Merge remote-tracking branch 'upstream/master'

Author: rossberg

.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.3.0
   - 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

document/core/binary/modules.rst

@@ -124,7 +124,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

@@ -1146,13 +1146,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]
@@ -1168,7 +1170,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/runtime.rst

@@ -556,7 +556,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

@@ -440,13 +440,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}
 
@@ -493,8 +493,6 @@ Element Segments
 
 Element segments allow for an optional :ref:`table index <text-tableidx>` to identify the table to initialize.
 
-.. todo:: TODO: multi-instr elemexpr
-
 .. math::
    \begin{array}{llclll}
    \production{element segment} & \Telem_I &::=&

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)

document/core/util/mathdefbs.py

@@ -4,16 +4,12 @@
 # mathdef.py controlled by buildername.
 
 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.writers.html5 import HTML5Translator
+from docutils import nodes
 from docutils.parsers.rst.directives.misc import Replace
-from six import text_type
 import re
 
 
@@ -25,36 +21,8 @@ def html_hyperlink(file, id):
   return '\\href{#%s}' % (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)
-
-# Mirrors sphinx/writers/latex
-def latex_hyperlink(file, id):
-  id = text_type(id).translate(tex_replace_map).\
-    encode('ascii', 'backslashreplace').decode('ascii').\
-    replace('_', '-').replace('\\', '_')
-  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: html_hyperlink(m.group(1), m.group(2)), node.astext())
+  node.children[0] = nodes.Text(new_text)
 
 # Expand mathdef names in math roles and directives
 
@@ -80,8 +48,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):
@@ -111,16 +78,23 @@ def run(self):
     self.content[-1] = self.content[-1] + '`'
     return super(MathdefDirective, self).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)
 
 # 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('singlehtml', WebAssemblyHTML5Translator)
   app.add_role('math', ext_math_role)
-  app.add_directive('math', ExtMathDirective)
+  app.add_directive('math', ExtMathDirective, override = True)
   app.add_directive('mathdef', MathdefDirective)