Merge remote-tracking branch 'upstream/master'

Author: binji

.travis.yml

@@ -1,19 +1,21 @@
-language: c++
 language: python
 python:
-  - "2.7"
+  - "3.7"
+dist: bionic
 
-sudo: on
-
-before_install:
-  - curl -sS https://dl.yarnpkg.com/debian/pubkey.gpg | sudo apt-key add -
-  - echo "deb https://dl.yarnpkg.com/debian/ stable main" | sudo tee /etc/apt/sources.list.d/yarn.list
-  - sudo apt-get update -qq
+addons:
+  apt:
+    sources:
+      - sourceline: 'deb https://dl.yarnpkg.com/debian/ stable main'
+        key_url: 'https://dl.yarnpkg.com/debian/pubkey.gpg'
+    packages:
+      - ocaml
+      - ocamlbuild
+      - texlive-full
+      - yarn
 
 install:
-  - ./interpreter/meta/travis/install-ocaml.sh
-  - sudo pip install sphinx==1.7.9
-  - sudo apt-get install texlive-full yarn
+  - pip install Sphinx==2.4.4
   - git clone https://github.com/tabatkins/bikeshed.git
   - pip install --editable $PWD/bikeshed
   - bikeshed update

document/core/Makefile

@@ -10,14 +10,10 @@ STATICDIR     = _static
 DOWNLOADDIR   = _download
 NAME          = WebAssembly
 
-# Hack until we have moved to more recent Sphinx.
-OLDMATHJAX    = https://cdn.mathjax.org/mathjax/latest/MathJax.js
-NEWMATHJAX    = https://cdnjs.cloudflare.com/ajax/libs/mathjax/2.7.1/MathJax.js
-
 # Internal variables.
 PAPEROPT_a4     = -D latex_paper_size=a4
 PAPEROPT_letter = -D latex_paper_size=letter
-ALLSPHINXOPTS   = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) .
+ALLSPHINXOPTS   = -d $(BUILDDIR)/doctrees $(SPHINXOPTS) .
 # the i18n builder cannot share the environment and doctrees with the others
 I18NSPHINXOPTS  = $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) .
 
@@ -111,16 +107,10 @@ html:
 	do \
 	  sed s:BASEDIR:.:g <$$file >$$file.out; \
 	  mv -f $$file.out $$file; \
-	  sed s~$(OLDMATHJAX)~$(NEWMATHJAX)~g <$$file >$$file.out; \
-	  mv -f $$file.out $$file; \
 	done
 	for file in `ls $(BUILDDIR)/html/*/*.html`; \
 	do \
 	  sed s:BASEDIR:..:g <$$file >$$file.out; \
-	  sed 's;<body; <script type="text/javascript">MathJax.Hub.Config({TeX: {MAXBUFFER: 30*1024}})</script><body;' \
-	    <$$file.out >$$file; \
-	  rm -f $$file.out; \
-	  sed s~$(OLDMATHJAX)~$(NEWMATHJAX)~g <$$file >$$file.out; \
 	  mv -f $$file.out $$file; \
 	done
 	@echo
@@ -268,7 +258,7 @@ latex:
 latexpdf:
 	$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
 	@echo "Running LaTeX files through pdflatex..."
-	$(MAKE) -C $(BUILDDIR)/latex all-pdf
+	$(MAKE) -C $(BUILDDIR)/latex LATEXMKOPTS=" </dev/null" all-pdf >$(BUILDDIR)/latex/LOG 2>&1 || cat $(BUILDDIR)/latex/LOG
 	@echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex."
 
 .PHONY: latexpdfja

document/core/appendix/properties.rst

