Add reST version of the documentation

docs/conf.py

@@ -23,5 +23,5 @@
 # -- Options for HTML output -------------------------------------------------
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
 
-html_theme = 'alabaster'
+html_theme = 'nature'
 html_static_path = ['_static']

docs/index.rst

@@ -11,6 +11,12 @@ Welcome to LunarML's documentation!
    :caption: Contents:
 
    intro
+   usage
+   language
+   library
+   ml-basis-system
+   lua
+   javascript
 
 Indices and tables
 ==================

docs/intro.rst

@@ -9,9 +9,9 @@ Features
 LunarML supports full SML '97 language, including module system.
 LunarML also supports some of Successor ML features and other language extensions.
 
-A subset of SML Basis Library is supported.
+A subset of :ref:`SML Basis Library <sml-basis-library>` is supported.
 
-For multi-file project, ML Basis system is supported.
+For multi-file project, :ref:`ML Basis system <ml-basis-system>` is supported.
 
 The program can communicate with other Lua or JavaScript code.
 
@@ -74,73 +74,3 @@ Alternatively, you can use Docker to build and run LunarML::
   $ docker run --rm -v "$(pwd)":/work -w /work --platform linux/amd64 lunarml:0.1.0 lunarml compile example/hello.sml
   $ lua example/hello.lua
   Hello world!
-
-Usage
------
-
-The ``lunarml`` command takes a subcommand, zero or more options, and an input.
-Example::
-
-  lunarml compile [options] input.(sml|mlb)
-
-Supported subcommands are:
-
-``compile``
-  Compile a program.
-
-``help``
-  Show help.
-
-``version``
-  Show version information.
-
-``compile`` subcommand
-^^^^^^^^^^^^^^^^^^^^^^
-
-You can specify one of the target options, and specify output type.
-
-Target options are:
-
-``--lua`` (default)
-  Targets Lua 5.3/5.4.
-
-``--lua-continuations``
-  Targets Lua 5.3/5.4.
-  Supports one-shot delimited continuations.
-  Also, supports deeply nested ``handle``.
-
-``--luajit``
-  Targets LuaJIT.
-
-``--nodejs``
-  Produces JavaScript program for Node.js.
-  The produced JavaScript code is for ES2020 or later.
-  The default extension for output is ``.mjs``.
-
-``--nodejs-cps``
-  Produces JavaScript program for Node.js.
-  The produced JavaScript code is for ES2020 or later.
-  This mode supports delimited continuations.
-  The default extension for output is ``.mjs``.
-
-Output type is one of:
-
-``--exe`` (default)
-  Produce a program to be run by an interpreter.
-
-``--lib``
-  Produces a module to be loaded by other Lua/JavaScript programs.
-
-Other options are:
-
-``-o<file.ext>``, ``--output=<file.ext>``
-  Specify a filename to output.
-
-``--mlb-path-map=<file>``
-  Specify an MLB path map.
-
-``--mlb-path-var=<var>=<path>``
-  Specify an MLB path variable.
-
-``--default-ann <annotation>``
-  Specify an MLB annotatinon.

docs/javascript.rst

@@ -0,0 +1,111 @@
+JavaScript interface
+====================
+
+JavaScript features are accessible via :ref:`javascript-structure`.
+
+ES modules can be imported with ``_esImport`` declaration: :ref:`importing-ecmascript-modules`.
+
+ES export
+---------
+
+To produce an ES module, use ``--lib`` compiler option and define a variable or structure named ``export``.
+
+For example,
+
+::
+
+   val export = <some value>;
+
+will compile to
+
+::
+
+   export default <some value>;
+
+and
+
+.. code-block:: sml
+
+   structure export = struct
+     val foo = "string"
+     val bar = 42
+     val fun' = "fun" (* SML keywords can be escaped by suffixing with a prime *)
+   end
+
+will compile to:
+
+.. code-block:: javascript
+
+   const foo = "string";
+   const bar = 42;
+   const fun = "fun";
+   export { foo, bar, fun };
+
+Note on CPS mode: You cannot call certain functions including ``print`` at top-level, because they are "async".
+In future, this limitation may be lifted by using top-level await.
+
+Internal representation
+-----------------------
+
+Warning: The internal representation of data types may change in the future.
+Do not rely on it!
+
+``unit`` (empty record)
+   ``undefined``.
+
+``bool``
+   JavaScript's boolean; ``true`` or ``false``.
+
+``int``
+   54-bit signed integer, as a subset of Number.
+   Overflows are always checked.
+
+``word``
+   32-bit unsigned integer, as a subset of Number.
+   The sign of zero must be positive.
+
+``real``
+   64-bit floating-point number (JavaScript's native Number).
+
+``char``
+   8-bit unsigned integer.
+   The sign of zero must be positive.
+
+``string``
+   ``Uint8Array``. Must not be modified.
+
+``WideChar.char``
+   16-bit unsigned integer.
+   The sign of zero must be positive.
+
+``WideString.string``
+   16-bit string (JavaScript's native String).
+
+``Int54.int``
+   54-bit signed integer, as a subset of Number (close to "safe integer").
+   The range is :math:`[-2^{53},2^{53}-1]`.
+   The sign of zero may be negative.
+   Overflows are always checked.
+
+``Int64.int``
+   BigInt.
+   Overflows are always checked.
+
+``IntInf.int``
+   BigInt.
+
+``Word64.word``
+   BigInt.
+
+``'a vector``
+   Array.
+   Must not be modified.
+
+``'a array``
+   Array.
+
+``JavaScript.value``
+   Any JavaScript value, including ``undefined`` or ``null``.
+
+Non-empty record
+   ``{ "0": <#1 of the record>, "foo": <#foo of the record> }``