Merge remote-tracking branch 'upstream/master'

Author: rossberg

.gitmodules

@@ -1,3 +1,3 @@
 [submodule "document/core/util/katex"]
 	path = document/core/util/katex
-	url = https://github.com/Khan/KaTeX.git
+	url = https://github.com/KaTeX/KaTeX.git

.travis.yml

@@ -1,14 +1,27 @@
-language: c++
 language: python
 python:
-  - "2.7"
+  - "3.7"
+dist: bionic
 
-sudo: on
+addons:
+  apt:
+    sources:
+      - sourceline: 'ppa:avsm/ppa'
+      - sourceline: 'deb https://dl.yarnpkg.com/debian/ stable main'
+        key_url: 'https://dl.yarnpkg.com/debian/pubkey.gpg'
+    update: true
+    packages:
+      - opam
+      - texlive-full
+      - yarn
 
 install:
-  - ./interpreter/meta/travis/install-ocaml.sh
-  - sudo pip install sphinx
-  - sudo apt-get install texlive-full
+  - opam init --auto-setup --compiler=4.07.1
+  - eval $(opam env)
+  - opam --version
+  - ocaml --version
+  - opam install --yes ocamlbuild.0.14.0
+  - pip install Sphinx==2.4.4
   - git clone https://github.com/tabatkins/bikeshed.git
   - pip install --editable $PWD/bikeshed
   - bikeshed update

README.md