@@ -218,15 +218,15 @@ Module instances are classified by *module contexts*, which are regular :ref:`co
 
   * Or the :ref:`external value <syntax-externval>` :math:`\EVFUNC~\X{fa}` must be :ref:`valid <valid-externval-func>` with some :ref:`external type <syntax-externtype>` :math:`\ETFUNC~\X{ft}`.
 
-* The :ref:`limits <syntax-limits>` :math:`\{\LMIN~n, \LMAX~m^?\}` must be :ref:`valid <valid-limits>`.
+* The :ref:`limits <syntax-limits>` :math:`\{\LMIN~n, \LMAX~m^?\}` must be :ref:`valid <valid-limits>` within range :math:`2^{32}`.
 
 * Then the table instance is valid with :ref:`table type <syntax-tabletype>` :math:`\{\LMIN~n, \LMAX~m^?\}~\FUNCREF`.
 
 .. math::
    \frac{
      ((S \vdash \EVFUNC~\X{fa} : \ETFUNC~\functype)^?)^n
      \qquad
-     \vdashlimits \{\LMIN~n, \LMAX~m^?\} \ok
+     \vdashlimits \{\LMIN~n, \LMAX~m^?\} : 2^{32}
    }{
      S \vdashtableinst \{ \TIELEM~(\X{fa}^?)^n, \TIMAX~m^? \} : \{\LMIN~n, \LMAX~m^?\}~\FUNCREF
    }
@@ -238,13 +238,13 @@ Module instances are classified by *module contexts*, which are regular :ref:`co
 :ref:`Memory Instances <syntax-meminst>` :math:`\{ \MIDATA~b^n, \MIMAX~m^? \}`
 ..............................................................................
 
-* The :ref:`limits <syntax-limits>` :math:`\{\LMIN~n, \LMAX~m^?\}` must be :ref:`valid <valid-limits>`.
+* The :ref:`limits <syntax-limits>` :math:`\{\LMIN~n, \LMAX~m^?\}` must be :ref:`valid <valid-limits>` within range :math:`2^{16}`.
 
 * Then the memory instance is valid with :ref:`memory type <syntax-memtype>` :math:`\{\LMIN~n, \LMAX~m^?\}`.
 
 .. math::
    \frac{
-     \vdashlimits \{\LMIN~n, \LMAX~m^?\} \ok
+     \vdashlimits \{\LMIN~n, \LMAX~m^?\} : 2^{16}
    }{
      S \vdashmeminst \{ \MIDATA~b^n, \MIMAX~m^? \} : \{\LMIN~n, \LMAX~m^?\}
    }

document/core/binary/modules.rst

@@ -117,7 +117,7 @@ Their contents consist of a :ref:`name <syntax-name>` further identifying the cu
    \end{array}
 
 .. note::
-   If an implementation interprets the contents of a custom section, then errors in that contents, or the placement of the section, must not invalidate the module.
+   If an implementation interprets the data of a custom section, then errors in that data, or the placement of the section, must not invalidate the module.
 
 
 .. index:: ! type section, type definition

document/core/conf.py

@@ -478,3 +478,9 @@
 rst_prolog = """
 .. include:: /""" + pwd + """/util/macros.def
 """
+
+# https://www.sphinx-doc.org/en/master/usage/extensions/math.html#confval-mathjax_config
+# http://docs.mathjax.org/en/v2.7-latest/options/input-processors/TeX.html
+mathjax_config = {
+    'TeX': { 'MAXBUFFER': 30*1024 },
+}

document/core/exec/instructions.rst

@@ -591,13 +591,15 @@ Memory Instructions
 
 8. Pop the value :math:`\I32.\CONST~n` from the stack.
 
-9. Either, try :ref:`growing <grow-mem>` :math:`\X{mem}` by :math:`n` :ref:`pages <page-size>`:
+9. Let :math:`\X{err}` be the |i32| value :math:`2^{32}-1`, for which :math:`\signed_{32}(\X{err})` is :math:`-1`.
+
+10. Either, try :ref:`growing <grow-mem>` :math:`\X{mem}` by :math:`n` :ref:`pages <page-size>`:
 
    a. If it succeeds, push the value :math:`\I32.\CONST~\X{sz}` to the stack.
 
-   b. Else, push the value :math:`\I32.\CONST~(-1)` to the stack.
+   b. Else, push the value :math:`\I32.\CONST~\X{err}` to the stack.
 
