* initial conversion of docs from restructured text to markdown
M .hgignore +1 -1
@@ 27,7 27,7 @@ syntax: regexp
 ^testing/test\.o$
 ^testing/(_)?test\.wasm$
 ^scopes[.]h$
-^doc/_build/
+^doc/site
 ^bin/
 ^src/known_symbols.hpp
 ^Makefile$

          
M doc/Makefile +11 -160
@@ 1,177 1,28 @@ 
-# Makefile for Sphinx documentation
+# Makefile for MkDocs documentation
 #
 
 # You can set these variables from the command line.
-SPHINXOPTS    =
-SPHINXBUILD   = sphinx-build
-PAPER         =
-BUILDDIR      = _build
+MKDOCSOPTS    =
+MKDOCS        = mkdocs
+BUILDDIR      = site
 
-# User-friendly check for sphinx-build
-ifeq ($(shell which $(SPHINXBUILD) >/dev/null 2>&1; echo $$?), 1)
-$(error The '$(SPHINXBUILD)' command was not found. Make sure you have Sphinx installed, then set the SPHINXBUILD environment variable to point to the full path of the '$(SPHINXBUILD)' executable. Alternatively you can add the directory with the executable to your PATH. If you don't have Sphinx installed, grab it from http://sphinx-doc.org/)
+# User-friendly check for MkDocs
+ifeq ($(shell which $(MKDOCS) >/dev/null 2>&1; echo $$?), 1)
+$(error The '$(MKDOCS)' command was not found. Make sure you have MkDocs installed, then set the MKDOCS environment variable to point to the full path of the '$(MKDOCS)' executable. Alternatively you can add the directory with the executable to your PATH. If you don't have MkDocs installed, grab it from https://www.mkdocs.org/)
 endif
 
 # Internal variables.
-PAPEROPT_a4     = -D latex_paper_size=a4
-PAPEROPT_letter = -D latex_paper_size=letter
-ALLSPHINXOPTS   = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) .
-# the i18n builder cannot share the environment and doctrees with the others
-I18NSPHINXOPTS  = $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) .
-
-.PHONY: help clean html dirhtml singlehtml pickle json htmlhelp qthelp devhelp epub latex latexpdf text man changes linkcheck doctest gettext
+.PHONY: help clean html
 
 help:
 	@echo "Please use \`make <target>' where <target> is one of"
+	@echo "  clean      to discard generated documentation"
 	@echo "  html       to make standalone HTML files"