@@ -32,3 +32,7 @@ should take place in
 [the WebAssembly design repository](https://github.com/WebAssembly/design)
 first, so that this spec repository can remain focused. And please follow the
 [guidelines for contributing](Contributing.md).
+
+# citing
+
+For citing WebAssembly in LaTeX, use [this bibtex file](wasm-specs.bib).

document/Makefile

@@ -21,6 +21,9 @@ publish: all deploy
 clean: $(DIRS:%=clean-%)
 	rm -rf $(BUILDDIR)
 
+.PHONY: diff
+diff: $(DIRS:%=diff-%)
+
 
 # Directory-specific targets.
 
@@ -54,6 +57,10 @@ $(DIRS:%=clean-%): clean-%:
 	(cd $(@:clean-%=%); make BUILDDIR=$(BUILDDIR) clean)
 	rm -rf $(BUILDDIR)/$(@:clean-%=%)
 
+.PHONY: $(DIRS:%=diff-%)
+$(DIRS:%=diff-%): diff-%:
+	(cd $(@:diff-%=%); make BUILDDIR=$(BUILDDIR) diff)
+
 
 # Help.
 

document/README.md

@@ -21,3 +21,98 @@ To build everything and update [webassembly.github.io/spec](https://webassembly.
 make publish
 ```
 Please make sure to only use that once a change has approval.
+
+## Step by step guide to building the spec
+
+### Prerequisites
+
+You will need `python3.7`, and `pip`. `pip` should come with Python, if not follow [these installation instructions for `pip`](https://pip.pypa.io/en/stable/installing/), or check your system package manager for `pip3`.
+
+> Important: you will need the version of pip that works with `python3.7`.
+
+
+Use something like [`pipenv`](https://pipenv.pypa.io/) to keep your system installation of Python clean.
+
+```
+pip install pipenv
+pipenv --python 3.7
+pipenv shell
+```
+
+Install Python dependencies:
+
+```
+pip install Sphinx==2.4.4
+```
+
+### Checking out the repository
+
+Make sure this repository was cloned with `--recursive`:
+
+```
+git clone --recursive https://github.com/WebAssembly/spec
+```
+
+If you have already cloned but without `--recursive`, you can delete and re-clone, or `cd` into `spec` and run:
+
+```
+git submodule update --init --recursive
+```
+
+The rest of these instructions assume you are in the directory where is README is:
+
+```
+cd spec/document
+```
+
+### Building the multi-page HTML document
+
+You can now build the [multi-page html document](https://webassembly.github.io/spec/core/):
+
+```
+make -C core html
+```
+
+### Building the single-page HTML document
+
+To build the [single-page W3C version](https://webassembly.github.io/spec/core/bikeshed/), there are more dependencies to install. First, get [Bikeshed](https://github.com/tabatkins/bikeshed):
+
+```
+# cd back to root of git directory
+git clone https://github.com/tabatkins/bikeshed.git
+pip install --editable bikeshed
+bikeshed update
+```
+
+You will also need `npm` and `yarn` for all the LaTeX goodness. `npm` might already be available on your system, you can also use something like [`nvm`](https://github.com/nvm-sh/nvm) to prevent messing with system packages:
+
+```
+npm install -g yarn
+cd document
+make -C core bikeshed
+```
+
+### Building the PDF
+
+To build the [PDF](https://webassembly.github.io/spec/core/_download/WebAssembly.pdf), you will need `texlive-full`, install it using your system package manager:
+
+```
+apt install texlive-full
+make -C core pdf
+```
+
+### Building the JavaScript Embedding API
+
+To build the [JavaScript Embedding API](https://webassembly.github.io/spec/js-api/index.html), you will need `bikeshed` as describe in the section [Building the single-page HTML document](#building-the-single-page-html-document):
+
+```
+make -C js-api
+```
+
+### Building the Web Embedding API
+
+To build the [Web Embedding API](https://webassembly.github.io/spec/web-api/index.html), you will need `bikeshed` as describe in the section [Building the single-page HTML document](#building-the-single-page-html-document):
+
+```
+make -C web-api
+```

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) .
 
@@ -27,6 +23,9 @@ usage:
 	@echo "  html       to make standalone HTML files"
 	@echo "  pdf        to make standalone PDF file"
 	@echo "  bikeshed   to make a bikeshed wrapped single large HTML file"
+	@echo "  diff       to make a diff of the bikeshed HTML file with the latest TR"
+	@echo "  WD-tar     generate tar file for updating the Working Draft"
+	@echo "  WD-echidna publish the Working Draft tar file via Echidna"
 	@echo "  all        to make all 3"
 	@echo "  publish    to make all and push to gh-pages"
 	@echo "  help       to see more options"
@@ -90,8 +89,12 @@ bikeshed-keep:
 	  echo Downloaded Bikeshed.
 
 
+.PHONY: index
+index:
+	(cd appendix; ./gen-index-instructions.py)
+
 .PHONY: pdf
-pdf:	latexpdf
+pdf:	index latexpdf
 	mkdir -p $(BUILDDIR)/html/$(DOWNLOADDIR)
 	ln -f $(BUILDDIR)/latex/$(NAME).pdf $(BUILDDIR)/html/$(DOWNLOADDIR)/$(NAME).pdf
 
@@ -102,22 +105,16 @@ clean:
 	rm -rf $(STATICDIR)
 
 .PHONY: html
-html:
+html: index
 	$(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html
 	for file in `ls $(BUILDDIR)/html/*.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
@@ -139,18 +136,60 @@ singlehtml:
 bikeshed:
 	$(SPHINXBUILD) -b singlehtml -c util/bikeshed \
 		$(ALLSPHINXOPTS) $(BUILDDIR)/bikeshed_singlehtml
+	python util/bikeshed_fixup.py $(BUILDDIR)/bikeshed_singlehtml/index.html \
+		>$(BUILDDIR)/bikeshed_singlehtml/index_fixed.html
 	mkdir -p $(BUILDDIR)/bikeshed_mathjax/
 	bikeshed spec index.bs $(BUILDDIR)/bikeshed_mathjax/index.html
 	mkdir -p $(BUILDDIR)/html/bikeshed/
+	(cd util/katex/ && yarn && yarn build && npm install --only=prod)
 	python util/mathjax2katex.py $(BUILDDIR)/bikeshed_mathjax/index.html \
 		>$(BUILDDIR)/html/bikeshed/index.html
 	mkdir -p $(BUILDDIR)/html/bikeshed/katex/dist/
 	cp -r util/katex/dist/* $(BUILDDIR)/html/bikeshed/katex/dist/
 	patch -p0 $(BUILDDIR)/html/bikeshed/katex/dist/katex.css \
 		< util/katex_fix.patch
+	cp $(BUILDDIR)/bikeshed_singlehtml/_static/pygments.css \
+		$(BUILDDIR)/html/bikeshed/
 	@echo
 	@echo "Build finished. The HTML page is in $(BUILDDIR)/html/bikeshed/."
 
+.PHONY: WD-tar
+WD-tar: bikeshed
+	@echo "Building tar file..."
+	tar cvf \
+		$(BUILDDIR)/WD.tar \
+		--transform='s|$(BUILDDIR)/html/bikeshed/||' \
+		--transform='s|index.html|Overview.html|' \
+		$(BUILDDIR)/html/bikeshed/index.html \
+		$(BUILDDIR)/html/bikeshed/pygments.css \
+		$(BUILDDIR)/html/bikeshed/katex/dist/katex.css \
+		$(BUILDDIR)/html/bikeshed/katex/dist/fonts
+	@echo "Built $(BUILDDIR)/WD.tar."
+
+.PHONY: WD-echidna
+WD-echidna: WD-tar
+	@if [ -z $(W3C_USERNAME) ] || \
+	    [ -z $(W3C_PASSWORD) ] || \
+			[ -z $(DECISION_URL) ] ; then \
+		echo "Must provide W3C_USERNAME, W3C_PASSWORD, and DECISION_URL environment variables"; \
+		exit 1; \
+	fi
+	curl 'https://labs.w3.org/echidna/api/request' \
+		--user '$(W3C_USERNAME):$(W3C_PASSWORD)' \
+		-F "tar=@$(BUILDDIR)/WD.tar" \
+		-F "decision=$(DECISION_URL)" | tee $(BUILDDIR)/WD-echidna-id.txt
+	@echo
+	@echo "Published working draft. Check its status at https://labs.w3.org/echidna/api/status?id=`cat $(BUILDDIR)/WD-echidna-id.txt`"
+
+.PHONY: diff
+diff: bikeshed
+	@echo "Downloading the old single-file html spec..."
+	curl `grep "^TR" index.bs | cut -d' ' -f2` -o $(BUILDDIR)/html/bikeshed/old.html
+	@echo "Done."
+	@echo "Diffing new against old (go get a coffee)..."
+	perl ../util/htmldiff.pl $(BUILDDIR)/html/bikeshed/old.html $(BUILDDIR)/html/bikeshed/index.html $(BUILDDIR)/html/bikeshed/diff.html
+	@echo "Done. The diff is at $(BUILDDIR)/html/bikeshed/diff.html"
+
 .PHONY: pickle
 pickle:
 	$(SPHINXBUILD) -b pickle $(ALLSPHINXOPTS) $(BUILDDIR)/pickle
@@ -223,7 +262,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