-10. Or, push the value :math:`\I32.\CONST~(-1)` to the stack.
+11. Or, push the value :math:`\I32.\CONST~\X{err}` to the stack.
 
 .. math::
    ~\\[-1ex]
@@ -613,7 +615,7 @@ Memory Instructions
      \end{array}
    \\[1ex]
    \begin{array}{lcl@{\qquad}l}
-   S; F; (\I32.\CONST~n)~\MEMORYGROW &\stepto& S; F; (\I32.\CONST~{-1})
+   S; F; (\I32.\CONST~n)~\MEMORYGROW &\stepto& S; F; (\I32.\CONST~\signed_{32}^{-1}(-1))
    \end{array}
    \end{array}
 

document/core/exec/modules.rst

@@ -1,7 +1,7 @@
 Modules
 -------
 
-For modules, the execution semantics primarily defines :ref:`instantiation <exec-instantiation>`, which :ref:`allocates <alloc>` instances for a module and its contained definitions, inititializes :ref:`tables <syntax-table>` and :ref:`memories <syntax-mem>` from contained :ref:`element <syntax-elem>` and :ref:`data <syntax-data>` segments, and invokes the :ref:`start function <syntax-start>` if present. It also includes :ref:`invocation <exec-invocation>` of exported functions.
+For modules, the execution semantics primarily defines :ref:`instantiation <exec-instantiation>`, which :ref:`allocates <alloc>` instances for a module and its contained definitions, initializes :ref:`tables <syntax-table>` and :ref:`memories <syntax-mem>` from contained :ref:`element <syntax-elem>` and :ref:`data <syntax-data>` segments, and invokes the :ref:`start function <syntax-start>` if present. It also includes :ref:`invocation <exec-invocation>` of exported functions.
 
 Instantiation depends on a number of auxiliary notions for :ref:`type-checking imports <exec-import>` and :ref:`allocating <alloc>` instances.
 

document/core/exec/numerics.rst

@@ -726,7 +726,7 @@ then its sign is non-deterministic and the :ref:`payload <syntax-payload>` is co
 
 * If the payload of all NaN inputs to the operator is :ref:`canonical <canonical-nan>` (including the case that there are no NaN inputs), then the payload of the output is canonical as well.
 
-* Otherwise the payload is picked non-determinsitically among all :ref:`arithmetic NaNs <arithmetic-nan>`; that is, its most significant bit is :math:`1` and all others are unspecified.
+* Otherwise the payload is picked non-deterministically among all :ref:`arithmetic NaNs <arithmetic-nan>`; that is, its most significant bit is :math:`1` and all others are unspecified.
 
 This non-deterministic result is expressed by the following auxiliary function producing a set of allowed outputs from a set of inputs:
 

document/core/exec/runtime.rst

@@ -479,7 +479,7 @@ That way, the end of the inner instruction sequence is known when part of an out
    When |END| is reached, i.e., the inner instruction sequence has been reduced to the empty sequence -- or rather, a sequence of :math:`n` |CONST| instructions representing the resulting values -- then the |LABEL| instruction is eliminated courtesy of its own :ref:`reduction rule <exec-label>`:
 
    .. math::
-      \LABEL_n\{\instr^n\}~\val^\ast~\END \quad\stepto\quad \val^n
+      \LABEL_m\{\instr^\ast\}~\val^n~\END \quad\stepto\quad \val^n
 
    This can be interpreted as removing the label from the stack and only leaving the locally accumulated operand values.
 

document/core/text/modules.rst

@@ -422,13 +422,13 @@ The syntax for exports mirrors their :ref:`abstract syntax <syntax-export>` dire
      \text{(}~\text{export}~~\X{nm}{:}\Tname~~d{:}\Texportdesc_I~\text{)}
        &\Rightarrow& \{ \ENAME~\X{nm}, \EDESC~d \} \\
    \production{export description} & \Texportdesc_I &::=&
-     \text{(}~\text{func}~~x{:}\Bfuncidx_I~\text{)}
+     \text{(}~\text{func}~~x{:}\Tfuncidx_I~\text{)}
        &\Rightarrow& \EDFUNC~x \\ &&|&