-	@echo "  dirhtml    to make HTML files named index.html in directories"
-	@echo "  singlehtml to make a single large HTML file"
-	@echo "  pickle     to make pickle files"
-	@echo "  json       to make JSON files"
-	@echo "  htmlhelp   to make HTML files and a HTML help project"
-	@echo "  qthelp     to make HTML files and a qthelp project"
-	@echo "  devhelp    to make HTML files and a Devhelp project"
-	@echo "  epub       to make an epub"
-	@echo "  latex      to make LaTeX files, you can set PAPER=a4 or PAPER=letter"
-	@echo "  latexpdf   to make LaTeX files and run them through pdflatex"
-	@echo "  latexpdfja to make LaTeX files and run them through platex/dvipdfmx"
-	@echo "  text       to make text files"
-	@echo "  man        to make manual pages"
-	@echo "  texinfo    to make Texinfo files"
-	@echo "  info       to make Texinfo files and run them through makeinfo"
-	@echo "  gettext    to make PO message catalogs"
-	@echo "  changes    to make an overview of all changed/added/deprecated items"
-	@echo "  xml        to make Docutils-native XML files"
-	@echo "  pseudoxml  to make pseudoxml-XML files for display purposes"
-	@echo "  linkcheck  to check all external links for integrity"
-	@echo "  doctest    to run all doctests embedded in the documentation (if enabled)"
 
 clean:
 	rm -rf $(BUILDDIR)/*
 
 html:
-	$(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html
-	@echo
-	@echo "Build finished. The HTML pages are in $(BUILDDIR)/html."
-
-dirhtml:
-	$(SPHINXBUILD) -b dirhtml $(ALLSPHINXOPTS) $(BUILDDIR)/dirhtml
-	@echo
-	@echo "Build finished. The HTML pages are in $(BUILDDIR)/dirhtml."
-
-singlehtml:
-	$(SPHINXBUILD) -b singlehtml $(ALLSPHINXOPTS) $(BUILDDIR)/singlehtml
-	@echo
-	@echo "Build finished. The HTML page is in $(BUILDDIR)/singlehtml."
-
-pickle:
-	$(SPHINXBUILD) -b pickle $(ALLSPHINXOPTS) $(BUILDDIR)/pickle
-	@echo
-	@echo "Build finished; now you can process the pickle files."
-
-json:
-	$(SPHINXBUILD) -b json $(ALLSPHINXOPTS) $(BUILDDIR)/json
-	@echo
-	@echo "Build finished; now you can process the JSON files."
-
-htmlhelp:
-	$(SPHINXBUILD) -b htmlhelp $(ALLSPHINXOPTS) $(BUILDDIR)/htmlhelp
-	@echo
-	@echo "Build finished; now you can run HTML Help Workshop with the" \
-	      ".hhp project file in $(BUILDDIR)/htmlhelp."
-
-qthelp:
-	$(SPHINXBUILD) -b qthelp $(ALLSPHINXOPTS) $(BUILDDIR)/qthelp
-	@echo
-	@echo "Build finished; now you can run "qcollectiongenerator" with the" \
-	      ".qhcp project file in $(BUILDDIR)/qthelp, like this:"
-	@echo "# qcollectiongenerator $(BUILDDIR)/qthelp/Scopes.qhcp"
-	@echo "To view the help file:"
-	@echo "# assistant -collectionFile $(BUILDDIR)/qthelp/Scopes.qhc"
-
-devhelp:
-	$(SPHINXBUILD) -b devhelp $(ALLSPHINXOPTS) $(BUILDDIR)/devhelp
-	@echo
-	@echo "Build finished."
-	@echo "To view the help file:"
-	@echo "# mkdir -p $$HOME/.local/share/devhelp/Scopes"
-	@echo "# ln -s $(BUILDDIR)/devhelp $$HOME/.local/share/devhelp/Scopes"
-	@echo "# devhelp"
-
-epub:
-	$(SPHINXBUILD) -b epub $(ALLSPHINXOPTS) $(BUILDDIR)/epub
-	@echo
-	@echo "Build finished. The epub file is in $(BUILDDIR)/epub."
-
-latex:
-	$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
+	$(MKDOCS) $(MKDOCSOPTS) build -d $(BUILDDIR)
 	@echo
-	@echo "Build finished; the LaTeX files are in $(BUILDDIR)/latex."
-	@echo "Run \`make' in that directory to run these through (pdf)latex" \
-	      "(use \`make latexpdf' here to do that automatically)."
-
-latexpdf:
-	$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
-	@echo "Running LaTeX files through pdflatex..."
-	$(MAKE) -C $(BUILDDIR)/latex all-pdf
-	@echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex."
-
-latexpdfja:
-	$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
-	@echo "Running LaTeX files through platex and dvipdfmx..."
-	$(MAKE) -C $(BUILDDIR)/latex all-pdf-ja
-	@echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex."
-
-text:
-	$(SPHINXBUILD) -b text $(ALLSPHINXOPTS) $(BUILDDIR)/text
-	@echo
-	@echo "Build finished. The text files are in $(BUILDDIR)/text."
-
-man:
-	$(SPHINXBUILD) -b man $(ALLSPHINXOPTS) $(BUILDDIR)/man
-	@echo
-	@echo "Build finished. The manual pages are in $(BUILDDIR)/man."
-
-texinfo:
-	$(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo
-	@echo
-	@echo "Build finished. The Texinfo files are in $(BUILDDIR)/texinfo."
-	@echo "Run \`make' in that directory to run these through makeinfo" \
-	      "(use \`make info' here to do that automatically)."
-
-info:
-	$(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo
-	@echo "Running Texinfo files through makeinfo..."
-	make -C $(BUILDDIR)/texinfo info
-	@echo "makeinfo finished; the Info files are in $(BUILDDIR)/texinfo."
-
-gettext:
-	$(SPHINXBUILD) -b gettext $(I18NSPHINXOPTS) $(BUILDDIR)/locale
-	@echo
-	@echo "Build finished. The message catalogs are in $(BUILDDIR)/locale."
-
-changes:
-	$(SPHINXBUILD) -b changes $(ALLSPHINXOPTS) $(BUILDDIR)/changes
-	@echo
-	@echo "The overview file is in $(BUILDDIR)/changes."
-
-linkcheck:
-	$(SPHINXBUILD) -b linkcheck $(ALLSPHINXOPTS) $(BUILDDIR)/linkcheck
-	@echo
-	@echo "Link check complete; look for any errors in the above output " \
-	      "or in $(BUILDDIR)/linkcheck/output.txt."
-
-doctest:
-	$(SPHINXBUILD) -b doctest $(ALLSPHINXOPTS) $(BUILDDIR)/doctest
-	@echo "Testing of doctests in the sources finished, look at the " \
-	      "results in $(BUILDDIR)/doctest/output.txt."
-
-xml:
-	$(SPHINXBUILD) -b xml $(ALLSPHINXOPTS) $(BUILDDIR)/xml
-	@echo
-	@echo "Build finished. The XML files are in $(BUILDDIR)/xml."
-
-pseudoxml:
-	$(SPHINXBUILD) -b pseudoxml $(ALLSPHINXOPTS) $(BUILDDIR)/pseudoxml
-	@echo
-	@echo "Build finished. The pseudo-XML files are in $(BUILDDIR)/pseudoxml."
+	@echo "Build finished. The HTML pages are in $(BUILDDIR)/."

          
M doc/build_reference.sc +118 -46
@@ 6,17 6,18 @@ import UTF-8
 let char = UTF-8.char
 
 let argc argv = (launch-args)
-assert (argc >= 2)
+assert (argc >= 3)
 let scriptpath =
     string (argv @ 1)
 let modulepath module =
-    if (argc < 3)
+    if ((string (argv @ 2)) == "core.sc")
         _ "core.sc" (globals)
     else
         let modulepath =
             string (argv @ 2)
         _ modulepath
             (require-from module-dir modulepath) as Scope
+let chapter = (string (argv @ 3))
 
 let module = (module as Scope)
 

          
@@ 82,8 83,10 @@ fn member-key (x)
     let s = (key as string)
     s
 
+let asterisk-char = 42:i8 # "*"
+
 fn docstring-is-complete (str)
-    (slice str 0 2) == ".."
+    str @ 0 == asterisk-char
 
 fn repeat-string (n c)
     loop (i s = 0:usize "")

          
@@ 92,17 95,43 @@ fn repeat-string (n c)
         _ (i + 1:usize)
             .. s c
 
-fn write-docstring (tab str)
+fn write-docstring (docstring-indent tab str)
     let c = (countof str)
     if (c > 0)
         io-write! tab
-        io-write! "\n"
-        io-write! tab
         for i in (range c)
             let s = (slice str i (i + 1))
             io-write! s
             if ((s == "\n") and ((i + 1) != c))
-                io-write! tab
+                io-write! docstring-indent
+
+fn get-defstring (def-parent-name def-type def-name)
+    # e.g. *type*{.property} `Array`{.descname} [](#scopes.type.Array "Permalink to this definition"){.headerlink} {#scopes.type.Array}
+    let parent-name =
+        if (empty? def-parent-name)
+            "scopes"
+        else
+            "scopes." .. def-parent-name
+    let def-id = (parent-name .. "." .. def-type .. "." .. def-name)
+    return ("*" .. def-type .. "*{.property} " ..
+            "`" .. def-name .. "`{.descname} " ..
+            "[](#" .. def-id .. " \"Permalink to this definition\"){.headerlink} " ..
+            "{#" .. def-id .. "}")
+
+fn get-fnstring (fn-parent-name fn-type fn-name fn-args)
+    # e.g. *fn*{.property} `__@`{.descname} (self index) [](#scopes.type.Array "Permalink to this definition"){.headerlink} {#scopes.fn.__@}
+    let parent-name =
+        if (empty? fn-parent-name)
+            "scopes"
+        else
+            "scopes." .. fn-parent-name
+
+    let fn-id = (parent-name .. "." .. fn-type .. "." .. fn-name)
+    return ("*" .. fn-type .. "*{.property} " ..
+            "`" .. fn-name .. "`{.descname} " ..
+            (? (empty? fn-args) "()" ("(*&ensp;" .. fn-args .. "&ensp;*)")) ..
+            "[](#" .. fn-id .. " \"Permalink to this definition\"){.headerlink} " ..
+            "{#" .. fn-id .. "}")
 
 fn print-entry (module parent key entry parent-name opts...)
     let print-entry = this-function

          
@@ 133,17 162,21 @@ fn print-entry (module parent key entry 
         if has-docstr (docstr as string)
         else ""
     let indent =
-        if typemember? "   "
+        if typemember? "    "
         else ""
+    let docstring-indent =
+        if typemember? "        "
+        else "    "
     let tab =
-        if typemember? "      "
+        if typemember? "   "
         else "   "
     if (docstring-is-complete docstr)
         if typemember?
-            write-docstring indent docstr
+            io-write! indent
+            write-docstring indent "" docstr
         else
             io-write! docstr
-            io-write! "\n"
+        io-write! "\n"
         return;
     if (T == Closure)
         let func = (entry as Closure)

          
@@ 155,51 188,74 @@ fn print-entry (module parent key entry 
             io-write! "\n"
         else
             io-write! indent
-            if (sc_template_is_inline label)
-                io-write! ".. inline:: ("
-            else
-                io-write! ".. fn:: ("
-            io-write! key
+
+            local args = ""
             let count = (sc_template_parameter_count label)
             for i in (range count)
                 let param = (sc_template_parameter label i)
-                io-write! " "
-                io-write! ((sc_parameter_name param) as string)
-            io-write! ")\n"
+                args ..= ((sc_parameter_name param) as string)
+                if (i < (count - 1))
+                    args ..= " "
+
+            io-write! (get-fnstring parent-name (? (sc_template_is_inline label) "inline" "fn") key args)
+            io-write! "\n\n"
+            io-write! indent
+            io-write! ":"
+
             if (empty? docstr)
-                write-docstring tab docstr2
+                if (empty? docstr2)
+                    write-docstring docstring-indent tab "\n"
+                else
+                    write-docstring docstring-indent tab docstr2
             else
-                write-docstring tab docstr
+                write-docstring docstring-indent tab docstr
+
+            io-write! "\n"
         return;
     elseif (T == Builtin)
         io-write! indent
-        io-write! ".. builtin:: ("
-        io-write! key
-        io-write! " ...)\n"
+        io-write! (get-fnstring parent-name "builtin" key "...")
+        io-write! "\n\n"
+        io-write! indent
+        io-write! ":"
     elseif (T == SugarMacro)
         io-write! indent
-        io-write! ".. sugar:: ("
-        io-write! key
-        io-write! " ...)\n"
+
+        let parent-name =
+            if (empty? parent-name)
+                "scopes"
+            else
+                "scopes." .. parent-name
+        let sugar-id = (parent-name .. ".sugar." .. key)
+        io-write! (
+            "*sugar*{.property} (`" .. key .. "`{.descname} *&ensp;...&ensp;*)" ..
+            " [](#" .. sugar-id .. " \"Permalink to this definition\"){.headerlink} " ..
+            "{#" .. sugar-id .. "}")
+
+        io-write! "\n\n"
+        io-write! indent
+        io-write! ":"
     elseif (T == SpiceMacro)
         io-write! indent
-        io-write! ".. spice:: ("
-        io-write! key
-        io-write! " ...)\n"
+        io-write! (get-fnstring parent-name "spice" key "...")
+        io-write! "\n\n"
+        io-write! indent
+        io-write! ":"
     elseif (T == type)
         if (typemember? and (not has-docstr))
             return;
         let ty = (entry as type)
         io-write! indent
-        io-write! ".. type:: "
-        io-write! key
+        io-write! (get-defstring parent-name "type" key)
         let superT = ('superof ty)
         let ST =
             if ('opaque? ty) Unknown
             else ('storageof ty)
         io-write! "\n\n"
+        io-write! indent
+        io-write! ":"
         if has-docstr
-            write-docstring tab docstr
+            write-docstring docstring-indent tab docstr
             io-write! "\n"
         else
             io-write! tab

          
@@ 216,9 272,9 @@ fn print-entry (module parent key entry 
             io-write! " type"
             let tystr = (tostring ty)
             if ((let tystr = (tostring ty)) != key)
-                io-write! " labeled ``"
+                io-write! " labeled `"
                 io-write! (tostring ty)
-                io-write! "``"
+                io-write! "`"
             if (superT != typename)
                 io-write! " of supertype `"
                 io-write! (tostring superT)

          
@@ 246,18 302,24 @@ fn print-entry (module parent key entry 
         let fntype = ('element@ T 0)
         let params = ('element-count fntype)
         io-write! indent
-        io-write! ".. compiledfn:: ("
-        io-write! key
-        io-write! " ...)\n\n"
+        io-write! (get-fnstring parent-name "compiledfn" key "...")
+        io-write! "\n\n"
+        io-write! indent
+        io-write! ":"
         io-write! tab
         io-write! "A"
         if (('kind entry) == value-kind-global)
             io-write! "n external"
         else
             io-write! " compiled"
-        io-write! " function of type ``"
+        io-write! " function of type `"
         io-write! (tostring fntype)
-        io-write! "``.\n"
+        io-write! "`.\n"
+
+        if (not has-docstr)
+            io-write! "\n"
+            return;
+
     elseif (T == Unknown)
         # a dreaded curse!
         return;

          
@@ 265,19 327,29 @@ fn print-entry (module parent key entry 
         if (typemember? and (not has-docstr))
             return;
         io-write! indent
-        io-write! ".. define:: "
-        io-write! key
-        io-write! "\n"
+        io-write! (get-defstring parent-name "define" key)
+        io-write! "\n\n"
+        io-write! indent
+        io-write! ":"
         if (not has-docstr)
-            io-write! "\n"
             io-write! tab
             io-write! "A constant of type `"
             io-write! (tostring T)
-            io-write! "`.\n"
-    write-docstring tab docstr
+            io-write! "`.\n\n"
+            return;
+
+    if (not has-docstr)
+        write-docstring docstring-indent tab "\n"
+    else
+        write-docstring docstring-indent tab docstr
+
+    io-write! "\n"
 
 let moduledoc = ('module-docstring module)
 if (not (empty? moduledoc))
+    io-write! "<style type=\"text/css\" rel=\"stylesheet\">"
+    io-write! ("body { counter-reset: chapter " .. chapter .. "; }")
+    io-write! "</style>\n\n"
     io-write! (moduledoc as string)
     io-write! "\n"
 

          
M doc/docs/about.md +4 -0
@@ 1,3 1,7 @@ 
+<style type="text/css" rel="stylesheet">
+body { counter-reset: chapter 1; }
+</style>
+
 About Scopes
 ============
 

          
M doc/docs/architecture.md +8 -9
@@ 3,14 3,13 @@ Architecture
 
 Scopes understands and transforms source code in multiple cleanly separated stages:
 
-=====  ===========  =======================  ======================
-Order  Stage        From                     To
-=====  ===========  =======================  ======================
-1      Parsing      Data Interchange Format  S-Expression Tree
-2      Expansion    S-Expression Tree        Untyped Scopes AST
-3      Checking     Untyped Scopes AST       Typed Scopes IL
-4      Translation  Typed Scopes IL          LLVM IR / SPIR-V
-5      Execution    LLVM IR / SPIR-V         Program Output
-=====  ===========  =======================  ======================
+Order |Stage       |From                    |To
+------|------------|------------------------|----------------------
+1     |Parsing     |Data Interchange Format |S-Expression Tree
+2     |Expansion   |S-Expression Tree       |Untyped Scopes AST
+3     |Checking    |Untyped Scopes AST      |Typed Scopes IL
+4     |Translation |Typed Scopes IL         |LLVM IR / SPIR-V
+5     |Execution   |LLVM IR / SPIR-V        |Program Output
+
 
 TODO
  No newline at end of file

          
M doc/docs/capi.md +1 -1
@@ 2,6 2,6 @@ C API Reference
 ===============
 
 The Scopes C API can be used from within Scopes programs and as a C library, and is
-defined in ``scopes.h``.
+defined in `scopes.h`.
 
 This chapter will provide usage and reference information in a future release.

          
M doc/docs/cpp_users.md +319 -322
@@ 1,3 1,7 @@ 
+<style type="text/css" rel="stylesheet">
+body { counter-reset: chapter 4; }
+</style>
+
 Scopes for C/C++ Users
 ======================
 

          
@@ 26,8 30,8 @@ compilation and as foundation for a buil
 When building objects with Scopes, certain restrictions apply. The generated
 object file has no ties to the Scopes runtime, and so the corresponding Scopes
 code must not use any first-class objects as constants. Instead, such code may
-use the ``sc_*`` functions exported by the Scopes runtime, but must be linked
-with ``libscopesrt`` to make those symbols available.
+use the `sc_*` functions exported by the Scopes runtime, but must be linked
+with `libscopesrt` to make those symbols available.
 
 Compiler Errors
 ---------------

          
@@ 49,7 53,7 @@ WinDbg, or by what is commonly referred 
 Scopes generates DWARF/COFF debug information for its programs and therefore
 supports step debuggers like GDB which understand the format.
 
-.. note::
+!!! attention
 
     At the time of writing, due to a limitation in LLVM, debug information
     generated at runtime is currently not available on Windows. Object

          
@@ 78,16 82,16 @@ Symbols
 -------
 
 For symbolic tokens that can be used to bind names to values and types, C
-accepts the character set of ``0-9A-Za-z_``. This allows users to concatenate
-many tokens without separating whitespace, such as in ``x+y``.
+accepts the character set of `0-9A-Za-z_`. This allows users to concatenate
+many tokens without separating whitespace, such as in `x+y`.
 
 Instead of a list of allowed characters, Scopes instead maintains an exclusion
 list of characters that terminate a symbolic sequence. These characters are
-the whitespace characters and characters from the set ``()[]{}"';#,``, where
-``,`` is in itself a context-free symbol.
+the whitespace characters and characters from the set `()[]{}"';#,`, where
+`,` is in itself a context-free symbol.
 
-This means that ``x+y`` would be read as a single token. A semantically-\
-equivalent expression in Scopes would have to be written as ``x + y``. See
+This means that `x+y` would be read as a single token. A semantically-\
+equivalent expression in Scopes would have to be written as `x + y`. See
 :doc:`dataformat` for details.
 
 Keywords

          
@@ 97,7 101,7 @@ C/C++ uses many different declarative fo
 during parsing using specific keywords. Like many other Scheme-likes, Scopes
 only parses programs as symbolic lists and postpones the interpretation of
 declarations until the last possible moment, expecting all expressions to follow
-just one basic form::
+just one basic form:
 
     # classic braced expression
     (head argument1 ... argumentN)

          
@@ 116,7 120,7 @@ The value and type of the head controls 
   further, or a template IL.
 * An IL macro (called a `spice`), called at compile time, which receives typed
   arguments and can generate new template IL to be specialized.
-* A call expression, equivalent to the ``head(argument1, ..., argumentN);``
+* A call expression, equivalent to the `head(argument1, ..., argumentN);`
   syntax in C/C++, called at runtime.
 
 As a result of this principle, there are no keywords in Scopes. Every single

          
@@ 148,7 152,7 @@ An infix expression is recognized by loo
 second token of an expression. If a matching definition is found, all tokens
 within that expression are treated as left/right-hand arguments and operators.
 
-The infix expression must follow the pattern ``(x0 op x1 op ... op xN)`` to be
+The infix expression must follow the pattern `(x0 op x1 op ... op xN)` to be
 recognized. If an odd argument is not a valid infix token, a syntax error
 will be raised.
 

          
@@ 157,8 161,8 @@ postfix expressions to keep confusion to
 can be entirely disabled by replacing the default wildcard sugar.
 
 A special symbol sugar exists which aims to simplify trivial container lookups.
-An expression like ``(object . attribute . attribute)`` can also be written
-as a single symbol, ``object.attribute.attribute``, which will be expanded
+An expression like `(object . attribute . attribute)` can also be written
+as a single symbol, `object.attribute.attribute`, which will be expanded
 to the former form, provided no value is already bound to this symbol in the
 current scope.
 

          
@@ 168,32 172,32 @@ Declarations, Statements and Expressions
 C/C++ distinguishes between three major lexical contexts: declaration level,
 statement level and expression level.
 
-.. code-block:: c++
+```c++
+// declaration level
+typedef int MyInt;
 
-    // declaration level
-    typedef int MyInt;
-
-    // illegal at this level
-    // printf("hello!\n");
+// illegal at this level
+// printf("hello!\n");
 
-    MyInt test (MyInt x) {
-        // statement level
-        int k =
-            // expression level
-            x * x
-        ;
-        int m = ({
-            // statement expressions, a GCC extension
-            // usage of statements here is legal.
-            printf("hello again!\n");
-            k * k;
-        });
-        return m;
-    }
+MyInt test (MyInt x) {
+    // statement level
+    int k =
+        // expression level
+        x * x
+    ;
+    int m = ({
+        // statement expressions, a GCC extension
+        // usage of statements here is legal.
+        printf("hello again!\n");
+        k * k;
+    });
+    return m;
+}
+```
 
 Scopes does not make such a distinction, and instead treats every declaration
 as an expression with a result type. The top level of a program is equivalent
-to its main function::
+to its main function:
 
     # the right hand side is not limited to constant expressions.
     let MyInt = int

          
@@ 216,38 220,38 @@ Constants and Variables
 -----------------------
 
 C/C++ expects named values to be declared with a type. Each value is mutable
-by default unless qualified by ``const``. Outside of a function it represents
+by default unless qualified by `const`. Outside of a function it represents
 a globally accessible value, within a function it represents a stack value.
 
-.. code-block:: c++
-
-    const int constant = 100;
+```c++
+const int constant = 100;
 
-    // a global value mapped to data segment
-    int variable1 = 0;
-    int variable2 = 0;
+// a global value mapped to data segment
+int variable1 = 0;
+int variable2 = 0;
 
-    // conceptually a copy operation
-    const int variable1_copy = variable1;
+// conceptually a copy operation
+const int variable1_copy = variable1;
 
-    void test () {
-        // conceptually declared on the stack
-        // initialization from value conceptually a copy operation
-        int variable3 = constant;
+void test () {
+    // conceptually declared on the stack
+    // initialization from value conceptually a copy operation
+    int variable3 = constant;
 
-        // mutable by default
-        variable3 = variable2;
+    // mutable by default
+    variable3 = variable2;
 
-        printf("%i\n", constant);
-        printf("%i\n", variable1);
-        printf("%i\n", variable2);
-        printf("%i\n", variable3);
-    }
+    printf("%i\n", constant);
+    printf("%i\n", variable1);
+    printf("%i\n", variable2);
+    printf("%i\n", variable3);
+}
+```
 
 In Scopes, expressions are bound to names using `let`, which only binds an
 expression or value to a name. The type of the value and where it is stored
 depends entirely on the expression that produces it. The `local` and `global`
-forms must be used to explicitly allocate a stack or data segment value::
+forms must be used to explicitly allocate a stack or data segment value:
 
     # a compile time constant integer
     let constant = 100

          
@@ 278,7 282,7 @@ forms must be used to explicitly allocat
 
 Unlike in C/C++, declarations of the same name within the same scope are
 permitted, and the previous binding is still accessible during evaluation
-of the right-hand side::
+of the right-hand side:
 
     let x = 1
     # x is now bound to the value 3

          
@@ 292,7 296,7 @@ Lexical Scope
 Both C/C++ and Scopes employ lexical scope to control visibility of bound names.
 
 Unlike in C/C++, lexical scope is a first order object in Scopes and can be used
-by new declarative forms as well as to export symbols from modules::
+by new declarative forms as well as to export symbols from modules:
 
     let scope =
         do

          
@@ 342,43 346,43 @@ C++14, templates can now also deduct the
 declared, but forward declared templates with automatic return type can not
 be instantiated.
 
-.. code-block:: c++
-
-    // forward declaration of typed function
-    int typed_forward_decl (int x, const char *text, bool toggle);
+```c++
+// forward declaration of typed function
+int typed_forward_decl (int x, const char *text, bool toggle);
 
-    // declaration of typed function
-    int typed_decl (int x, const char *text, bool toggle) {
-        return 0;
-    }
+// declaration of typed function
+int typed_decl (int x, const char *text, bool toggle) {
+    return 0;
+}
 
-    // forward declaration of template
-    template<typename A, typename B, typename C>
-    void lazy_typed_decl_returns_void (A a, B b, C c);
+// forward declaration of template
+template<typename A, typename B, typename C>
+void lazy_typed_decl_returns_void (A a, B b, C c);
 
-    void test1 () {
-        // forward declaration can be used
-        lazy_typed_decl_returns_void(1,2,3);
-    }
+void test1 () {
+    // forward declaration can be used
+    lazy_typed_decl_returns_void(1,2,3);
+}
 
-    // forward declaration of template with auto return type
-    template<typename A, typename B, typename C>
-    auto lazy_typed_decl_returns_auto (A a, B b, C c);
+// forward declaration of template with auto return type
+template<typename A, typename B, typename C>
+auto lazy_typed_decl_returns_auto (A a, B b, C c);
 
-    void test2 () {
-        // error: use before deduction of ‘auto’
-        lazy_typed_decl_returns_auto(1,2,3);
-    }
+void test2 () {
+    // error: use before deduction of ‘auto’
+    lazy_typed_decl_returns_auto(1,2,3);
+}
 
-    // implementation of template with auto return type
-    template<typename A, typename B, typename C>
-    auto lazy_typed_decl_returns_auto (A a, B b, C c) {
-        return 0;
-    }
+// implementation of template with auto return type
+template<typename A, typename B, typename C>
+auto lazy_typed_decl_returns_auto (A a, B b, C c) {
+    return 0;
+}
+```
 
 In Scopes, all function declarations are lazily typed, and `static-typify` can
 be used to instantiate concrete functions at compile time. Forward declarations
-are possible but must be completed within the same scope::
+are possible but must be completed within the same scope:
 
     # forward declarations can not be typed
     #fn typed_forward_decl

          
@@ 417,15 421,15 @@ are possible but must be completed withi
 Variadic Arguments
 ------------------
 
-C introduced variadic arguments at runtime using the ``va_list`` type, in order
-to support variadic functions like ``printf()``. C++ improved upon this
+C introduced variadic arguments at runtime using the `va_list` type, in order
+to support variadic functions like `printf()`. C++ improved upon this
 concept by introducing variadic template arguments. It remains difficult to
 perform reflection on variadic arguments, such as iteration or targeted
 capturing.
 
 Functions in Scopes do not support runtime variadic functions (although calling
 variadic C functions is supported), but support compile time variadic arguments.
-See the following example::
+See the following example:
 
     # any trailing parameter ending in '...' is interpreted to be variadic.
     fn takes-varargs (x y rest...)

          
@@ 458,18 462,18 @@ C++ allows overloading of functions by s
 the same name but different type signatures. On call, the call arguments types
 are used to deduce the correct function to use:
 
-.. code-block:: c++
+```c++
+int overloaded (int a, int b) { return 0; }
+int overloaded (int a, float b) { return 1; }
+int overloaded (float a, int b) { return 2; }
 
-    int overloaded (int a, int b) { return 0; }
-    int overloaded (int a, float b) { return 1; }
-    int overloaded (float a, int b) { return 2; }
-
-    // this new form of overloaded could be specified in a different file
-    int overloaded (float a, float b) { return 3; }
+// this new form of overloaded could be specified in a different file
+int overloaded (float a, float b) { return 3; }
+```
 
 Scopes offers a similar mechanism as a library form, but requires that
 overloads are grouped at the time of declaration. The first form that
-matches argument types implicitly is selected, in order of declaration::
+matches argument types implicitly is selected, in order of declaration:
 
     fn... overloaded
     case (a : i32, b : i32)

          
@@ 517,7 521,7 @@ Using Third Party Libraries
 With C/C++, third party libraries are typically built in a separate build
 process provided by their developer, either as static or shared libraries.
 Their definitions are made available through include files that an author
-can embed into translation units using the ``#include`` preprocessing
+can embed into translation units using the `#include` preprocessing
 command. The libraries' precompiled symbols are typically merged into the
 executable during linking or at runtime, either when the process is mapped
 into memory or function pointers are loaded manually from the library.

          
@@ 532,7 536,7 @@ embedded directly into its translation u
 libraries' or module's functions are actually used.
 
 Scopes also supports embedding existing third party C libraries in the classical
-way, using `include`, `load-library` and `load-object`::
+way, using `include`, `load-library` and `load-object`:
 
     # how to create trivial bindings for a C library
 

          
@@ 562,7 566,7 @@ way, using `include`, `load-library` and
 
         locals;
 
-Externals using C signatures can also be defined and used directly::
+Externals using C signatures can also be defined and used directly:
 
     let puts = (extern 'puts (function i32 rawstring))
     # definition becomes immediately available

          
@@ 573,30 577,29 @@ Type Primitives
 
 C/C++'s type primitives map to Scopes in the following way:
 
-=============================================== =======================
-C++                                             Scopes
-=============================================== =======================
-`bool`                                          `bool`
-`int8_t`                                        `i8`
-`int16_t`                                       `i16`
-`int32_t`                                       `i32`
-`int64_t`                                       `i64`
-`uint8_t`                                       `u8`
-`uint16_t`                                      `u16`
-`uint32_t`                                      `u32`
-`uint64_t`                                      `u64`
-`float`                                         `f32`
-`double`                                        `f64`
-``typedef U V``                                 `let V = U`
-``using V = U``                                 `let V = U`
-`const T *`                                     `@ T`
-`T *`                                           `mutable (@ T)`
-`const T &`                                     `& T`
-`T &`                                           `mutable (& T)`
-``std::array<T, N>``                            `array T N`
-``std::tuple<T0, ..., Tn>``                     `tuple T0 ... Tn`
-``const T [N] __attribute__((aligned (A)))``    `vector T N`
-=============================================== =======================
+C++                                            |Scopes
+-----------------------------------------------|-----------------------
+`bool`                                         |`bool`
+`int8_t`                                       |`i8`
+`int16_t`                                      |`i16`
+`int32_t`                                      |`i32`
+`int64_t`                                      |`i64`
+`uint8_t`                                      |`u8`
+`uint16_t`                                     |`u16`
+`uint32_t`                                     |`u32`
+`uint64_t`                                     |`u64`
+`float`                                        |`f32`
+`double`                                       |`f64`
+`typedef U V`                                  |`let V = U`
+`using V = U`                                  |`let V = U`
+`const T *`                                    |`@ T`
+`T *`                                          |`mutable (@ T)`
+`const T &`                                    |`& T`
+`T &`                                          |`mutable (& T)`
+`std::array<T, N>`                             |`array T N`
+`std::tuple<T0, ..., Tn>`                      |`tuple T0 ... Tn`
+`const T [N] __attribute__((aligned (A)))`     |`vector T N`
+
 
 Initializer Lists
 -----------------

          
@@ 607,13 610,11 @@ fields without knowing their type. `type
 temporary closure which is turned into a constructor call as soon as the
 typeinit instance is cast to its target type during assignment.
 
-=========================================== =====================================
-C++                                         Scopes
-=========================================== =====================================
-`std::array<T> _ = { arg0, ..., argN };`    `arrayof T arg0 ... argN`
-`std::tuple<auto> _ = { arg0, ..., argN };` `tupleof arg0 ... argN`
-`x.member = { arg0, ..., argN };`           `x.member = (typeinit arg0 ... argN)`
-=========================================== =====================================
+C++                                         |Scopes
+--------------------------------------------|-------------------------------------
+`std::array<T> _ - { arg0, ..., argN };`    |`arrayof T arg0 ... argN`
+`std::tuple<auto> _ - { arg0, ..., argN };` |`tupleof arg0 ... argN`
+`x.member - { arg0, ..., argN };`           |`x.member - (typeinit arg0 ... argN)`
 
 Structs
 -------

          
@@ 624,19 625,19 @@ not permit composition by inheritance. C
 Compare this C++ example, which makes use of recently introduced default
 initializers and designated initializers:
 
-.. code-block:: c++
+```c++
+struct Example {
+    int value;
+    // default initializers only supported in C++11 and up
+    bool choice = false;
+    const char *text = "";
+};
 
-    struct Example {
-        int value;
-        // default initializers only supported in C++11 and up
-        bool choice = false;
-        const char *text = "";
-    };
+// designated initializers only supported in C99
+Example example = { .value = 100, .text = "test" };
+```
 
-    // designated initializers only supported in C99
-    Example example = { .value = 100, .text = "test" };
-
-to this equivalent declaration in Scopes::
+to this equivalent declaration in Scopes:
 
     using import struct
 

          
@@ 655,32 656,32 @@ Methods
 
 C++ introduced methods as a way to associate functions directly with structs
 and classes. In C++, the argument referencing the object argument is hidden
-and implicitly bound to the ``this`` symbol. Members and other methods of the
+and implicitly bound to the `this` symbol. Members and other methods of the
 struct are in the lexical scope of the method.
 
-.. code-block:: c++
-
-    // this example is a little contrived for illustrational purposes
-    struct Example {
-        int value;
+```c++
+// this example is a little contrived for illustrational purposes
+struct Example {
+    int value;
 
-        // a method declaration
-        int get_add_value (int n) {
-            return this->value + n;
-        }
-
-        // another method declaration
-        void print_value_plus_one () {
-            printf("%i\n", get_add_value(1));
-        }
-    };
-
-    void use_example (Example example) {
-        example.print_value_plus_one();
+    // a method declaration
+    int get_add_value (int n) {
+        return this->value + n;
     }
 
+    // another method declaration
+    void print_value_plus_one () {
+        printf("%i\n", get_add_value(1));
+    }
+};
+
+void use_example (Example example) {
+    example.print_value_plus_one();
+}
+```
+
 Scopes supports methods in a more explicit way that makes refactorings from
-function to method and back easier, both in declaration and in usage::
+function to method and back easier, both in declaration and in usage:
 
     struct Example plain
         value : i32

          
@@ 696,8 697,8 @@ function to method and back easier, both
         'print_value_plus_one example
 
 What happens here is that we call a quoted symbol with arguments. The call
-handler for the `Symbol` type rewrites ``'methodname object arg0 ... argN``
-as ``(getattr (typeof object) 'methodname) object arg0 ... argN``.
+handler for the `Symbol` type rewrites `'methodname object arg0 ... argN`
+as `(getattr (typeof object) 'methodname) object arg0 ... argN`.
 
 Virtual Methods
 ---------------

          
@@ 712,7 713,7 @@ Classes
 C++'s concept of classes is only indirectly supported through structs in Scopes.
 Access modifiers are not available, but methods can be made "private" by keeping
 their definition local. Fields can not be hidden, but they can be visibly
-marked as private by convention::
+marked as private by convention:
 
     struct Example plain
         # an underscore indicates that the attribute is not meant to be

          
@@ 741,19 742,19 @@ Template Classes
 C++ supports generics in the form of template classes, which are lazily typed
 structs.
 
-.. code-block:: c++
+```c++
+template<typename T, int x>
+struct Example {
+    T value;
 
-    template<typename T, int x>
-    struct Example {
-        T value;
-
-        bool compare () {
-            value == x;
-        }
-    };
+    bool compare () {
+        value == x;
+    }
+};
+```
 
 Scopes leverages constant expression folding and compile time closures to
-trivially provide this feature via `inline` functions::
+trivially provide this feature via `inline` functions:
 
     # a function decorator memoizes the result so we get the same type for
       the same arguments

          
@@ 770,30 771,30 @@ Partial template specialization allows t
 depending on instantiation arguments. The same mechanism is also used to do
 type-based dispatch. Here is an example:
 
-.. code-block:: c++
-
-    #include <stdlib.h>
+```c++
+#include <stdlib.h>
 
-    template<typename T> struct to_int {
-        // linker complains: missing symbol
-        int operator()(T x);
-    };
+template<typename T> struct to_int {
+    // linker complains: missing symbol
+    int operator()(T x);
+};
 
-    template<> struct to_int<int> {
-        int operator()(int x) {
-            return x;
-        }
-    };
+template<> struct to_int<int> {
+    int operator()(int x) {
+        return x;
+    }
+};
 
-    template<> struct to_int<const char *> {
-        int operator()(const char *x) {
-            return atoi(x);
-        }
-    };
+template<> struct to_int<const char *> {
+    int operator()(const char *x) {
+        return atoi(x);
+    }
+};
+```
 
 In Scopes, it is not necessary to create types in order to build single
 type based dispatch operators. Here are three ways to supply the same
-functionality::
+functionality:
 
     include "stdlib.h"
 

          
@@ 827,7 828,7 @@ A type implementing a method under this 
 it is used to construct both specialized types and to instantiate a type. Its
 first argument is the name of the type that has been called.
 
-Here is an example that changes the default constructor of a struct::
+Here is an example that changes the default constructor of a struct:
 
     struct Example plain
         _value : i32

          
@@ 847,27 848,27 @@ value goes out of scope. Destructors typ
 used to switch contexts. This is commonly used in C++ as part of a programming
 technique used to bind the life cycle of a resource to that of a corresponding
 object. This technique is generally referred to as *Resource Acquisition Is
-Initialization* or `RAII <https://en.cppreference.com/w/cpp/language/raii>`_,
+Initialization* or [RAII](https://en.cppreference.com/w/cpp/language/raii),
 in the C++ community, or as *Scope-Bound Resource Management* (SBRM).
 
-.. code-block:: c++
-
-    struct Handle {
-        void *_handle;
+```c++
+struct Handle {
+    void *_handle;
 
-        // constructor
-        Handle(void *handle) : _handle(handle) {}
-        // destructor
-        ~Handle() {
-            printf("destroying handle\n");
-            free(_handle);
-        }
-    };
+    // constructor
+    Handle(void *handle) : _handle(handle) {}
+    // destructor
+    ~Handle() {
+        printf("destroying handle\n");
+        free(_handle);
+    }
+};
+```
 
 Values of non-plain type, so-called unique types, are guaranteed to be
 referenced only at a single point within a program. Because of this guarantee,
 a unique type is able to supply a destructor through the `__drop` special method
-that is automatically called when the value goes out of scope::
+that is automatically called when the value goes out of scope:
 
     struct Handle
         _handle : voidstar

          
@@ 889,33 890,33 @@ Operator Overloading
 C++ allows overloading type operators through special methods defined either
 in a struct, class or namespace.
 
-..  code-block:: c++
+```c++
+class Accumulable {
+public:
+    // overload the addition operator for class + class
+    Accumulable operator +(Accumulable x) {
+        return Accumulable(this->value + x.value);
+    }
+    // another overload for class + int
+    Accumulable operator +(int x) {
+        return Accumulable(this->value + x);
+    }
 
-    class Accumulable {
-    public:
-        // overload the addition operator for class + class
-        Accumulable operator +(Accumulable x) {
-            return Accumulable(this->value + x.value);
-        }
-        // another overload for class + int
-        Accumulable operator +(int x) {
-            return Accumulable(this->value + x);
-        }
+    Accumulable (int _value) : value(_value) {}
+
+    int value;
+};
 
-        Accumulable (int _value) : value(_value) {}
-
-        int value;
-    };
-
-    // a third overload for supporting int + class
-    Accumulable operator +(Accumulable a, int b) {
-        return Accumulable(a.value + b.value);
-    }
+// a third overload for supporting int + class
+Accumulable operator +(Accumulable a, int b) {
+    return Accumulable(a.value + b.value);
+}
+```
 
 Scopes supports operator overloading through informally-specified operator
 protocols that any type can support by exposing dispatch methods bound to
 special attributes. See this equivalent example, which applies not only to
-structs, but any type definition::
+structs, but any type definition:
 
     struct Accumulable
         # one compile time function for all left-hand side variants receives

          
@@ 955,17 956,15 @@ by the `include` mechanism.
 At the time of writing, only a few containers from the C++ standard library
 have functional equivalents in Scopes yet. Here is a comparison table:
 
-======================= ====================
-C++                     Scopes
-======================= ====================
-``std::array``          `array`
-``std::tuple``          `tuple`
-``std::vector``         `Array.GrowingArray`
-``std::unordered_set``  `Map.Set`
-``std::unordered_map``  `Map.Map`
-``std::unique_ptr``     `Box.Box`
-``std::function``       `Capture.capture`
-======================= ====================
+C++                    |Scopes
+-----------------------|--------------------
+`std::array`           |`array`
+`std::tuple`           |`tuple`
+`std::vector`          |`Array.GrowingArray`
+`std::unordered_set`   |`Map.Set`
+`std::unordered_map`   |`Map.Map`
+`std::unique_ptr`      |`Box.Box`
+`std::function`        |`Capture.capture`
 
 Memory Handling & Management
 ----------------------------

          
@@ 978,24 977,22 @@ Scopes uses an identical model. No garba
 
 A comparison of concepts by example:
 
-=================================== ===================================
-C/C++                               Scopes
-=================================== ===================================
-``T value;`` (globally)             `global value : T`
-``T value;`` (locally)              `local value : T`
-``T values[size];`` (static size)   `local value : (array T size)`
-``T values[size];`` (dynamic size)  `let value = (alloca-array T size)`
-``alloca(sizeof(T))``               `alloca T`
-``alloca(sizeof(T) * size)``        `alloca-array T size`
-``malloc(sizeof(T))``               `malloc T`
-``malloc(sizeof(T) * size)``        `malloc-array T size`
-=================================== ===================================
+C/C++                              |Scopes
+-----------------------------------|-----------------------------------
+`T value;` (globally)              |`global value : T`
+`T value;` (locally)               |`local value : T`
+`T values[size];` (static size)    |`local value : (array T size)`
+`T values[size];` (dynamic size)   |`let value = (alloca-array T size)`
+`alloca(sizeof(T))`                |`alloca T`
+`alloca(sizeof(T) * size)`         |`alloca-array T size`
+`malloc(sizeof(T))`                |`malloc T`
+`malloc(sizeof(T) * size)`         |`malloc-array T size`
 
 In addition, C++ allows the management of memory by recursively invoking a
 type-defined destructor on stack values when exiting a bracketed scope, as well
 as on globals when the program is exited or a library unloaded. Based on this
 mechanism and intricate elision rules, various smart pointer types are
-implemented, of which the most useful is ``std::unique_ptr``, which is a type
+implemented, of which the most useful is `std::unique_ptr`, which is a type
 that manages the lifetime of a single heap value until it goes out of scope.
 
 In Scopes, types can be defined as unique, which instructs Scopes to manage the

          
@@ 1008,32 1005,32 @@ an example.
 Closures
 --------
 
-C++ supports runtime closures through the ``std::function`` type, which allows
+C++ supports runtime closures through the `std::function` type, which allows
 the implicit binding of values to a function, so that when the function is
 called, the bound values become available to the function without having to
 pass them as arguments. In functional programming, this process can be used to
 implement currying.
 
-..  code-block:: c++
+```c++
+void print_bound_constant () {
+    const int y = 42;
+    // capture `y` along with the function
+    auto f = [y](int x) -> int { return x + y; }
+    // prints 65
+    std::cout << f(23) << std::endl;
+}
 
-    void print_bound_constant () {
-        const int y = 42;
-        // capture `y` along with the function
-        auto f = [y](int x) -> int { return x + y; }
-        // prints 65
-        std::cout << f(23) << std::endl;
-    }
-
-    void print_bound_value (int y) {
-        // capture `y` along with the function
-        auto f = [y](int x) -> int { return x + y; }
-        // prints 23+y
-        std::cout << f(23) << std::endl;
-    }
+void print_bound_value (int y) {
+    // capture `y` along with the function
+    auto f = [y](int x) -> int { return x + y; }
+    // prints 23+y
+    std::cout << f(23) << std::endl;
+}
+```
 
 Scopes supports compile time closures natively, as demonstrated previously, but
 runtime closures are also supported through so-called captures. The example
-above would be translated as follows::
+above would be translated as follows:
 
     fn print_bound_constant ()
         let y = 42

          
@@ 1054,37 1051,37 @@ Loops
 -----
 
 C offers two structured control flows for loops which depend on mutation of
-an exit variable, namely ``while`` and ``for``. In addition, C++11 introduced
-the range-based ``for`` loop, which provides syntactical sugar for iterating
+an exit variable, namely `while` and `for`. In addition, C++11 introduced
+the range-based `for` loop, which provides syntactical sugar for iterating
 elements of a collection.
 
-..  code-block:: c++
+```c++
+// C-style for-loop implementing a counter
+for (int i = 0; i < 10; ++i) {
+    printf("%i\n", i);
+}
 
-    // C-style for-loop implementing a counter
-    for (int i = 0; i < 10; ++i) {
-        printf("%i\n", i);
-    }
-
-    // C-style for-loop implementing an iterator
-    for (iter_t it = first(container), int k = 0; is_valid(it); it = next(it), ++k) {
-        process(k, at(it));
-    }
+// C-style for-loop implementing an iterator
+for (iter_t it = first(container), int k = 0; is_valid(it); it = next(it), ++k) {
+    process(k, at(it));
+}
 
-    // while-loop implementing a counter
-    int i = 0;
-    while (i < 10) {
-        printf("%i\n", i);
-        ++i;
-    }
+// while-loop implementing a counter
+int i = 0;
+while (i < 10) {
+    printf("%i\n", i);
+    ++i;
+}
 
-    // range-based for-loop implementing an iterator (C++17 form)
-    for (auto &&[first,second] : map) {
-        process(first, second);
-    }
+// range-based for-loop implementing an iterator (C++17 form)
+for (auto &&[first,second] : map) {
+    process(first, second);
+}
+```
 
 Scopes defines a single builtin primitive for loops which leverages
 backpropagation of immutable values, upon which various other library forms are
-implemented::
+implemented:
 
     # implementing a counter using the range-based form
     for i in (range 10)

          
@@ 1127,7 1124,7 @@ allowing the CPU and GPU side to share a
 Scopes provides the :doc:`module-glm` and :doc:`module-glsl` modules, which
 implement native GLSL types and functions.
 
-See the following example implementing and compiling a pixel shader::
+See the following example implementing and compiling a pixel shader:
 
     using import glm
     using import glsl

          
@@ 1143,42 1140,41 @@ See the following example implementing a
 
 The program output is as follows:
 
-.. code-block:: glsl
+```glsl
+#version 330
+#ifdef GL_ARB_shading_language_420pack
+#extension GL_ARB_shading_language_420pack : require
+#endif
 
-    #version 330
-    #ifdef GL_ARB_shading_language_420pack
-    #extension GL_ARB_shading_language_420pack : require
-    #endif
-
-    in vec2 uv;
-    layout(location = 1) out vec4 color;
+in vec2 uv;
+layout(location = 1) out vec4 color;
 
-    void main()
-    {
-        vec2 _14 = (uv * vec2(0.5)) + vec2(0.5);
-        vec4 _19 = vec4(0.0);
-        _19.x = _14.x;
-        vec4 _21 = _19;
-        _21.y = _14.y;
-        vec4 _22 = _21;
-        _22.z = 0.0;
-        vec4 _24 = _22;
-        _24.w = 1.0;
-        color = _24;
-    }
+void main()
+{
+    vec2 _14 = (uv * vec2(0.5)) + vec2(0.5);
+    vec4 _19 = vec4(0.0);
+    _19.x = _14.x;
+    vec4 _21 = _19;
+    _21.y = _14.y;
+    vec4 _22 = _21;
+    _22.z = 0.0;
+    vec4 _24 = _22;
+    _24.w = 1.0;
+    color = _24;
+}
+```
 
 Exceptions
 ----------
 
 C provides only a primitive kind of unstructured exception handling via the
-``setjmp()`` and ``longjmp()`` functions provided by ``setjmp.h``.
+`setjmp()` and `longjmp()` functions provided by `setjmp.h`.
 
 C++ provides structured and polymorphic exception handling at runtime. Any value
-can be thrown as an exception using the ``throw`` keyword, and caught using
-the ``try .. catch`` form.
+can be thrown as an exception using the `throw` keyword, and caught using
+the `try .. catch` form.
 
-.. code-block:: c++
-
+```c++
     struct myexception {
         const char *what;
     };

          
@@ 1193,10 1189,11 @@ the ``try .. catch`` form.
             std::cout << e.what << std::endl;
         }
     }
+```
 
 Scopes supports a form of structured exception handling that is monomorphic,
 light-weight and C compatible. A value of any type can be raised using the
-``raise`` form, and handled using the ``try .. except`` form::
+`raise` form, and handled using the `try .. except` form:
 
     using import struct
 

          
@@ 1224,7 1221,7 @@ ABI Compliance
 --------------
 
 Scopes aims to achieve full compliance with the C ABI used on x64 platforms
-for Linux, MacOS X and Windows, defaulting to the ``cdecl`` calling convention.
+for Linux, MacOS X and Windows, defaulting to the `cdecl` calling convention.
 Other calling conventions are not yet supported. Any Scopes function can be
 passed as a callback to a C library, and C functions can be called from Scopes
 without any additional hinting required.

          
M doc/docs/dataformat.md +73 -79
@@ 1,3 1,7 @@ 
+<style type="text/css" rel="stylesheet">
+body { counter-reset: chapter 5; }
+</style>
+
 Notation
 ========
 

          
@@ 5,7 9,7 @@ Scopes source code is written in a notat
 even before the first function is even written: *Scopes List Notation*,
 abbreviated **SLN**.
 
-Closely related to `S-Expressions <https://en.wikipedia.org/wiki/S-expression>`_,
+Closely related to [S-Expressions](https://en.wikipedia.org/wiki/S-expression),
 SLN can be regarded as a human-readable serialization format comparable to
 YAML, XML or JSON. It has been optimized for simplicity and terseness.
 

          
@@ 18,7 22,7 @@ At a Glance
 -----------
 
 As a summary, here is an example that provides an overview of all
-the notation aspects::
+the notation aspects:
 
     # below is some random data without any schema
 

          
@@ 134,14 138,14 @@ SLN recognizes only five kinds of elemen
 * **Lists**
 * **Comments**
 
-.. note:: Comments are not part of the data structure.
+!!! note
+    Comments are not part of the data structure.
 
-Comments
-^^^^^^^^
+### Comments ###
 
-Both line and block comments are initiated with a single token, ``#``. A comment
+Both line and block comments are initiated with a single token, `#`. A comment
 lasts from its beginning token to the first non-whitespace character with an equal
-or lower indentation level. Some examples of valid comments::
+or lower indentation level. Some examples of valid comments:
 
     # a line comment
     not a comment

          
@@ 152,31 156,29 @@ or lower indentation level. Some example
         indentation rules
     but this line is not a comment
 
-Strings
-^^^^^^^
+### Strings ###
 
 Strings describe sequences of unsigned 8-bit characters in the range of 0-255.
-A string begins and ends with ``"`` (double quotes).  The ``\`` escape character
+A string begins and ends with `"` (double quotes).  The `\` escape character
 can be used to include quotes in a string and describe unprintable control
-characters such as ``\\n`` (return) and ``\\t`` (tab). Other unprintable
-characters can be encoded via ``\\xNN``, where ``NN`` is the character's
+characters such as `\n` (return) and `\t` (tab). Other unprintable
+characters can be encoded via `\xNN`, where `NN` is the character's
 hexadecimal code. Strings are parsed as-is, so UTF-8 encoded strings will be
 copied over verbatim.
 
-Here are some examples of valid strings::
+Here are some examples of valid strings:
 
     "a single-line string in double quotations"
     "return: \n, tab: \t, backslash: \\, double quote: \", nbsp: \xFF."
 
-Raw Block Strings
-^^^^^^^^^^^^^^^^^
+### Raw Block Strings ###
 
 Raw block strings provide a way to quote multiple lines of text with characters
-that should not be escaped. A raw block string begins with ``""""`` (four
+that should not be escaped. A raw block string begins with `""""` (four
 double quotes). A raw block string ends at the first newline before a printable
 character that has a lower indentation.
 
-Here are some examples of valid raw block strings::
+Here are some examples of valid raw block strings:
 
     """"a single-line string as a block string
     # commented line inbetween

          
@@ 186,19 188,18 @@ Here are some examples of valid raw bloc
             printf("hello world\n");
         }
 
-Symbols
-^^^^^^^
+### Symbols ###
 
 Like strings, a symbol describes a sequence of 8-bit characters, but acts as a
 label or bindable name. Symbols may contain any character from the UTF-8
 character set and terminate when encountering any character from the set
-``#;()[]{},``. A symbol always terminates when one of these characters is
+`#;()[]{},`. A symbol always terminates when one of these characters is
 encountered. Any symbol that parses as a number is also excluded. Two symbols
 sharing the same sequence of characters always map to the same value.
 
-As a special case, ``,`` is always parsed as a single character.
+As a special case, `,` is always parsed as a single character.
 
-Here are some examples of valid symbols::
+Here are some examples of valid symbols:
 
     # classic underscore notation
     some_identifier _some_identifier

          
@@ 211,20 212,19 @@ Here are some examples of valid symbols:
     # numbered
     _42 =303
 
-Numbers
-^^^^^^^
+### Numbers ###
 
 Numbers come in two forms: integers and reals. The parser understands integers
-in the range ``-(2^63)`` to ``2^64-1`` and records them as signed 32-bit values
+in the range `-(2^63)` to `2^64-1` and records them as signed 32-bit values
 unless the value is too big, in which case it will be extended to 64-bit
 signed, then 64-bit unsigned. Reals are floating point numbers parsed and
-stored as `IEEE-754 <https://wikipedia.org/wiki/IEEE_754>`_ binary32 values.
+stored as [IEEE-754](https://wikipedia.org/wiki/IEEE_754) binary32 values.
 
-Numbers can be explicitly specified to be of a certain type by appending a ``:``
-to the number as well as a numerical typename that is one of: ``i8``, ``i16``,
-``i32``, ``i64``, ``u8``, ``u16``, ``u32``, ``u64``, ``f32`` or ``f64``.
+Numbers can be explicitly specified to be of a certain type by appending a `:`
+to the number as well as a numerical typename that is one of: `i8`, `i16`,
+`i32`, `i64`, `u8`, `u16`, `u32`, `u64`, `f32` or `f64`.
 
-Here are some examples of valid numbers::
+Here are some examples of valid numbers:
 
     # positive and negative integers in decimal and hexadecimal notation
     0 +23 42 -303 12 -1 -0x20 0xAFFE

          
@@ 239,16 239,15 @@ Here are some examples of valid numbers:
     # a floating-point number with double precision
     1.0:f64
 
-Lists
-^^^^^
+### Lists ###
 
 Lists are the only nesting type, and can be either scoped by braces or
-indentation. For braces, ``()``, ``[]`` and ``{}`` are accepted.
+indentation. For braces, `()`, `[]` and `{}` are accepted.
 
 Lists can be empty or contain a virtually unlimited number of elements,
 only separated by whitespace. They typically describe expressions in Scopes.
 
-Here are some examples of valid lists::
+Here are some examples of valid lists:
 
     # a list of numbers in naked format
     1 2 3 4 5

          
@@ 265,9 264,9 @@ Naked & Braced Lists
 Every Scopes source file is parsed as a tree of expresion lists.
 
 The classic notation (what we will call *braced notation*) uses a syntax close
-to what `Lisp <http://en.wikipedia.org/wiki/Lisp_(programming_language)>`_ and
-`Scheme <http://en.wikipedia.org/wiki/Scheme_(programming_language)>`_ authors
-know as *restricted* `S-expressions <https://en.wikipedia.org/wiki/S-expression>`_::
+to what [Lisp](http://en.wikipedia.org/wiki/Lisp_(programming_language)) and
+[Scheme](http://en.wikipedia.org/wiki/Scheme_(programming_language)) authors
+know as *restricted* [S-expressions](https://en.wikipedia.org/wiki/S-expression>):
 
     (print
         (.. "Hello" "World")

          
@@ 275,13 274,13 @@ know as *restricted* `S-expressions <htt
 
 As a modern alternative, Scopes offers a *naked notation* where the scope of
 lists is implicitly balanced by indentation, an approach used by
-`Python <http://en.wikipedia.org/wiki/Python_(programming_language)>`_,
-`Haskell <http://en.wikipedia.org/wiki/Haskell_(programming_language)>`_,
-`YAML <http://en.wikipedia.org/wiki/YAML>`_,
-`Sass <http://en.wikipedia.org/wiki/Sass_(stylesheet_language)>`_ and many
+[Python](http://en.wikipedia.org/wiki/Python_(programming_language)),
+[Haskell](http://en.wikipedia.org/wiki/Haskell_(programming_language)),
+[YAML](http://en.wikipedia.org/wiki/YAML),
+[Sass](http://en.wikipedia.org/wiki/Sass_(stylesheet_language)) and many
 other languages.
 
-This source parses as the same list in the previous, braced example::
+This source parses as the same list in the previous, braced example:
 
     # The same list as above, but in naked format.
         A sub-paragraph continues the list.

          
@@ 294,11 293,10 @@ This source parses as the same list in t
           escape token which causes a continuation of the parent list
         \ 303 606 909
 
-Mixing Modes
-^^^^^^^^^^^^
+### Mixing Modes ###
 
 Naked lists can contain braced lists, and braced lists can
-contain naked lists::
+contain naked lists:
 
     # compute the value of (1 + 2 + (3 * 4)) and print the result
     (print

          
@@ 331,10 329,10 @@ while code examples make ample use of na
 Brace Styles
 ------------
 
-In addition to regular parentheses ``()``, SLN parses curly ``{}`` and
-square ``[]`` brace styles. They are merely meant for providing variety for
+In addition to regular parentheses `()`, SLN parses curly `{}` and
+square `[]` brace styles. They are merely meant for providing variety for
 writing SLN-based formats, and are expanded to simple lists during parsing.
-Some examples::
+Some examples:
 
     [a b c d]
     # expands to

          
@@ 348,14 346,14 @@ List Separators
 ---------------
 
 Both naked and braced lists support a special control character, the list
-separator ``;`` (semicolon). Known as a statement separator in other languages,
+separator `;` (semicolon). Known as a statement separator in other languages,
 it groups atoms into separate lists and allows the omission of required
 parentheses or lines in complex trees.
 
 In addition, it is possible to list-wrap the first element of a list in naked
-mode by starting the head of the block with ``;``.
+mode by starting the head of the block with `;`.
 
-Here are some examples::
+Here are some examples:
 
     # in braced notation
     (print a; print (a;b;); print c;)

          
@@ 370,10 368,10 @@ Here are some examples::
     # parses as
     ((print a) (print b) ((print c) (print d)))
 
-.. warning::
+!!! warning
 
     If semicolons are used with braced notation then any trailing elements that
-    are not terminated with ``;`` will not be wrapped::
+    are not terminated with `;` will not be wrapped:
 
         # in braced notation
         (print a; print (a;b;); print c)

          
@@ 387,44 385,42 @@ As naked notation gives the author the f
 it also takes away. The following section discusses small challenges that
 might be encountered when using naked notation and how to resolve them.
 
-Single Elements
-^^^^^^^^^^^^^^^
+### Single Elements ###
 
 Special care must be taken when single elements are defined when the author
 wants to wrap them in a list.
 
-Here is a braced list describing an expression printing the number 42::
+Here is a braced list describing an expression printing the number 42:
 
     (print 42)
 
 The naked equivalent declares two elements in a single line, which are implicitly
-wrapped in a single list::
+wrapped in a single list:
 
     print 42
 
-A single element on its own line is not wrapped::
+A single element on its own line is not wrapped:
 
     print           # (print
         42          #        42)
 
-What if we want to just print a newline, passing no arguments?::
+What if we want to just print a newline, passing no arguments?:
 
     print           # print
 
 The statement above will be ignored because a symbol is resolved but not called.
-One can make use of the ``;`` (split-statement) control
-character, which ends the current list::
+One can make use of the `;` (split-statement) control
+character, which ends the current list:
 
     print;          # (print)
 
-Continuation Lines
-^^^^^^^^^^^^^^^^^^
+### Continuation Lines ###
 
 There are often situations when a high number of elements in a list
 interferes with best practices of formatting source code and exceeds the line
 column limit (typically 80 or 100).
 
-In braced lists, the problem is easily corrected::
+In braced lists, the problem is easily corrected:
 
     # import many symbols from an external module into the active namespace
     (import-from "OpenGL"

          
@@ 432,7 428,7 @@ In braced lists, the problem is easily c
         GL_STENCIL_BUFFER_BIT GL_DEPTH_BUFFER_BIT glViewport glUseProgram
         glDrawArrays glEnable glDisable GL_TRIANGLE_STRIP)
 
-The naked approach interprets each new line as a nested list::
+The naked approach interprets each new line as a nested list:
 
     # produces runtime errors
     import-from "OpenGL"

          
@@ 447,7 443,7 @@ The naked approach interprets each new l
         (GL_STENCIL_BUFFER_BIT GL_DEPTH_BUFFER_BIT glViewport glUseProgram)
         (glDrawArrays glEnable glDisable GL_TRIANGLE_STRIP))
 
-This can be fixed by using the ``splice-line`` control character, ``\``::
+This can be fixed by using the `splice-line` control character, `\`:
 
     # correct solution using splice-line, postfix-style
     import-from "OpenGL" \

          
@@ 455,9 451,9 @@ This can be fixed by using the ``splice-
         GL_STENCIL_BUFFER_BIT GL_DEPTH_BUFFER_BIT glViewport glUseProgram \
         glDrawArrays glEnable glDisable GL_TRIANGLE_STRIP
 
-Unlike in other languages, and as previously demonstrated, ``\`` splices at the
+Unlike in other languages, and as previously demonstrated, `\` splices at the
 token level rather than the character level, and can also be placed at the
-beginning of nested lines, where the parent is still the active list::
+beginning of nested lines, where the parent is still the active list:
 
     # correct solution using the splice-line control character '\', prefix-style
     import-from "OpenGL"

          
@@ 465,10 461,9 @@ beginning of nested lines, where the par
         \ GL_STENCIL_BUFFER_BIT GL_DEPTH_BUFFER_BIT glViewport glUseProgram
         \ glDrawArrays glEnable glDisable GL_TRIANGLE_STRIP
 
-Tail Splicing
-^^^^^^^^^^^^^
+### Tail Splicing ###
 
-Naked notation is ideal for writing nested lists that accumulate at the tail::
+Naked notation is ideal for writing nested lists that accumulate at the tail:
 
     # braced
     (a b c

          
@@ 483,26 478,25 @@ Naked notation is ideal for writing nest
         j k l
 
 However, there are complications when additional elements need to be spliced
-back into the parent list::
+back into the parent list:
 
     (a b c
         (d e f
             (g h i))
         j k l)
 
-Once again, we can reuse the splice-line control character ``\`` to get what we
-want::
+Once again, we can reuse the splice-line control character `\` to get what we
+want:
 
     a b c
         d e f
             g h i
         \ j k l
 
-Left-Hand Nesting
-^^^^^^^^^^^^^^^^^
+### Left-Hand Nesting ###
 
 When using infix notation, conditional blocks, or functions producing functions,
-lists occur that nest at the head level rather than the tail::
+lists occur that nest at the head level rather than the tail:
 
     ((((a b)
         c d)

          
@@ 510,7 504,7 @@ lists occur that nest at the head level 
                 g h)
 
 The equivalent naked mode version makes extensive use of list separator and
-splice-line characters to describe the same tree::
+splice-line characters to describe the same tree:
 
     # equivalent structure
     ;

          
@@ 523,7 517,7 @@ splice-line characters to describe the s
 
 A more complex tree which also requires splicing elements back into the parent
 list can be implemented with the same combination of list separator and
-splice-line characters::
+splice-line characters:
 
     # braced
     (a

          
A => doc/docs/extra.css +77 -0
@@ 0,0 1,77 @@ 
+body {
+    counter-reset: chapter;
+}
+
+div.section h1 {
+    counter-reset: section;
+}
+
+div.section h2 {
+    counter-reset: subsection;
+}
+
+div.section h3 {
+    counter-reset: subsubsection;
+}
+
+div.section h1#the-scopes-programming-infrastructure:before, h1#search:before {
+    content: none;
+}
+
+div.section h1:before {
+    content: counter(chapter) ". ";
+}
+
+div.section h2:before {
+    counter-increment: section;
+    content: counter(chapter) "." counter(section) ". ";
+}
+
+div.section h3:before {
+    counter-increment: subsection;
+    content: counter(chapter) "." counter(section) "." counter(subsection) ". ";
+}
+
+div.section h4:before {
+    counter-increment: subsubsection;
+    content: counter(chapter) "." counter(section) "." counter(subsection) "." counter(subsubsection) ". ";
+}
+
+div.wy-menu {
+    counter-reset: menu-chapter
+}
+
+div.wy-menu>ul li.toctree-l1 {
+    counter-increment: menu-chapter;
+    counter-reset: menu-section;
+}
+
+div.wy-menu>ul li.toctree-l1>a:before {
+    content: counter(menu-chapter) ". ";
+}
+
+div.wy-menu>ul li.toctree-l2 {
+    counter-increment: menu-section;
+    counter-reset: menu-subsection;
+}
+
+div.wy-menu>ul li.toctree-l2>a:before {
+    content: counter(menu-chapter) "." counter(menu-section) ". ";
+}
+
+div.wy-menu>ul li.toctree-l3 {
+    counter-increment: menu-subsection;
+    counter-reset: menu-subsubsection;
+}
+
+div.wy-menu>ul li.toctree-l3>a:before {
+    content: counter(menu-chapter) "." counter(menu-section) "." counter(menu-subsection) ". ";
+}
+
+div.wy-menu>ul li.toctree-l4 {
+    counter-increment: menu-subsubsection;
+}
+
+div.wy-menu>ul li.toctree-l4>a:before {
+    content: counter(menu-chapter) "." counter(menu-section) "." counter(menu-subsection) "." counter(menu-subsubsection) ". ";
+}

          
M doc/docs/index.md +5 -32
@@ 1,8 1,3 @@ 
-.. Scopes documentation master file, created by
-   sphinx-quickstart on Tue Sep 22 07:49:51 2015.
-   You can adapt this file completely to your liking, but it should at least
-   contain the root `toctree` directive.
-
 The Scopes Programming Infrastructure
 =====================================
 

          
@@ 13,30 8,8 @@ language repository.
 
 Contents:
 
-.. toctree::
-   :maxdepth: 2
-   :numbered:
-
-   about
-   intro
-   tutorial
-   cpp_users
-   dataformat
-   modules
-
-..
-   architecture
-   Scopeslang
-   debugging
-   meta
-   lang
-   capi
-   reference
-
-Indices and tables
-==================
-
-* :ref:`genindex`
-* :ref:`modindex`
-* :ref:`search`
-
+- [About Scopes](about.md)
+- [Getting Started](intro.md)
+- [The Scopes Tutorial](tutorial.md)
+- [Scopes for C/C++ Users](cpp_users.md)
+- [Notation](dataformat.md)

          
M doc/docs/intro.md +70 -69
@@ 1,3 1,7 @@ 
+<style type="text/css" rel="stylesheet">
+body { counter-reset: chapter 2; }
+</style>
+
 Getting Started
 ===============
 

          
@@ 5,122 9,119 @@ Installation
 ------------
 
 You can either download a binary distribution of Scopes from the
-`website <http://scopes.rocks>`_ or build Scopes from source.
+[website](http://scopes.rocks) or build Scopes from source.
 
 The main repository for scopes is on
-`sourcehut <https://hg.sr.ht/~duangle/scopes>`_.
+[sourcehut](https://hg.sr.ht/~duangle/scopes).
 
 Note: any reference to `scopes-repo` in the instructions refers to wherever
 you have checked out the Scopes source tree.
 
-Building Scopes on Windows
-^^^^^^^^^^^^^^^^^^^^^^^^^^
+### Building Scopes on Windows ###
 
 Scopes only supports the `mingw64` toolchain for the foreseeable future.
 
-* Install `MSYS2 <http://msys2.github.io>`_ and
-  `install <https://github.com/valtron/llvm-stuff/wiki/Build-LLVM-with-MSYS2>`_
-  clang, LLVM 10.0.x, polly, cmake and make for ``x86_64``. The packages are
-  named ``mingw64/mingw-w64-x86_64-llvm``, ``mingw64/mingw-w64-x86_64-clang``,
-  ``mingw64/mingw-w64-x86_64-cmake``, ``mingw64/mingw-w64-x86_64-polly``
-  and ``make``.
-* Nice to have: ``mingw-w64-x86_64-gdb``
-* at least ``usr/bin`` from your MSYS2 installation must be added to the
-  ``PATH`` variable so that the buildscript can find MSYS2.
+* Install [MSYS2](http://msys2.github.io) and
+  [install](https://github.com/valtron/llvm-stuff/wiki/Build-LLVM-with-MSYS2)
+  clang, LLVM 10.0.x, polly, cmake and make for `x86_64`. The packages are
+  named `mingw64/mingw-w64-x86_64-llvm`, `mingw64/mingw-w64-x86_64-clang`,
+  `mingw64/mingw-w64-x86_64-cmake`, `mingw64/mingw-w64-x86_64-polly`
+  and `make`.
+* Nice to have: `mingw-w64-x86_64-gdb`
+* at least `usr/bin` from your MSYS2 installation must be added to the
+  `PATH` variable so that the buildscript can find MSYS2.
 * You also need the latest source distributions of
-  `SPIRV-Tools <https://github.com/KhronosGroup/SPIRV-Tools>`_ and
-  `SPIRV-Cross <https://github.com/KhronosGroup/SPIRV-Cross>`_ checked out
+  [SPIRV-Tools](https://github.com/KhronosGroup/SPIRV-Tools) and
+  [SPIRV-Cross](https://github.com/KhronosGroup/SPIRV-Cross) checked out
   into the workspace folder.
-* Lastly, you need a build of `GENie <https://github.com/bkaradzic/GENie>`_
+* Lastly, you need a build of [GENie](https://github.com/bkaradzic/GENie)
   (binaries available on the page).
-* Check ``SPIRV-Tools``' build instructions to verify that its dependency on
-  ``SPIRV-Headers`` is satisfied, and all other dependencies are up-to-date.
-  Build ``SPIRV-Tools`` using
-  ``mkdir build && cd build && cmake .. -G "MSYS Makefiles"
-  -DCMAKE_BUILD_TYPE=Release && make`` in `scopes-repo/SPIRV-Tools/build`.
-* ``SPIRV-Cross`` does not have to be built.
-* In the workspace folder, run ``genie gmake`` once to generate the project
+* Check `SPIRV-Tools`' build instructions to verify that its dependency on
+  `SPIRV-Headers` is satisfied, and all other dependencies are up-to-date.
+  Build `SPIRV-Tools` using
+  `mkdir build && cd build && cmake .. -G "MSYS Makefiles"
+  -DCMAKE_BUILD_TYPE=Release && make` in `scopes-repo/SPIRV-Tools/build`.
+* `SPIRV-Cross` does not have to be built.
+* In the workspace folder, run `genie gmake` once to generate the project
   Makefiles.
-* To build in debug mode, run ``make -C build``. For release mode, use
-  ``make -C build config=release``. Use the option ``-j4`` to speed up the
-  build on a multicore machine, where ``4`` is a sensible number of CPU
+* To build in debug mode, run `make -C build`. For release mode, use
+  `make -C build config=release`. Use the option `-j4` to speed up the
+  build on a multicore machine, where `4` is a sensible number of CPU
   hardware threads to use.
-* There should now be a ``scopes.exe`` executable in the `bin` folder.
+* There should now be a `scopes.exe` executable in the `bin` folder.
 * For the clang bridge to work properly, copy
   `clang/lib/clang/10.0.x/include` to `scopes-repo/lib/clang/include`.
-* For a fresh rebuild, just remove the ``build`` directory before running
-  ``make`` again.
+* For a fresh rebuild, just remove the `build` directory before running
+  `make` again.
 
-Building Scopes on Linux
-^^^^^^^^^^^^^^^^^^^^^^^^
+### Building Scopes on Linux ###
 
 * You need build-essentials, clang, libclang and LLVM 10.0.x installed -
   preferably locally:
-* Put ``llvm-config`` in your ``$PATH``.
+* Put `llvm-config` in your `$PATH`.
 * Alternatively, provide your own clang distribution and symlink it to
-  ``scopes-repo/clang``.
+  `scopes-repo/clang`.
 * You also need the latest source distributions of
-  `SPIRV-Tools <https://github.com/KhronosGroup/SPIRV-Tools>`_ and
-  `SPIRV-Cross <https://github.com/KhronosGroup/SPIRV-Cross>`_ checked out or
+  [SPIRV-Tools](https://github.com/KhronosGroup/SPIRV-Tools) and
+  [SPIRV-Cross](https://github.com/KhronosGroup/SPIRV-Cross) checked out or
   symlinked into the workspace folder.
-* Lastly, you need a build of `GENie <https://github.com/bkaradzic/GENie>`_
+* Lastly, you need a build of [GENie](https://github.com/bkaradzic/GENie)
   (binaries available on the page).
-* Check ``SPIRV-Tools``' build instructions to verify that its dependency on
-  ``SPIRV-Headers`` is satisfied, and all other dependencies are up-to-date.
-  Build ``SPIRV-Tools`` using
-  ``mkdir build && cd build && cmake .. -DCMAKE_BUILD_TYPE=Release && make``
+* Check `SPIRV-Tools`' build instructions to verify that its dependency on
+  `SPIRV-Headers` is satisfied, and all other dependencies are up-to-date.
+  Build `SPIRV-Tools` using
+  `mkdir build && cd build && cmake .. -DCMAKE_BUILD_TYPE=Release && make`
   in `scopes-repo/SPIRV-Tools/build`.
-* ``SPIRV-Cross`` does not have to be built.
-* In the workspace folder, run ``genie gmake`` once to generate the project
+* `SPIRV-Cross` does not have to be built.
+* In the workspace folder, run `genie gmake` once to generate the project
   Makefiles.
-* To build in debug mode, run ``make -C build``. For release mode, use
-  ``make -C build config=release``. Use the option ``-j4`` to speed up the
-  build on a multicore machine, where ``4`` is a sensible number of CPU
+* To build in debug mode, run `make -C build`. For release mode, use
+  `make -C build config=release`. Use the option `-j4` to speed up the
+  build on a multicore machine, where `4` is a sensible number of CPU
   hardware threads to use.
-* There should now be a ``scopes`` executable in the `bin` folder.
+* There should now be a `scopes` executable in the `bin` folder.
 * For the clang bridge to work properly, copy or symlink
   `$(llvm-config --prefix)/lib/clang/$(llvm-config --version)/include` to
   `scopes-repo/lib/clang/include`.
-* For a fresh rebuild, just remove the ``build`` directory before running
-  ``make`` again.
+* For a fresh rebuild, just remove the `build` directory before running
+  `make` again.
 
-Building Scopes on macOS
-^^^^^^^^^^^^^^^^^^^^^^^^
+### Building Scopes on macOS ###
 
 * Scopes builds on macOS Mojave (10.14) using LLVM 10.0.
-* You'll need the following packages from `brew <https://brew.sh/>`_: `llvm`
-  and `cmake`. Scopes' build system respects ``brew``'s standard installation
+* You'll need the following packages from [brew](https://brew.sh/): `llvm`
+  and `cmake`. Scopes' build system respects `brew`'s standard installation
   paths.
 * Alternatively, provide your own clang distribution and symlink it to
-  ``scopes-repo/clang``.
-* Put ``llvm-config`` in your ``$PATH``. Find it in `$(brew --prefix llvm)/bin`
+  `scopes-repo/clang`.
+* Put `llvm-config` in your `$PATH`. Find it in `$(brew --prefix llvm)/bin`
   if using brew.
 * You'll also need an installation of the Xcode Command Line Tools:
-  ``xcode-select --install``.
+  `xcode-select --install`.
 * You may also need to force installation of the macOS SDK headers:
   Open `macOS_SDK_headers_for_macOS_10.14.pkg` found in
   `/Library/Developer/CommandLineTools/Packages`
 * You also need the latest source distributions of
-  `SPIRV-Tools <https://github.com/KhronosGroup/SPIRV-Tools>`_ and
-  `SPIRV-Cross <https://github.com/KhronosGroup/SPIRV-Cross>`_ checked out or
+  [SPIRV-Tools](https://github.com/KhronosGroup/SPIRV-Tools) and
+  [SPIRV-Cross](https://github.com/KhronosGroup/SPIRV-Cross) checked out or
   symlinked into the workspace folder.
-* Lastly, you need a build of `GENie <https://github.com/bkaradzic/GENie>`_
+* Lastly, you need a build of [GENie](https://github.com/bkaradzic/GENie)
   (binaries available on the page).
-* Check ``SPIRV-Tools``' build instructions to verify that its dependency on
-  ``SPIRV-Headers`` is satisfied, and all other dependencies are up-to-date.
-  Build ``SPIRV-Tools`` using
-  ``mkdir build && cd build && cmake .. -DCMAKE_BUILD_TYPE=Release && make``
+* Check `SPIRV-Tools`' build instructions to verify that its dependency on
+  `SPIRV-Headers` is satisfied, and all other dependencies are up-to-date.
+  Build `SPIRV-Tools` using
+  `mkdir build && cd build && cmake .. -DCMAKE_BUILD_TYPE=Release && make`
   in `scopes-repo/SPIRV-Tools/build`.
-* ``SPIRV-Cross`` does not have to be built.
-* In the workspace folder, run ``genie gmake`` once to generate the project
+* `SPIRV-Cross` does not have to be built.
+* In the workspace folder, run `genie gmake` once to generate the project
   Makefiles.
-* To build in debug mode, run ``make -C build``. For release mode, use
-  ``make -C build config=release``. Use the option ``-j4`` to speed up the
-  build on a multicore machine, where ``4`` is a sensible number of CPU
+* To build in debug mode, run `make -C build`. For release mode, use
+  `make -C build config=release`. Use the option `-j4` to speed up the
+  build on a multicore machine, where `4` is a sensible number of CPU
   hardware threads to use.
-* There should now be a ``scopes`` executable in the `bin` folder.
+* There should now be a `scopes` executable in the `bin` folder.
 * For the clang bridge to work properly, copy or symlink
   `$(llvm-config --prefix)/lib/clang/$(llvm-config --version)/include` to
   `scopes-repo/lib/clang/include`.
 * For a fresh rebuild, just remove the `build` directory before running
-  ``make`` again.
+  `make` again.

          
M doc/docs/ir-ref.md +351 -128
@@ 6,294 6,517 @@ This chapter will provide reference info
 Built-in Types
 --------------
 
-.. ir-type:: void
-.. ir-type:: i1
-.. ir-type:: i8
-.. ir-type:: i16
-.. ir-type:: i32
-.. ir-type:: i64
-.. ir-type:: float
-.. ir-type:: double
-.. ir-type:: rawstring
-.. ir-type:: opaque
+*ir-type*{.property} `void`{.descname} [](#scopes.ir-type.void "Permalink to this definition"){.headerlink} {#scopes.ir-type.void}
+
+:	
+
+*ir-type*{.property} `i1`{.descname} [](#scopes.ir-type.i1 "Permalink to this definition"){.headerlink} {#scopes.ir-type.i1}
+
+:	
+
+*ir-type*{.property} `i8`{.descname} [](#scopes.ir-type.i8 "Permalink to this definition"){.headerlink} {#scopes.ir-type.i8}
+
+:	
+
+*ir-type*{.property} `i16`{.descname} [](#scopes.ir-type.i16 "Permalink to this definition"){.headerlink} {#scopes.ir-type.i16}
+
+:	
+
+*ir-type*{.property} `i32`{.descname} [](#scopes.ir-type.i32 "Permalink to this definition"){.headerlink} {#scopes.ir-type.i32}
+
+:	
+
+*ir-type*{.property} `i64`{.descname} [](#scopes.ir-type.i64 "Permalink to this definition"){.headerlink} {#scopes.ir-type.i64}
+
+:	
+
+*ir-type*{.property} `float`{.descname} [](#scopes.ir-type.float "Permalink to this definition"){.headerlink} {#scopes.ir-type.float}
+
+:	
+
+*ir-type*{.property} `double`{.descname} [](#scopes.ir-type.double "Permalink to this definition"){.headerlink} {#scopes.ir-type.double}
+
+:	
+
+*ir-type*{.property} `rawstring`{.descname} [](#scopes.ir-type.rawstring "Permalink to this definition"){.headerlink} {#scopes.ir-type.rawstring}
+
+:	
+
+*ir-type*{.property} `opaque`{.descname} [](#scopes.ir-type.opaque "Permalink to this definition"){.headerlink} {#scopes.ir-type.opaque}
+
+:	
 
 Type Constructors
 -----------------
 
-.. ir-special:: (function return-type (? param-type ...) (? _:...))
+*ir-special*{.property} `(function return-type (? param-type ...) (? _:...))`{.descname} [](#scopes.ir-special.function "Permalink to this definition"){.headerlink} {#scopes.ir-special.function}
+
+:	
+
+*ir-special*{.property} `(pointer type)`{.descname} [](#scopes.ir-special.pointer "Permalink to this definition"){.headerlink} {#scopes.ir-special.pointer}
 
-.. ir-special:: (pointer type)
+:	
+
+*ir-special*{.property} `(array type count)`{.descname} [](#scopes.ir-special.array "Permalink to this definition"){.headerlink} {#scopes.ir-special.array}
 
-.. ir-special:: (array type count)
+:	
+
+*ir-special*{.property} `(vector type count)`{.descname} [](#scopes.ir-special.vector "Permalink to this definition"){.headerlink} {#scopes.ir-special.vector}
 
-.. ir-special:: (vector type count)
+:	
 
-.. ir-special:: (struct name (? _:packed) (? type ...))
+*ir-special*{.property} `(struct name (? _:packed) (? type ...))`{.descname} [](#scopes.ir-special.struct "Permalink to this definition"){.headerlink} {#scopes.ir-special.struct}
+
+:	
 
-.. ir-special:: (typeof value)
+*ir-special*{.property} `(typeof value)`{.descname} [](#scopes.ir-special.typeof "Permalink to this definition"){.headerlink} {#scopes.ir-special.typeof}
+
+:	
 
-.. ir-special:: (getelementtype type (? index ...))
+*ir-special*{.property} `(getelementtype type (? index ...))`{.descname} [](#scopes.ir-special.getelementtype "Permalink to this definition"){.headerlink} {#scopes.ir-special.getelementtype}
+
+:	
 
 Definitions
 -----------
 
-.. ir-special:: (defvalue value)
+*ir-special*{.property} `(defvalue value)`{.descname} [](#scopes.ir-special.defvalue "Permalink to this definition"){.headerlink} {#scopes.ir-special.defvalue}
+
+:	
 
-.. ir-special:: (deftype value)
+*ir-special*{.property} `(deftype value)`{.descname} [](#scopes.ir-special.deftype "Permalink to this definition"){.headerlink} {#scopes.ir-special.deftype}
+
+:	
+
+*ir-special*{.property} `(defstruct name (? _:packed) (? type ...))`{.descname} [](#scopes.ir-special.defstruct "Permalink to this definition"){.headerlink} {#scopes.ir-special.defstruct}
 
-.. ir-special:: (defstruct name (? _:packed) (? type ...))
+:	
+
+*ir-special*{.property} `(define name ((? param ...)) type (? expression ...))`{.descname} [](#scopes.ir-special.define "Permalink to this definition"){.headerlink} {#scopes.ir-special.define}
 
-.. ir-special:: (define name ((? param ...)) type (? expression ...))
+:	
 
-.. ir-special:: (declare symbol-string type)
+*ir-special*{.property} `(declare symbol-string type)`{.descname} [](#scopes.ir-special.declare "Permalink to this definition"){.headerlink} {#scopes.ir-special.declare}
+
+:	
 
 Aggregate Constructors
 ----------------------
 
-.. ir-special:: (structof (| (? "" (? _:packed)) type) (? const-value ...))
+*ir-special*{.property} `(structof (| (? "" (? _:packed)) type) (? const-value ...))`{.descname} [](#scopes.ir-special.structof "Permalink to this definition"){.headerlink} {#scopes.ir-special.structof}
+
+:	
+
+*ir-special*{.property} `(arrayof type (? const-value ...))`{.descname} [](#scopes.ir-special.arrayof "Permalink to this definition"){.headerlink} {#scopes.ir-special.arrayof}
 
-.. ir-special:: (arrayof type (? const-value ...))
+:	
 
-.. ir-special:: (vectorof const-value (? ...))
+*ir-special*{.property} `(vectorof const-value (? ...))`{.descname} [](#scopes.ir-special.vectorof "Permalink to this definition"){.headerlink} {#scopes.ir-special.vectorof}
+
+:	
 
 Constant Values
 ---------------
 
-.. ir-special:: (int type integer-value)
+*ir-special*{.property} `(int type integer-value)`{.descname} [](#scopes.ir-special.int "Permalink to this definition"){.headerlink} {#scopes.ir-special.int}
+
+:	Constructs an integer constant of `type`.
 
-    Constructs an integer constant of ``type``.
+    A naked integer is shorthand for `(int i32 <number>)`.
 
-    A naked integer is shorthand for ``(int i32 <number>)``.
+*ir-special*{.property} `(real type real-value)`{.descname} [](#scopes.ir-special.real "Permalink to this definition"){.headerlink} {#scopes.ir-special.real}
 
-.. ir-special:: (real type real-value)
+:	Constructs a real constant of `type`.
+
+*ir-special*{.property} `(null type)`{.descname} [](#scopes.ir-special.null "Permalink to this definition"){.headerlink} {#scopes.ir-special.null}
 
-    Constructs a real constant of ``type``.
+:	Constructs a zero initializer for `type`.
 
-.. ir-special:: (null type)
+*ir-special*{.property} `(alignof type)`{.descname} [](#scopes.ir-special.alignof "Permalink to this definition"){.headerlink} {#scopes.ir-special.alignof}
 
-    Constructs a zero initializer for ``type``.
+:	
+
+*ir-special*{.property} `(sizeof type)`{.descname} [](#scopes.ir-special.sizeof "Permalink to this definition"){.headerlink} {#scopes.ir-special.sizeof}
 
-.. ir-special:: (alignof type)
+:	
 
-.. ir-special:: (sizeof type)
+*ir-special*{.property} `(lengthof type)`{.descname} [](#scopes.ir-special.lengthof "Permalink to this definition"){.headerlink} {#scopes.ir-special.lengthof}
 
-.. ir-special:: (lengthof type)
+:	
+
+*ir-macro*{.property} `(&str string)`{.descname} [](#scopes.ir-macro.&str "Permalink to this definition"){.headerlink} {#scopes.ir-macro.&str}
 
-.. ir-macro:: (&str string)
+:	
 
-    Constructs a global string constant and returns it as ``rawstring``.
+    Constructs a global string constant and returns it as `rawstring`.
 
 Flow Control
 ------------
 
-.. ir-special:: (block name)
+*ir-special*{.property} `(block name)`{.descname} [](#scopes.ir-special.block "Permalink to this definition"){.headerlink} {#scopes.ir-special.block}
+
+:	
+
+*ir-special*{.property} `(set-block block-expr)`{.descname} [](#scopes.ir-special.set-block "Permalink to this definition"){.headerlink} {#scopes.ir-special.set-block}
 
-.. ir-special:: (set-block block-expr)
+:	
+
+*ir-special*{.property} `(call callee (? argument-value ...))`{.descname} [](#scopes.ir-special.call "Permalink to this definition"){.headerlink} {#scopes.ir-special.call}
 
-.. ir-special:: (call callee (? argument-value ...))
+:	
+
+*ir-special*{.property} `(ret (? return-value))`{.descname} [](#scopes.ir-special.ret "Permalink to this definition"){.headerlink} {#scopes.ir-special.ret}
 
-.. ir-special:: (ret (? return-value))
+:	
 
-.. ir-special:: (br label-value)
+*ir-special*{.property} `(br label-value)`{.descname} [](#scopes.ir-special.br "Permalink to this definition"){.headerlink} {#scopes.ir-special.br}
+
+:	
 
-.. ir-special:: (cond-br value then-label-value else-label-value)
+*ir-special*{.property} `(cond-br value then-label-value else-label-value)`{.descname} [](#scopes.ir-special.cond-br "Permalink to this definition"){.headerlink} {#scopes.ir-special.cond-br}
+
+:	
 
-.. ir-special:: (phi type (? (value label-value) ...))
+*ir-special*{.property} `(phi type (? (value label-value) ...))`{.descname} [](#scopes.ir-special.phi "Permalink to this definition"){.headerlink} {#scopes.ir-special.phi}
+
+:	
 
-.. ir-special:: (incoming phi-value (? (value label-value) ...))
+*ir-special*{.property} `(incoming phi-value (? (value label-value) ...))`{.descname} [](#scopes.ir-special.incoming "Permalink to this definition"){.headerlink} {#scopes.ir-special.incoming}
+
+:	
+
+*ir-macro*{.property} `(? condition-expr then-expr else-expr)`{.descname} [](#scopes.ir-macro.? "Permalink to this definition"){.headerlink} {#scopes.ir-macro.?}
 
-.. ir-macro:: (? condition-expr then-expr else-expr)
+:	
+
+*ir-macro*{.property} `(and? a-expr b-expr)`{.descname} [](#scopes.ir-macro.and? "Permalink to this definition"){.headerlink} {#scopes.ir-macro.and?}
 
-.. ir-macro:: (and? a-expr b-expr)
+:	
+
+*ir-macro*{.property} `(or? a-expr b-expr)`{.descname} [](#scopes.ir-macro.or? "Permalink to this definition"){.headerlink} {#scopes.ir-macro.or?}
 
-.. ir-macro:: (or? a-expr b-expr)
+:	
 
-.. ir-macro:: (if (condition-expr expression ...) ... (? (_:else expression ...)))
+*ir-macro*{.property} `(if (condition-expr expression ...) ... (? (_:else expression ...)))`{.descname} [](#scopes.ir-macro.if "Permalink to this definition"){.headerlink} {#scopes.ir-macro.if}
+
+:	
 
-.. ir-macro:: (loop var-name init-expr condition-expr iterate-expr expression ...)
+*ir-macro*{.property} `(loop var-name init-expr condition-expr iterate-expr expression ...)`{.descname} [](#scopes.ir-macro.loop "Permalink to this definition"){.headerlink} {#scopes.ir-macro.loop}
+
+:	
 
-.. ir-macro:: (assert condition-expr (? exception-expr))
+*ir-macro*{.property} `(assert condition-expr (? exception-expr))`{.descname} [](#scopes.ir-macro.assert "Permalink to this definition"){.headerlink} {#scopes.ir-macro.assert}
+
+:	
 
 Unary Operators
 ---------------
 
-.. ir-macro:: (not pointer-expr)
+*ir-macro*{.property} `(not pointer-expr)`{.descname} [](#scopes.ir-macro.not "Permalink to this definition"){.headerlink} {#scopes.ir-macro.not}
+
+:	
 
 Binary Operators
 ----------------
 
-.. ir-special:: (add lhs rhs)
+*ir-special*{.property} `(add lhs rhs)`{.descname} [](#scopes.ir-special.add "Permalink to this definition"){.headerlink} {#scopes.ir-special.add}
+
+:	
+
+*ir-special*{.property} `(add-nsw lhs rhs)`{.descname} [](#scopes.ir-special.add-nsw "Permalink to this definition"){.headerlink} {#scopes.ir-special.add-nsw}
 
-.. ir-special:: (add-nsw lhs rhs)
+:	
 
-.. ir-special:: (add-nuw lhs rhs)
+*ir-special*{.property} `(add-nuw lhs rhs)`{.descname} [](#scopes.ir-special.add-nuw "Permalink to this definition"){.headerlink} {#scopes.ir-special.add-nuw}
+
+:	
 
-.. ir-special:: (fadd lhs rhs)
+*ir-special*{.property} `(fadd lhs rhs)`{.descname} [](#scopes.ir-special.fadd "Permalink to this definition"){.headerlink} {#scopes.ir-special.fadd}
+
+:	
+
+*ir-special*{.property} `(sub lhs rhs)`{.descname} [](#scopes.ir-special.sub "Permalink to this definition"){.headerlink} {#scopes.ir-special.sub}
 
-.. ir-special:: (sub lhs rhs)
+:	
 
-.. ir-special:: (sub-nsw lhs rhs)
+*ir-special*{.property} `(sub-nsw lhs rhs)`{.descname} [](#scopes.ir-special.sub-nsw "Permalink to this definition"){.headerlink} {#scopes.ir-special.sub-nsw}
+
+:	
 
-.. ir-special:: (sub-nuw lhs rhs)
+*ir-special*{.property} `(sub-nuw lhs rhs)`{.descname} [](#scopes.ir-special.sub-nuw "Permalink to this definition"){.headerlink} {#scopes.ir-special.sub-nuw}
+
+:	
+
+*ir-special*{.property} `(fsub lhs rhs)`{.descname} [](#scopes.ir-special.fsub "Permalink to this definition"){.headerlink} {#scopes.ir-special.fsub}
 
-.. ir-special:: (fsub lhs rhs)
+:	
 
-.. ir-special:: (mul lhs rhs)
+*ir-special*{.property} `(mul lhs rhs)`{.descname} [](#scopes.ir-special.mul "Permalink to this definition"){.headerlink} {#scopes.ir-special.mul}
+
+:	
 
-.. ir-special:: (mul-nsw lhs rhs)
+*ir-special*{.property} `(mul-nsw lhs rhs)`{.descname} [](#scopes.ir-special.mul-nsw "Permalink to this definition"){.headerlink} {#scopes.ir-special.mul-nsw}
+
+:	
+
+*ir-special*{.property} `(mul-nuw lhs rhs)`{.descname} [](#scopes.ir-special.mul-nuw "Permalink to this definition"){.headerlink} {#scopes.ir-special.mul-nuw}
 
-.. ir-special:: (mul-nuw lhs rhs)
+:	
 
-.. ir-special:: (fmul lhs rhs)
+*ir-special*{.property} `(fmul lhs rhs)`{.descname} [](#scopes.ir-special.fmul "Permalink to this definition"){.headerlink} {#scopes.ir-special.fmul}
+
+:	
 
-.. ir-special:: (udiv lhs rhs)
+*ir-special*{.property} `(udiv lhs rhs)`{.descname} [](#scopes.ir-special.udiv "Permalink to this definition"){.headerlink} {#scopes.ir-special.udiv}
+
+:	
+
+*ir-special*{.property} `(sdiv lhs rhs)`{.descname} [](#scopes.ir-special.sdiv "Permalink to this definition"){.headerlink} {#scopes.ir-special.sdiv}
 
-.. ir-special:: (sdiv lhs rhs)
+:	
 
-.. ir-special:: (exact-sdiv lhs rhs)
+*ir-special*{.property} `(exact-sdiv lhs rhs)`{.descname} [](#scopes.ir-special.exact-sdiv "Permalink to this definition"){.headerlink} {#scopes.ir-special.exact-sdiv}
+
+:	
 
-.. ir-special:: (urem lhs rhs)
+*ir-special*{.property} `(urem lhs rhs)`{.descname} [](#scopes.ir-special.urem "Permalink to this definition"){.headerlink} {#scopes.ir-special.urem}
+
+:	
+
+*ir-special*{.property} `(srem lhs rhs)`{.descname} [](#scopes.ir-special.srem "Permalink to this definition"){.headerlink} {#scopes.ir-special.srem}
 
-.. ir-special:: (srem lhs rhs)
+:	
 
-.. ir-special:: (frem lhs rhs)
+*ir-special*{.property} `(frem lhs rhs)`{.descname} [](#scopes.ir-special.frem "Permalink to this definition"){.headerlink} {#scopes.ir-special.frem}
+
+:	
 
-.. ir-special:: (shl lhs rhs)
+*ir-special*{.property} `(shl lhs rhs)`{.descname} [](#scopes.ir-special.shl "Permalink to this definition"){.headerlink} {#scopes.ir-special.shl}
+
+:	
+
+*ir-special*{.property} `(lshr lhs rhs)`{.descname} [](#scopes.ir-special.lshr "Permalink to this definition"){.headerlink} {#scopes.ir-special.lshr}
 
-.. ir-special:: (lshr lhs rhs)
+:	
 
-.. ir-special:: (ashr lhs rhs)
+*ir-special*{.property} `(ashr lhs rhs)`{.descname} [](#scopes.ir-special.ashr "Permalink to this definition"){.headerlink} {#scopes.ir-special.ashr}
+
+:	
 
-.. ir-special:: (and lhs rhs)
+*ir-special*{.property} `(and lhs rhs)`{.descname} [](#scopes.ir-special.and "Permalink to this definition"){.headerlink} {#scopes.ir-special.and}
+
+:	
+
+*ir-special*{.property} `(or lhs rhs)`{.descname} [](#scopes.ir-special.or "Permalink to this definition"){.headerlink} {#scopes.ir-special.or}
 
-.. ir-special:: (or lhs rhs)
+:	
 
-.. ir-special:: (xor lhs rhs)
+*ir-special*{.property} `(xor lhs rhs)`{.descname} [](#scopes.ir-special.xor "Permalink to this definition"){.headerlink} {#scopes.ir-special.xor}
+
+:	
 
 Comparators
 -----------
 
-.. ir-special:: (icmp op lhs rhs)
+*ir-special*{.property} `(icmp op lhs rhs)`{.descname} [](#scopes.ir-special.icmp "Permalink to this definition"){.headerlink} {#scopes.ir-special.icmp}
+
+:	
 
-.. ir-special:: (fcmp op lhs rhs)
+*ir-special*{.property} `(fcmp op lhs rhs)`{.descname} [](#scopes.ir-special.fcmp "Permalink to this definition"){.headerlink} {#scopes.ir-special.fcmp}
+
+:	
 
-.. ir-special:: (select condition-expr then-value else-value)
+*ir-special*{.property} `(select condition-expr then-value else-value)`{.descname} [](#scopes.ir-special.select "Permalink to this definition"){.headerlink} {#scopes.ir-special.select}
+
+:	
 
-.. ir-macro:: (null? pointer-expr)
+*ir-macro*{.property} `(null? pointer-expr)`{.descname} [](#scopes.ir-macro.null? "Permalink to this definition"){.headerlink} {#scopes.ir-macro.null?}
+
+:	
 
 Composition
 -----------
 
-.. ir-special:: (getelementptr value (? index-value ...))
+*ir-special*{.property} `(getelementptr value (? index-value ...))`{.descname} [](#scopes.ir-special.getelementptr "Permalink to this definition"){.headerlink} {#scopes.ir-special.getelementptr}
+
+:	
+
+*ir-special*{.property} `(extractelement value index)`{.descname} [](#scopes.ir-special.extractelement "Permalink to this definition"){.headerlink} {#scopes.ir-special.extractelement}
 
-.. ir-special:: (extractelement value index)
+:	
 
-.. ir-special:: (insertelement value element index)
+*ir-special*{.property} `(insertelement value element index)`{.descname} [](#scopes.ir-special.insertelement "Permalink to this definition"){.headerlink} {#scopes.ir-special.insertelement}
+
+:	
 
-.. ir-special:: (shufflevector value1 value2 mask)
+*ir-special*{.property} `(shufflevector value1 value2 mask)`{.descname} [](#scopes.ir-special.shufflevector "Permalink to this definition"){.headerlink} {#scopes.ir-special.shufflevector}
+
+:	
+
+*ir-special*{.property} `(extractvalue value index)`{.descname} [](#scopes.ir-special.extractvalue "Permalink to this definition"){.headerlink} {#scopes.ir-special.extractvalue}
 
-.. ir-special:: (extractvalue value index)
+:	
 
-.. ir-special:: (insertvalue value element index)
+*ir-special*{.property} `(insertvalue value element index)`{.descname} [](#scopes.ir-special.insertvalue "Permalink to this definition"){.headerlink} {#scopes.ir-special.insertvalue}
+
+:	
 
 Memory
 ------
 
-.. ir-special:: (align value bytes)
+*ir-special*{.property} `(align value bytes)`{.descname} [](#scopes.ir-special.align "Permalink to this definition"){.headerlink} {#scopes.ir-special.align}
+
+:	
 
-.. ir-special:: (load from-value)
+*ir-special*{.property} `(load from-value)`{.descname} [](#scopes.ir-special.load "Permalink to this definition"){.headerlink} {#scopes.ir-special.load}
+
+:	
+
+*ir-special*{.property} `(store from-value to-value)`{.descname} [](#scopes.ir-special.store "Permalink to this definition"){.headerlink} {#scopes.ir-special.store}
 
-.. ir-special:: (store from-value to-value)
+:	
+
+*ir-special*{.property} `(alloca type (? count-value))`{.descname} [](#scopes.ir-special.alloca "Permalink to this definition"){.headerlink} {#scopes.ir-special.alloca}
 
-.. ir-special:: (alloca type (? count-value))
+:	
 
-.. ir-special:: (va_arg va_list-value type)
+*ir-special*{.property} `(va_arg va_list-value type)`{.descname} [](#scopes.ir-special.va_arg "Permalink to this definition"){.headerlink} {#scopes.ir-special.va_arg}
+
+:	
 
 Global Values
 -------------
 
-.. ir-special:: (constant global-value)
+*ir-special*{.property} `(constant global-value)`{.descname} [](#scopes.ir-special.constant "Permalink to this definition"){.headerlink} {#scopes.ir-special.constant}
+
+:	
 
-.. ir-special:: (global name constant-value)
+*ir-special*{.property} `(global name constant-value)`{.descname} [](#scopes.ir-special.global "Permalink to this definition"){.headerlink} {#scopes.ir-special.global}
+
+:	
 
 Casting
 -------
 
-.. ir-special:: (trunc value type)
+*ir-special*{.property} `(trunc value type)`{.descname} [](#scopes.ir-special.trunc "Permalink to this definition"){.headerlink} {#scopes.ir-special.trunc}
+
+:	
+
+*ir-special*{.property} `(zext value type)`{.descname} [](#scopes.ir-special.zext "Permalink to this definition"){.headerlink} {#scopes.ir-special.zext}
 
-.. ir-special:: (zext value type)
+:	
 
-.. ir-special:: (sext value type)
+*ir-special*{.property} `(sext value type)`{.descname} [](#scopes.ir-special.sext "Permalink to this definition"){.headerlink} {#scopes.ir-special.sext}
+
+:	
 
-.. ir-special:: (fptrunc value type)
+*ir-special*{.property} `(fptrunc value type)`{.descname} [](#scopes.ir-special.fptrunc "Permalink to this definition"){.headerlink} {#scopes.ir-special.fptrunc}
+
+:	
+
+*ir-special*{.property} `(fpext value type)`{.descname} [](#scopes.ir-special.fpext "Permalink to this definition"){.headerlink} {#scopes.ir-special.fpext}
 
-.. ir-special:: (fpext value type)
+:	
+
+*ir-special*{.property} `(fptoui value type)`{.descname} [](#scopes.ir-special.fptoui "Permalink to this definition"){.headerlink} {#scopes.ir-special.fptoui}
 
-.. ir-special:: (fptoui value type)
+:	
+
+*ir-special*{.property} `(fptosi value type)`{.descname} [](#scopes.ir-special.fptosi "Permalink to this definition"){.headerlink} {#scopes.ir-special.fptosi}
 
-.. ir-special:: (fptosi value type)
+:	
+
+*ir-special*{.property} `(uitofp value type)`{.descname} [](#scopes.ir-special.uitofp "Permalink to this definition"){.headerlink} {#scopes.ir-special.uitofp}
+
+:	
 
-.. ir-special:: (uitofp value type)
+*ir-special*{.property} `(sitofp value type)`{.descname} [](#scopes.ir-special.sitofp "Permalink to this definition"){.headerlink} {#scopes.ir-special.sitofp}
 
-.. ir-special:: (sitofp value type)
+:	
+
+*ir-special*{.property} `(ptrtoint value type)`{.descname} [](#scopes.ir-special.ptrtoint "Permalink to this definition"){.headerlink} {#scopes.ir-special.ptrtoint}
 
-.. ir-special:: (ptrtoint value type)
+:	
 
-.. ir-special:: (intotptr value type)
+*ir-special*{.property} `(intotptr value type)`{.descname} [](#scopes.ir-special.intotptr "Permalink to this definition"){.headerlink} {#scopes.ir-special.intotptr}
+
+:	
 
-.. ir-special:: (bitcast value type)
+*ir-special*{.property} `(bitcast value type)`{.descname} [](#scopes.ir-special.bitcast "Permalink to this definition"){.headerlink} {#scopes.ir-special.bitcast}
+
+:	
 
-.. ir-special:: (addrspacecast value type)
+*ir-special*{.property} `(addrspacecast value type)`{.descname} [](#scopes.ir-special.addrspacecast "Permalink to this definition"){.headerlink} {#scopes.ir-special.addrspacecast}
+
+:	
 
 Debugging
 ---------
 
-.. ir-special:: (dump-module)
+*ir-special*{.property} `(dump-module)`{.descname} [](#scopes.ir-special.dump-module)`{.descname} "Permalink to this definition"){.headerlink} {#scopes.ir-special.dump-module)`{.descname}}
+
+:	
+
+*ir-special*{.property} `(dump value)`{.descname} [](#scopes.ir-special.dump "Permalink to this definition"){.headerlink} {#scopes.ir-special.dump}
 
-.. ir-special:: (dump value)
+:	
 
-.. ir-special:: (dumptype type)
+*ir-special*{.property} `(dumptype type)`{.descname} [](#scopes.ir-special.dumptype "Permalink to this definition"){.headerlink} {#scopes.ir-special.dumptype}
+
+:	
 
 Metaprogramming
 ---------------
 
-.. ir-special:: (include filename-string)
+*ir-special*{.property} `(include filename-string)`{.descname} [](#scopes.ir-special.include "Permalink to this definition"){.headerlink} {#scopes.ir-special.include}
 
-    Includes expressions from another source file into the module currently being
-    defined. ``filename-string`` is the path to the source file to be included,
+:	Includes expressions from another source file into the module currently being
+    defined. `filename-string` is the path to the source file to be included,
     relative to the path of the expression's anchor.
 
-.. ir-special:: (execute function-value)
+*ir-special*{.property} `(execute function-value)`{.descname} [](#scopes.ir-special.execute "Permalink to this definition"){.headerlink} {#scopes.ir-special.execute}
 
-    Executes a function in the module as it is being defined. The function must
-    match the signature ``(function void [Environment])``. If the environment
+:	Executes a function in the module as it is being defined. The function must
+    match the signature `(function void [Environment])`. If the environment
     parameter is defined, then the currently active translation environment
     will be passed.
 
-.. ir-macro:: (run expression ...)
+*ir-macro*{.property} `(run expression ...)`{.descname} [](#scopes.ir-macro.run "Permalink to this definition"){.headerlink} {#scopes.ir-macro.run}
+
+:	
 
-.. ir-special:: (module name (| _:IR language) (? expression ...))
+*ir-special*{.property} `(module name (| _:IR language) (? expression ...))`{.descname} [](#scopes.ir-special.module "Permalink to this definition"){.headerlink} {#scopes.ir-special.module}
 
-    Declares a new LLVM module with a new empty namespace. ``language`` must be
-    a name with which a preprocessor has been registered, or ``IR`` for the
+:	Declares a new LLVM module with a new empty namespace. `language` must be
+    a name with which a preprocessor has been registered, or `IR` for the
     default.
 
-.. ir-special:: (quote type element)
+*ir-special*{.property} `(quote type element)`{.descname} [](#scopes.ir-special.quote "Permalink to this definition"){.headerlink} {#scopes.ir-special.quote}
 
-    Adds the symbolic expression ``element`` as global constant pointer to the
+:	Adds the symbolic expression `element` as global constant pointer to the
     module currently being defined and returns its value handle. This allows
     programs to create and process properly anchored expressions.
 
-.. ir-special:: (splice (? expression ...))
+*ir-special*{.property} `(splice (? expression ...))`{.descname} [](#scopes.ir-special.splice "Permalink to this definition"){.headerlink} {#scopes.ir-special.splice}
+
+:	
+
+*ir-macro*{.property} `(print (? value ...))`{.descname} [](#scopes.ir-macro.print "Permalink to this definition"){.headerlink} {#scopes.ir-macro.print}
 
-.. ir-macro:: (print (? value ...))
+:	
 
-.. ir-macro:: (handle pointer-value)
+*ir-macro*{.property} `(handle pointer-value)`{.descname} [](#scopes.ir-macro.handle "Permalink to this definition"){.headerlink} {#scopes.ir-macro.handle}
+
+:	
 
-.. ir-macro:: (table (? (key value) ...))
+*ir-macro*{.property} `(table (? (key value) ...))`{.descname} [](#scopes.ir-macro.table "Permalink to this definition"){.headerlink} {#scopes.ir-macro.table}
 
-.. ir-special:: (error message-string expression)
+:	
+
+*ir-special*{.property} `(error message-string expression)`{.descname} [](#scopes.ir-special.error "Permalink to this definition"){.headerlink} {#scopes.ir-special.error}
 
-.. ir-special:: (nop)
+:	
 
-    Ponders the futility of existence.
+*ir-special*{.property} `(nop)`{.descname} [](#scopes.ir-special.nop "Permalink to this definition"){.headerlink} {#scopes.ir-special.nop}
+
+:	Ponders the futility of existence.

          
M doc/docs/lang.md +1 -2
@@ 9,8 9,7 @@ Functions
 
 yes yes
 
-Variable Arguments
-^^^^^^^^^^^^^^^^^^
+### Variable Arguments ###
 
 Bindings
 --------

          
M doc/docs/module-Array.md +145 -111
@@ 1,120 1,154 @@ 
-Array
-=====
-
-Provides mutable array types that store their elements on the heap rather
-than in registers or the stack.
+<style type="text/css" rel="stylesheet">body { counter-reset: chapter 7; }</style>
+
+Array
+=====
+
+Provides mutable array types that store their elements on the heap rather
+than in registers or the stack.
+
+*type*{.property} `Array`{.descname} [](#scopes.type.Array "Permalink to this definition"){.headerlink} {#scopes.type.Array}
+
+:   An opaque type of supertype `Struct`.
+
+    *fn*{.property} `__@`{.descname} (*&ensp;self index&ensp;*)[](#scopes.Array.fn.__@ "Permalink to this definition"){.headerlink} {#scopes.Array.fn.__@}
+
+    :   Implements support for the `@` operator. Returns a view reference to the
+        element at `index` of array `self`.
 
-.. type:: Array
+    *inline*{.property} `__as`{.descname} (*&ensp;cls T&ensp;*)[](#scopes.Array.inline.__as "Permalink to this definition"){.headerlink} {#scopes.Array.inline.__as}
+
+    :   Implements support for the `as` operator. Arrays can be cast to
+        `Generator`, or directly passed to `for`.
+
+    *inline*{.property} `__countof`{.descname} (*&ensp;self&ensp;*)[](#scopes.Array.inline.__countof "Permalink to this definition"){.headerlink} {#scopes.Array.inline.__countof}
 
-   An opaque type of supertype `Struct`.
+    :   Implements support for the `countof` operator. Returns the current
+        number of elements stored in `self` as a value of `usize` type.
+
+    *inline*{.property} `__drop`{.descname} (*&ensp;self&ensp;*)[](#scopes.Array.inline.__drop "Permalink to this definition"){.headerlink} {#scopes.Array.inline.__drop}
+
+    :   Implements support for freeing the array's memory when it goes out
+        of scope.
+
+    *inline*{.property} `__imply`{.descname} (*&ensp;cls T&ensp;*)[](#scopes.Array.inline.__imply "Permalink to this definition"){.headerlink} {#scopes.Array.inline.__imply}
 
-   .. fn:: (__@ self index)
-      
-      Implements support for the `@` operator. Returns a view reference to the
-      element at `index` of array `self`.
-   .. inline:: (__as cls T)
-      
-      Implements support for the `as` operator. Arrays can be cast to
-      `Generator`, or directly passed to `for`.
-   .. inline:: (__countof self)
-      
-      Implements support for the `countof` operator. Returns the current
-      number of elements stored in `self` as a value of `usize` type.
-   .. inline:: (__drop self)
-      
-      Implements support for freeing the array's memory when it goes out
-      of scope.
-   .. inline:: (__imply cls T)
-      
-      Implements support for pointer casts, to pass the array to C functions
-      for example.
-   .. inline:: (__typecall cls element-type capacity)
-      
-      Construct a mutable array type of ``element-type`` with a variable or
-      fixed maximum capacity.
-      
-      If ``capacity`` is defined, then it specifies the maximum number
-      of array elements permitted. If it is undefined, then an initial
-      capacity of 16 elements is assumed, which is doubled whenever
-      it is exceeded, allowing for an indefinite number of elements.
-   .. fn:: (append self value)
-      
-      Append `value` as an element to the array `self` and return a reference
-      to the new element. When the `array` is of `GrowingArray` type, this
-      operation will transparently resize the array's storage.
-   .. fn:: (clear self)
-      
-      Clear the array and reset its element count to zero. This will drop
-      all elements that have been previously contained by the array.
-   .. inline:: (emplace-append self args...)
-      
-      Construct a new element with arguments `args...` directly in a newly
-      assigned slot of array `self`. When the `array` is of `GrowingArray`
-      type, this operation will transparently resize the array's storage.
-   .. inline:: (emplace-append-many self size args...)
-      
-      Construct a new element with arguments `args...` directly in a newly
-      assigned slot of array `self`. When the `array` is of `GrowingArray`
-      type, this operation will transparently resize the array's storage.
-   .. type:: insert
+    :   Implements support for pointer casts, to pass the array to C functions
+        for example.
+
+    *inline*{.property} `__typecall`{.descname} (*&ensp;cls element-type capacity&ensp;*)[](#scopes.Array.inline.__typecall "Permalink to this definition"){.headerlink} {#scopes.Array.inline.__typecall}
+
+    :   Construct a mutable array type of ``element-type`` with a variable or
+        fixed maximum capacity.
+        
+        If ``capacity`` is defined, then it specifies the maximum number
+        of array elements permitted. If it is undefined, then an initial
+        capacity of 16 elements is assumed, which is doubled whenever
+        it is exceeded, allowing for an indefinite number of elements.
+
+    *fn*{.property} `append`{.descname} (*&ensp;self value&ensp;*)[](#scopes.Array.fn.append "Permalink to this definition"){.headerlink} {#scopes.Array.fn.append}
+
+    :   Append `value` as an element to the array `self` and return a reference
+        to the new element. When the `array` is of `GrowingArray` type, this
+        operation will transparently resize the array's storage.
+
+    *fn*{.property} `clear`{.descname} (*&ensp;self&ensp;*)[](#scopes.Array.fn.clear "Permalink to this definition"){.headerlink} {#scopes.Array.fn.clear}
+
+    :   Clear the array and reset its element count to zero. This will drop
+        all elements that have been previously contained by the array.
+
+    *inline*{.property} `emplace-append`{.descname} (*&ensp;self args...&ensp;*)[](#scopes.Array.inline.emplace-append "Permalink to this definition"){.headerlink} {#scopes.Array.inline.emplace-append}
+
+    :   Construct a new element with arguments `args...` directly in a newly
+        assigned slot of array `self`. When the `array` is of `GrowingArray`
+        type, this operation will transparently resize the array's storage.
+
+    *inline*{.property} `emplace-append-many`{.descname} (*&ensp;self size args...&ensp;*)[](#scopes.Array.inline.emplace-append-many "Permalink to this definition"){.headerlink} {#scopes.Array.inline.emplace-append-many}
+
+    :   Construct a new element with arguments `args...` directly in a newly
+        assigned slot of array `self`. When the `array` is of `GrowingArray`
+        type, this operation will transparently resize the array's storage.
+
+    *type*{.property} `insert`{.descname} [](#scopes.Array.type.insert "Permalink to this definition"){.headerlink} {#scopes.Array.type.insert}
 
-      
-      Insert `value` at `index` into the array `self` and return a reference
-      to the new element. When the `array` is of `GrowingArray` type, this
-      operation will transparently resize the array's storage.
-      This operation offsets the index of each following element by 1.
-      If index is omitted, `insert` operates like `append`.
+    :   Insert `value` at `index` into the array `self` and return a reference
+        to the new element. When the `array` is of `GrowingArray` type, this
+        operation will transparently resize the array's storage.
+        This operation offsets the index of each following element by 1.
+        If index is omitted, `insert` operates like `append`.
+
+    *fn*{.property} `last`{.descname} (*&ensp;self&ensp;*)[](#scopes.Array.fn.last "Permalink to this definition"){.headerlink} {#scopes.Array.fn.last}
+
+    :   
+
+    *fn*{.property} `pop`{.descname} (*&ensp;self&ensp;*)[](#scopes.Array.fn.pop "Permalink to this definition"){.headerlink} {#scopes.Array.fn.pop}
+
+    :   Remove element with highest index from array `self` and return it.
+
+    *fn*{.property} `remove`{.descname} (*&ensp;self index&ensp;*)[](#scopes.Array.fn.remove "Permalink to this definition"){.headerlink} {#scopes.Array.fn.remove}
+
+    :   Remove element at index from array `self` and return it.
+        This operation offsets the index of each following element by -1.
+
+    *fn*{.property} `resize`{.descname} (*&ensp;self count args...&ensp;*)[](#scopes.Array.fn.resize "Permalink to this definition"){.headerlink} {#scopes.Array.fn.resize}
+
+    :   Resize the array to the specified count. Items are apppend or removed
+        to meet the desired count.
+
+    *inline*{.property} `reverse`{.descname} (*&ensp;self&ensp;*)[](#scopes.Array.inline.reverse "Permalink to this definition"){.headerlink} {#scopes.Array.inline.reverse}
+
+    :   
+
+    *inline*{.property} `sort`{.descname} (*&ensp;self key ...&ensp;*)[](#scopes.Array.inline.sort "Permalink to this definition"){.headerlink} {#scopes.Array.inline.sort}
+
+    :   Sort elements of array `self` from smallest to largest, either using
+        the `<` operator supplied by the element type, or by using the key
+        supplied by the callable `key`, which is expected to return a comparable
+        value for each element value supplied.
+
+    *fn*{.property} `swap`{.descname} (*&ensp;self a b&ensp;*)[](#scopes.Array.fn.swap "Permalink to this definition"){.headerlink} {#scopes.Array.fn.swap}
+
+    :   Safely swap the contents of two indices.
+
+*type*{.property} `FixedArray`{.descname} [](#scopes.type.FixedArray "Permalink to this definition"){.headerlink} {#scopes.type.FixedArray}
 
-   .. fn:: (last self)
-   .. fn:: (pop self)
-      
-      Remove element with highest index from array `self` and return it.
-   .. fn:: (remove self index)
-      
-      Remove element at index from array `self` and return it.
-      This operation offsets the index of each following element by -1.
-   .. fn:: (resize self count args...)
-      
-      Resize the array to the specified count. Items are apppend or removed
-      to meet the desired count.
-   .. inline:: (reverse self)
-   .. inline:: (sort self key ...)
-      
-      Sort elements of array `self` from smallest to largest, either using
-      the `<` operator supplied by the element type, or by using the key
-      supplied by the callable `key`, which is expected to return a comparable
-      value for each element value supplied.
-   .. fn:: (swap self a b)
-      
-      Safely swap the contents of two indices.
-.. type:: FixedArray
+:   An opaque type of supertype `Array`.
+
+    *fn*{.property} `__repr`{.descname} (*&ensp;self&ensp;*)[](#scopes.FixedArray.fn.__repr "Permalink to this definition"){.headerlink} {#scopes.FixedArray.fn.__repr}
+
+    :   Implements support for the `repr` operation.
+
+    *inline*{.property} `__typecall`{.descname} (*&ensp;cls opts...&ensp;*)[](#scopes.FixedArray.inline.__typecall "Permalink to this definition"){.headerlink} {#scopes.FixedArray.inline.__typecall}
+
+    :   
 
-   An opaque type of supertype `Array`.
+    *inline*{.property} `capacity`{.descname} (*&ensp;self&ensp;*)[](#scopes.FixedArray.inline.capacity "Permalink to this definition"){.headerlink} {#scopes.FixedArray.inline.capacity}
+
+    :   Returns the maximum capacity of array `self`, which is fixed.
+
+    *fn*{.property} `reserve`{.descname} (*&ensp;self count&ensp;*)[](#scopes.FixedArray.fn.reserve "Permalink to this definition"){.headerlink} {#scopes.FixedArray.fn.reserve}
+
+    :   Internally used by the type. Ensures that array `self` can hold at least
+        `count` elements. A fixed array will raise an assertion when its
+        capacity has been exceeded.
 
-   .. fn:: (__repr self)
-      
-      Implements support for the `repr` operation.
-   .. inline:: (__typecall cls opts...)
-   .. inline:: (capacity self)
-      
-      Returns the maximum capacity of array `self`, which is fixed.
-   .. fn:: (reserve self count)
-      
-      Internally used by the type. Ensures that array `self` can hold at least
-      `count` elements. A fixed array will raise an assertion when its
-      capacity has been exceeded.
-.. type:: GrowingArray
+*type*{.property} `GrowingArray`{.descname} [](#scopes.type.GrowingArray "Permalink to this definition"){.headerlink} {#scopes.type.GrowingArray}
+
+:   An opaque type of supertype `Array`.
+
+    *fn*{.property} `__repr`{.descname} (*&ensp;self&ensp;*)[](#scopes.GrowingArray.fn.__repr "Permalink to this definition"){.headerlink} {#scopes.GrowingArray.fn.__repr}
+
+    :   Implements support for the `repr` operation.
+
+    *inline*{.property} `__typecall`{.descname} (*&ensp;cls opts...&ensp;*)[](#scopes.GrowingArray.inline.__typecall "Permalink to this definition"){.headerlink} {#scopes.GrowingArray.inline.__typecall}
 
-   An opaque type of supertype `Array`.
+    :   
+
+    *inline*{.property} `capacity`{.descname} (*&ensp;self&ensp;*)[](#scopes.GrowingArray.inline.capacity "Permalink to this definition"){.headerlink} {#scopes.GrowingArray.inline.capacity}
+
+    :   Returns the current maximum capacity of array `self`.
 
-   .. fn:: (__repr self)
-      
-      Implements support for the `repr` operation.
-   .. inline:: (__typecall cls opts...)
-   .. inline:: (capacity self)
-      
-      Returns the current maximum capacity of array `self`.
-   .. fn:: (reserve self count)
-      
-      Internally used by the type. Ensures that array `self` can hold at least
-      `count` elements. A growing array will always attempt to comply.
+    *fn*{.property} `reserve`{.descname} (*&ensp;self count&ensp;*)[](#scopes.GrowingArray.fn.reserve "Permalink to this definition"){.headerlink} {#scopes.GrowingArray.fn.reserve}
+
+    :   Internally used by the type. Ensures that array `self` can hold at least
+        `count` elements. A growing array will always attempt to comply.
+

          
M doc/docs/module-Box.md +60 -16
@@ 1,23 1,67 @@ 
+<style type="text/css" rel="stylesheet">body { counter-reset: chapter 8; }</style>
+
 Box
 ===
 
 Provides a unique reference container for heap allocated values.
 
-.. type:: Box
+*type*{.property} `Box`{.descname} [](#scopes.type.Box "Permalink to this definition"){.headerlink} {#scopes.type.Box}
+
+:   An opaque type.
+
+    *spice*{.property} `__=`{.descname} (*&ensp;...&ensp;*)[](#scopes.Box.spice.__= "Permalink to this definition"){.headerlink} {#scopes.Box.spice.__=}
+
+    :   
+
+    *inline*{.property} `__@`{.descname} (*&ensp;self keys...&ensp;*)[](#scopes.Box.inline.__@ "Permalink to this definition"){.headerlink} {#scopes.Box.inline.__@}
+
+    :   
+
+    *spice*{.property} `__as`{.descname} (*&ensp;...&ensp;*)[](#scopes.Box.spice.__as "Permalink to this definition"){.headerlink} {#scopes.Box.spice.__as}
 
-   An opaque type.
+    :   
+
+    *inline*{.property} `__countof`{.descname} (*&ensp;self&ensp;*)[](#scopes.Box.inline.__countof "Permalink to this definition"){.headerlink} {#scopes.Box.inline.__countof}
+
+    :   
+
+    *inline*{.property} `__drop`{.descname} (*&ensp;self&ensp;*)[](#scopes.Box.inline.__drop "Permalink to this definition"){.headerlink} {#scopes.Box.inline.__drop}
+
+    :   
+
+    *spice*{.property} `__getattr`{.descname} (*&ensp;...&ensp;*)[](#scopes.Box.spice.__getattr "Permalink to this definition"){.headerlink} {#scopes.Box.spice.__getattr}
+
+    :   
+
+    *spice*{.property} `__imply`{.descname} (*&ensp;...&ensp;*)[](#scopes.Box.spice.__imply "Permalink to this definition"){.headerlink} {#scopes.Box.spice.__imply}
 
-   .. spice:: (__= ...)
-   .. inline:: (__@ self keys...)
-   .. spice:: (__as ...)
-   .. inline:: (__countof self)
-   .. inline:: (__drop self)
-   .. spice:: (__getattr ...)
-   .. spice:: (__imply ...)
-   .. spice:: (__methodcall ...)
-   .. inline:: (__repr self)
-   .. spice:: (__static-imply ...)
-   .. inline:: (make-cast-op f const?)
-   .. inline:: (new T args...)
-   .. inline:: (view self)
-   .. inline:: (wrap value)
+    :   
+
+    *spice*{.property} `__methodcall`{.descname} (*&ensp;...&ensp;*)[](#scopes.Box.spice.__methodcall "Permalink to this definition"){.headerlink} {#scopes.Box.spice.__methodcall}
+
+    :   
+
+    *inline*{.property} `__repr`{.descname} (*&ensp;self&ensp;*)[](#scopes.Box.inline.__repr "Permalink to this definition"){.headerlink} {#scopes.Box.inline.__repr}
+
+    :   
+
+    *spice*{.property} `__static-imply`{.descname} (*&ensp;...&ensp;*)[](#scopes.Box.spice.__static-imply "Permalink to this definition"){.headerlink} {#scopes.Box.spice.__static-imply}
+
+    :   
+
+    *inline*{.property} `make-cast-op`{.descname} (*&ensp;f const?&ensp;*)[](#scopes.Box.inline.make-cast-op "Permalink to this definition"){.headerlink} {#scopes.Box.inline.make-cast-op}
+
+    :   
+
+    *inline*{.property} `new`{.descname} (*&ensp;T args...&ensp;*)[](#scopes.Box.inline.new "Permalink to this definition"){.headerlink} {#scopes.Box.inline.new}
+
+    :   
+
+    *inline*{.property} `view`{.descname} (*&ensp;self&ensp;*)[](#scopes.Box.inline.view "Permalink to this definition"){.headerlink} {#scopes.Box.inline.view}
+
+    :   
+
+    *inline*{.property} `wrap`{.descname} (*&ensp;value&ensp;*)[](#scopes.Box.inline.wrap "Permalink to this definition"){.headerlink} {#scopes.Box.inline.wrap}
+
+    :   
+

          
M doc/docs/module-Capture.md +60 -19
@@ 1,31 1,72 @@ 
+<style type="text/css" rel="stylesheet">body { counter-reset: chapter 9; }</style>
+
 Capture
 =======
 
 A capture is a runtime closure that transparently captures (hence the name)
 runtime values outside of the function.
 
-.. type:: Capture
+*type*{.property} `Capture`{.descname} [](#scopes.type.Capture "Permalink to this definition"){.headerlink} {#scopes.type.Capture}
+
+:   An opaque type.
+
+    *inline*{.property} `__call`{.descname} (*&ensp;self args...&ensp;*)[](#scopes.Capture.inline.__call "Permalink to this definition"){.headerlink} {#scopes.Capture.inline.__call}
+
+    :   
 
-   An opaque type.
+    *inline*{.property} `__drop`{.descname} (*&ensp;self&ensp;*)[](#scopes.Capture.inline.__drop "Permalink to this definition"){.headerlink} {#scopes.Capture.inline.__drop}
+
+    :   
+
+    *inline*{.property} `__typecall`{.descname} (*&ensp;cls args...&ensp;*)[](#scopes.Capture.inline.__typecall "Permalink to this definition"){.headerlink} {#scopes.Capture.inline.__typecall}
+
+    :   
 
-   .. inline:: (__call self args...)
-   .. inline:: (__drop self)
-   .. inline:: (__typecall cls args...)
-   .. inline:: (function return-type param-types...)
-   .. inline:: (make-type ...)
-.. type:: CaptureTemplate
+    *inline*{.property} `function`{.descname} (*&ensp;return-type param-types...&ensp;*)[](#scopes.Capture.inline.function "Permalink to this definition"){.headerlink} {#scopes.Capture.inline.function}
+
+    :   
+
+    *inline*{.property} `make-type`{.descname} (*&ensp;...&ensp;*)[](#scopes.Capture.inline.make-type "Permalink to this definition"){.headerlink} {#scopes.Capture.inline.make-type}
+
+    :   
 
-   An opaque type.
+*type*{.property} `CaptureTemplate`{.descname} [](#scopes.type.CaptureTemplate "Permalink to this definition"){.headerlink} {#scopes.type.CaptureTemplate}
+
+:   An opaque type.
+
+    *inline*{.property} `__drop`{.descname} (*&ensp;self&ensp;*)[](#scopes.CaptureTemplate.inline.__drop "Permalink to this definition"){.headerlink} {#scopes.CaptureTemplate.inline.__drop}
+
+    :   
 
-   .. inline:: (__drop self)
-   .. spice:: (__imply ...)
-   .. inline:: (build-instance self f)
-   .. inline:: (instance self types...)
-   .. inline:: (typify-function cls types...)
-.. type:: SpiceCapture
+    *spice*{.property} `__imply`{.descname} (*&ensp;...&ensp;*)[](#scopes.CaptureTemplate.spice.__imply "Permalink to this definition"){.headerlink} {#scopes.CaptureTemplate.spice.__imply}
+
+    :   
+
+    *inline*{.property} `build-instance`{.descname} (*&ensp;self f&ensp;*)[](#scopes.CaptureTemplate.inline.build-instance "Permalink to this definition"){.headerlink} {#scopes.CaptureTemplate.inline.build-instance}
+
+    :   
+
+    *inline*{.property} `instance`{.descname} (*&ensp;self types...&ensp;*)[](#scopes.CaptureTemplate.inline.instance "Permalink to this definition"){.headerlink} {#scopes.CaptureTemplate.inline.instance}
+
+    :   
+
+    *inline*{.property} `typify-function`{.descname} (*&ensp;cls types...&ensp;*)[](#scopes.CaptureTemplate.inline.typify-function "Permalink to this definition"){.headerlink} {#scopes.CaptureTemplate.inline.typify-function}
+
+    :   
 
-   An opaque type.
+*type*{.property} `SpiceCapture`{.descname} [](#scopes.type.SpiceCapture "Permalink to this definition"){.headerlink} {#scopes.type.SpiceCapture}
+
+:   An opaque type.
+
+*sugar*{.property} (`capture`{.descname} *&ensp;...&ensp;*) [](#scopes.sugar.capture "Permalink to this definition"){.headerlink} {#scopes.sugar.capture}
+
+:   
 
-.. sugar:: (capture ...)
-.. sugar:: (decorate-capture ...)
-.. sugar:: (spice-capture ...)
+*sugar*{.property} (`decorate-capture`{.descname} *&ensp;...&ensp;*) [](#scopes.sugar.decorate-capture "Permalink to this definition"){.headerlink} {#scopes.sugar.decorate-capture}
+
+:   
+
+*sugar*{.property} (`spice-capture`{.descname} *&ensp;...&ensp;*) [](#scopes.sugar.spice-capture "Permalink to this definition"){.headerlink} {#scopes.sugar.spice-capture}
+
+:   
+

          
M doc/docs/module-FunctionChain.md +45 -29
@@ 1,10 1,12 @@ 
+<style type="text/css" rel="stylesheet">body { counter-reset: chapter 12; }</style>
+
 FunctionChain
 =============
 
 A function chain implements a compile-time observer pattern that allows
 a module to call back into dependent modules in a decoupled way.
 
-See following example::
+See following example:
 
     using import FunctionChain
 

          
@@ 32,8 34,6 @@ See following example::
 
 Running this program will output:
 
-..  code-block:: none
-
     first handler activated with argument 1
     handler activated with argument 1
     last handler activated with argument 1

          
@@ 42,33 42,49 @@ Running this program will output:
     last handler activated with argument 2
     handler activated with argument 3
 
-.. type:: FunctionChain
+*type*{.property} `FunctionChain`{.descname} [](#scopes.type.FunctionChain "Permalink to this definition"){.headerlink} {#scopes.type.FunctionChain}
+
+:   A plain type of storage type `(opaque@ _type)`.
+
+    *spice*{.property} `__call`{.descname} (*&ensp;...&ensp;*)[](#scopes.FunctionChain.spice.__call "Permalink to this definition"){.headerlink} {#scopes.FunctionChain.spice.__call}
+
+    :   
+
+    *inline*{.property} `__repr`{.descname} (*&ensp;self&ensp;*)[](#scopes.FunctionChain.inline.__repr "Permalink to this definition"){.headerlink} {#scopes.FunctionChain.inline.__repr}
 
-   A plain type of storage type `(opaque@ _type)`.
+    :   
+
+    *spice*{.property} `__typecall`{.descname} (*&ensp;...&ensp;*)[](#scopes.FunctionChain.spice.__typecall "Permalink to this definition"){.headerlink} {#scopes.FunctionChain.spice.__typecall}
+
+    :   
+
+    *inline*{.property} `append`{.descname} (*&ensp;self f&ensp;*)[](#scopes.FunctionChain.inline.append "Permalink to this definition"){.headerlink} {#scopes.FunctionChain.inline.append}
+
+    :   Append function `f` to function chain. When the function chain is called,
+        `f` will be called last. The return value of `f` will be ignored.
+
+    *inline*{.property} `clear`{.descname} (*&ensp;self&ensp;*)[](#scopes.FunctionChain.inline.clear "Permalink to this definition"){.headerlink} {#scopes.FunctionChain.inline.clear}
 
-   .. spice:: (__call ...)
-   .. inline:: (__repr self)
-   .. spice:: (__typecall ...)
-   .. inline:: (append self f)
-      
-      Append function `f` to function chain. When the function chain is called,