-     \text{(}~\text{table}~~x{:}\Btableidx_I~\text{)}
+     \text{(}~\text{table}~~x{:}\Ttableidx_I~\text{)}
        &\Rightarrow& \EDTABLE~x \\ &&|&
-     \text{(}~\text{memory}~~x{:}\Bmemidx_I~\text{)}
+     \text{(}~\text{memory}~~x{:}\Tmemidx_I~\text{)}
        &\Rightarrow& \EDMEM~x \\ &&|&
-     \text{(}~\text{global}~~x{:}\Bglobalidx_I~\text{)}
+     \text{(}~\text{global}~~x{:}\Tglobalidx_I~\text{)}
        &\Rightarrow& \EDGLOBAL~x \\
    \end{array}
 

document/core/text/values.rst

@@ -96,13 +96,17 @@ Floating-Point
      h{:}\Thexdigit~~q{:}\Thexfrac &\Rightarrow& (h+q)/16 \\ &&|&
      h{:}\Thexdigit~~\text{\_}~~~~p{:}\Thexdigit~~q{:}\Thexfrac &\Rightarrow& (h+(p+q)/16)/16 \\
    \production{decimal floating-point number} & \Tfloat &::=&
+     p{:}\Tnum
+       &\Rightarrow& p \\ &&|&
      p{:}\Tnum~\text{.}~q{:}\Tfrac
        &\Rightarrow& p+q \\ &&|&
      p{:}\Tnum~(\text{E}~|~\text{e})~{\pm}{:}\Tsign~e{:}\Tnum
        &\Rightarrow& p\cdot 10^{\pm e} \\ &&|&
      p{:}\Tnum~\text{.}~q{:}\Tfrac~(\text{E}~|~\text{e})~{\pm}{:}\Tsign~e{:}\Tnum
        &\Rightarrow& (p+q)\cdot 10^{\pm e} \\
    \production{hexadecimal floating-point number} & \Thexfloat &::=&
+     \text{0x}~p{:}\Thexnum
+       &\Rightarrow& p \\ &&|&
      \text{0x}~p{:}\Thexnum~\text{.}~q{:}\Thexfrac
        &\Rightarrow& p+q \\ &&|&
      \text{0x}~p{:}\Thexnum~(\text{P}~|~\text{p})~{\pm}{:}\Tsign~e{:}\Tnum

document/core/util/bikeshed_fixup.py

@@ -1,4 +1,4 @@
-#! /usr/bin/env python
+#! /usr/bin/env python3
 # -*- coding: latin-1 -*-
 
 import os

document/core/util/mathdef.py

@@ -1,12 +1,9 @@
 from sphinx.ext.mathbase import math
-from sphinx.ext.mathbase import displaymath
-from sphinx.ext.mathbase import math_role
 from sphinx.ext.mathbase import MathDirective
-from sphinx.ext.mathbase import latex_visit_math
-from sphinx.ext.mathbase import latex_visit_displaymath
-from sphinx.ext.mathjax import html_visit_math
-from sphinx.ext.mathjax import html_visit_displaymath
-from sphinx.util.texescape import tex_escape_map, tex_replace_map
+from sphinx.util.texescape import tex_replace_map
+from sphinx.writers.html5 import HTML5Translator
+from sphinx.writers.latex import LaTeXTranslator
+from docutils import nodes
 from docutils.parsers.rst.directives.misc import Replace
 from six import text_type
 import re
@@ -20,16 +17,8 @@ def html_hyperlink(file, id):
   return '\\href{../%s.html#%s}' % (file, id.replace('_', '-'))
 
 def html_transform_math_xref(node):
-  node['latex'] = \
-    xref_re.sub(lambda m: html_hyperlink(m.group(1), m.group(2)), node['latex'])
-
-def ext_html_visit_math(self, node):
-  html_transform_math_xref(node)
-  html_visit_math(self, node)
-
-def ext_html_visit_displaymath(self, node):
-  html_transform_math_xref(node)
-  html_visit_displaymath(self, node)
+  new_text = xref_re.sub(lambda m: html_hyperlink(m.group(1), m.group(2)), node.astext())
+  node.children[0] = nodes.Text(new_text)
 
 # Mirrors sphinx/writers/latex
 def latex_hyperlink(file, id):
@@ -39,17 +28,8 @@ def latex_hyperlink(file, id):
   return '\\hyperref[%s:%s]' % (file, id)
 
 def latex_transform_math_xref(node):
-  node['latex'] = \
-    xref_re.sub(lambda m: latex_hyperlink(m.group(1), m.group(2)), node['latex'])
-
-def ext_latex_visit_math(self, node):
-  latex_transform_math_xref(node)
-  latex_visit_math(self, node)
-
-def ext_latex_visit_displaymath(self, node):
-  latex_transform_math_xref(node)
-  latex_visit_displaymath(self, node)
-
+  new_text = xref_re.sub(lambda m: latex_hyperlink(m.group(1), m.group(2)), node.astext())
+  node.children[0] = nodes.Text(new_text)
 
 # Expand mathdef names in math roles and directives
 
@@ -75,8 +55,7 @@ def replace_mathdefs(doc, s):
 
 def ext_math_role(role, raw, text, line, inliner, options = {}, content = []):
   text = replace_mathdefs(inliner.document, raw.split('`')[1])
-  return math_role(role, raw, text, line, inliner, options = options,
-                   content = content)
+  return [math(raw, text)], []
 
 class ExtMathDirective(MathDirective):
   def run(self):
@@ -85,7 +64,7 @@ def run(self):
       self.content[i] = replace_mathdefs(doc, s)
     for i, s in enumerate(self.arguments):
       self.arguments[i] = replace_mathdefs(doc, s)
-    return super(ExtMathDirective, self).run()
+    return super().run()
 
 class MathdefDirective(Replace):
   def run(self):
@@ -99,23 +78,45 @@ def run(self):
     doc = self.state.document
     if not hasattr(doc, 'mathdefs'):
       doc.mathdefs = {}
+    # TODO: we don't ever hit the case where len(self.content) > 1
     for i, s in enumerate(self.content):
       self.content[i] = replace_mathdefs(doc, s)
     doc.mathdefs[name] = [arity, ''.join(self.content)]
     self.content[0] = ':math:`' + self.content[0]
     self.content[-1] = self.content[-1] + '`'
-    return super(MathdefDirective, self).run()
-
+    return super().run()
+
+class WebAssemblyHTML5Translator(HTML5Translator):
+  """
+  Customize HTML5Translator.
+  Convert xref in math and math block nodes to hrefs.
+  """
+  def visit_math(self, node, math_env = ''):
+    html_transform_math_xref(node)
+    super().visit_math(node, math_env)
+
+  def visit_math_block(self, node, math_env  = ''):
+    html_transform_math_xref(node)
+    super().visit_math_block(node, math_env)
+
+class WebAssemblyLaTeXTranslator(LaTeXTranslator):
+  """
+  Customize LaTeXTranslator.
+  Convert xref in math and math block nodes to hyperrefs.
+  """
+  def visit_math(self, node):
+    latex_transform_math_xref(node)
+    super().visit_math(node)
+
+  def visit_math_block(self, node):
+    latex_transform_math_xref(node)
+    super().visit_math_block(node)
 
 # Setup
 
 def setup(app):
-  app.add_node(math,
-               html = (ext_html_visit_math, None),
-               latex = (ext_latex_visit_math, None))
-  app.add_node(displaymath,
-               html = (ext_html_visit_displaymath, None),
-               latex = (ext_latex_visit_displaymath, None))
+  app.set_translator('html', WebAssemblyHTML5Translator)
+  app.set_translator('latex', WebAssemblyLaTeXTranslator)
   app.add_role('math', ext_math_role)
-  app.add_directive('math', ExtMathDirective)
+  app.add_directive('math', ExtMathDirective, override = True)
   app.add_directive('mathdef', MathdefDirective)