Skip to content
This repository was archived by the owner on Apr 25, 2025. It is now read-only.

Commit 902580f

Browse files
aheejinaheejin
authored
Revert "Merge 'document/' directory of 'WebAssembly/reference-types/master' (#91)" (#117)
This reverts commit 0d8fab6. This reverts #91, which squashed all upstream commits into one, which was not the recommended way in https://github.com/WebAssembly/proposals/blob/master/howto.md#syncing-with-upstream-changes.
1 parent b99c97e commit 902580f

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

86 files changed

+3348
-17410
lines changed

‎document/core/.gitignore renamed to ‎document/.gitignore

Lines changed: 0 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,2 @@
11
_build
22
_static
3-
document/*.pyc

‎document/Makefile

Lines changed: 245 additions & 51 deletions
Original file line numberDiff line numberDiff line change
@@ -1,76 +1,270 @@
1-
DIRS = core js-api web-api
2-
FILES = index.html
3-
BUILDDIR = _build
1+
# Makefile for Sphinx documentation
2+
#
43

5-
# Global targets.
4+
# You can set these variables from the command line.
5+
SPHINXOPTS =
6+
SPHINXBUILD = sphinx-build
7+
PAPER = a4
8+
BUILDDIR = _build
9+
STATICDIR = _static
10+
DOWNLOADDIR = _download
11+
GHPAGESDIR = ../docs
12+
NAME = WebAssembly
613

7-
.PHONY: all
8-
all: $(BUILDDIR) root $(DIRS)
14+
# Internal variables.
15+
PAPEROPT_a4 = -D latex_paper_size=a4
16+
PAPEROPT_letter = -D latex_paper_size=letter
17+
ALLSPHINXOPTS = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) .
18+
# the i18n builder cannot share the environment and doctrees with the others
19+
I18NSPHINXOPTS = $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) .
920

10-
$(BUILDDIR):
11-
mkdir -p $@
21+
.PHONY: usage
22+
usage:
23+
@echo "Please use \`make <target>' where <target> is one of"
24+
@echo " html to make standalone HTML files"
25+
@echo " pdf to make standalone PDF file"
26+
@echo " all to make both"
27+
@echo " publish to make all and push to gh-pages"
28+
@echo " help to see more options"
1229

13-
.PHONY: deploy
14-
deploy:
15-
GIT_DEPLOY_DIR=$(BUILDDIR) bash deploy.sh
30+
.PHONY: help
31+
help:
32+
@echo "Usage: \`make <target>' where <target> is one of"
33+
@echo " html to make standalone HTML files"
34+
@echo " pdf to make standalone PDF file"
35+
@echo " all to make both"
36+
@echo " publish to make all and push to gh-pages"
37+
@echo " dirhtml to make HTML files named index.html in directories"
38+
@echo " singlehtml to make a single large HTML file"
39+
@echo " pickle to make pickle files"
40+
@echo " json to make JSON files"
41+
@echo " htmlhelp to make HTML files and a HTML help project"
42+
@echo " qthelp to make HTML files and a qthelp project"
43+
@echo " applehelp to make an Apple Help Book"
44+
@echo " devhelp to make HTML files and a Devhelp project"
45+
@echo " epub to make an epub"
46+
@echo " epub3 to make an epub3"
47+
@echo " latex to make LaTeX files, you can set PAPER=a4 or PAPER=letter"
48+
@echo " latexpdf to make LaTeX files and run them through pdflatex"
49+
@echo " latexpdfja to make LaTeX files and run them through platex/dvipdfmx"
50+
@echo " text to make text files"
51+
@echo " man to make manual pages"
52+
@echo " texinfo to make Texinfo files"
53+
@echo " info to make Texinfo files and run them through makeinfo"
54+
@echo " gettext to make PO message catalogs"
55+
@echo " changes to make an overview of all changed/added/deprecated items"
56+
@echo " xml to make Docutils-native XML files"
57+
@echo " pseudoxml to make pseudoxml-XML files for display purposes"
58+
@echo " linkcheck to check all external links for integrity"
59+
@echo " doctest to run all doctests embedded in the documentation (if enabled)"
60+
@echo " coverage to run coverage check of the documentation (if enabled)"
61+
@echo " dummy to check syntax errors of document sources"
1662

1763
.PHONY: publish
1864
publish: all deploy
1965

66+
.PHONY: deploy
67+
deploy:
68+
GIT_DEPLOY_DIR=$(BUILDDIR)/html sh deploy.sh
69+
70+
.PHONY: all
71+
all: pdf html
72+
73+
.PHONY: pdf
74+
pdf: latexpdf
75+
mkdir -p $(BUILDDIR)/html/$(DOWNLOADDIR)
76+
ln -f $(BUILDDIR)/latex/$(NAME).pdf $(BUILDDIR)/html/$(DOWNLOADDIR)/$(NAME).pdf
77+
78+
2079
.PHONY: clean
21-
clean: $(DIRS:%=clean-%)
80+
clean:
2281
rm -rf $(BUILDDIR)
82+
rm -rf $(STATICDIR)
2383

24-
.PHONY: diff
25-
diff: $(DIRS:%=diff-%)
84+
.PHONY: html
85+
html:
86+
$(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html
87+
for file in `ls $(BUILDDIR)/html/*.html`; \
88+
do \
89+
sed s:BASEDIR:.:g <$$file >$$file.out; \
90+
mv -f $$file.out $$file; \
91+
done
92+
for file in `ls $(BUILDDIR)/html/*/*.html`; \
93+
do \
94+
sed s:BASEDIR:..:g <$$file >$$file.out; \
95+
sed 's;<body;<script type="text/javascript">MathJax.Hub.Config({TeX: {MAXBUFFER: 10*1024}})</script><body;' \
96+
<$$file.out >$$file; \
97+
rm -f $$file.out; \
98+
done
99+
@echo
100+
@echo "Build finished. The HTML pages are in `pwd`/$(BUILDDIR)/html."
26101

102+
.PHONY: dirhtml
103+
dirhtml:
104+
$(SPHINXBUILD) -b dirhtml $(ALLSPHINXOPTS) $(BUILDDIR)/dirhtml
105+
@echo
106+
@echo "Build finished. The HTML pages are in $(BUILDDIR)/dirhtml."
27107

28-
# Directory-specific targets.
108+
.PHONY: singlehtml
109+
singlehtml:
110+
$(SPHINXBUILD) -b singlehtml $(ALLSPHINXOPTS) $(BUILDDIR)/singlehtml
111+
@echo
112+
@echo "Build finished. The HTML page is in $(BUILDDIR)/singlehtml."
29113

30-
.PHONY: root
31-
root: $(BUILDDIR)
32-
touch $(BUILDDIR)/.nojekyll
33-
cp -f $(FILES) $(BUILDDIR)/
114+
.PHONY: pickle
115+
pickle:
116+
$(SPHINXBUILD) -b pickle $(ALLSPHINXOPTS) $(BUILDDIR)/pickle
117+
@echo
118+
@echo "Build finished; now you can process the pickle files."
34119

35-
.PHONY: $(DIRS)
36-
$(DIRS): %: $(BUILDDIR) $(DIRS:%=build-%) $(DIRS:%=dir-%)
120+
.PHONY: json
121+
json:
122+
$(SPHINXBUILD) -b json $(ALLSPHINXOPTS) $(BUILDDIR)/json
123+
@echo
124+
@echo "Build finished; now you can process the JSON files."
37125

38-
.PHONY: $(DIRS:%=build-%)
39-
$(DIRS:%=build-%): build-%:
40-
(cd $(@:build-%=%); make BUILDDIR=$(BUILDDIR) all)
126+
.PHONY: htmlhelp
127+
htmlhelp:
128+
$(SPHINXBUILD) -b htmlhelp $(ALLSPHINXOPTS) $(BUILDDIR)/htmlhelp
129+
@echo
130+
@echo "Build finished; now you can run HTML Help Workshop with the" \
131+
".hhp project file in $(BUILDDIR)/htmlhelp."
41132

42-
.PHONY: $(DIRS:%=dir-%)
43-
$(DIRS:%=dir-%): dir-%:
44-
mkdir -p $(BUILDDIR)/$(@:dir-%=%)
45-
rm -rf $(BUILDDIR)/$(@:dir-%=%)/*
46-
cp -R $(@:dir-%=%)/$(BUILDDIR)/html/* $(BUILDDIR)/$(@:dir-%=%)/
133+
.PHONY: qthelp
134+
qthelp:
135+
$(SPHINXBUILD) -b qthelp $(ALLSPHINXOPTS) $(BUILDDIR)/qthelp
136+
@echo
137+
@echo "Build finished; now you can run "qcollectiongenerator" with the" \
138+
".qhcp project file in $(BUILDDIR)/qthelp, like this:"
139+
@echo "# qcollectiongenerator $(BUILDDIR)/qthelp/WebAssembly.qhcp"
140+
@echo "To view the help file:"
141+
@echo "# assistant -collectionFile $(BUILDDIR)/qthelp/WebAssembly.qhc"
47142

48-
.PHONY: $(DIRS:%=deploy-%)
49-
$(DIRS:%=deploy-%): deploy-%:
50-
GIT_DEPLOY_DIR=$(BUILDDIR) GIT_DEPLOY_SUBDIR=$(@:deploy-%=%) bash deploy.sh
143+
.PHONY: applehelp
144+
applehelp:
145+
$(SPHINXBUILD) -b applehelp $(ALLSPHINXOPTS) $(BUILDDIR)/applehelp
146+
@echo
147+
@echo "Build finished. The help book is in $(BUILDDIR)/applehelp."
148+
@echo "N.B. You won't be able to view it unless you put it in" \
149+
"~/Library/Documentation/Help or install it in your application" \
150+
"bundle."
51151

52-
.PHONY: $(DIRS:%=publish-%)
53-
$(DIRS:%=publish-%): publish-%: % deploy-%
152+
.PHONY: devhelp
153+
devhelp:
154+
$(SPHINXBUILD) -b devhelp $(ALLSPHINXOPTS) $(BUILDDIR)/devhelp
155+
@echo
156+
@echo "Build finished."
157+
@echo "To view the help file:"
158+
@echo "# mkdir -p $$HOME/.local/share/devhelp/WebAssembly"
159+
@echo "# ln -s $(BUILDDIR)/devhelp $$HOME/.local/share/devhelp/WebAssembly"
160+
@echo "# devhelp"
54161

55-
.PHONY: $(DIRS:%=clean-%)
56-
$(DIRS:%=clean-%): clean-%:
57-
(cd $(@:clean-%=%); make BUILDDIR=$(BUILDDIR) clean)
58-
rm -rf $(BUILDDIR)/$(@:clean-%=%)
162+
.PHONY: epub
163+
epub:
164+
$(SPHINXBUILD) -b epub $(ALLSPHINXOPTS) $(BUILDDIR)/epub
165+
@echo
166+
@echo "Build finished. The epub file is in $(BUILDDIR)/epub."
59167

60-
.PHONY: $(DIRS:%=diff-%)
61-
$(DIRS:%=diff-%): diff-%:
62-
(cd $(@:diff-%=%); make BUILDDIR=$(BUILDDIR) diff)
168+
.PHONY: epub3
169+
epub3:
170+
$(SPHINXBUILD) -b epub3 $(ALLSPHINXOPTS) $(BUILDDIR)/epub3
171+
@echo
172+
@echo "Build finished. The epub3 file is in $(BUILDDIR)/epub3."
63173

174+
.PHONY: latex
175+
latex:
176+
$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
177+
@echo
178+
@echo "Build finished; the LaTeX files are in $(BUILDDIR)/latex."
179+
@echo "Run \`make' in that directory to run these through (pdf)latex" \
180+
"(use \`make latexpdf' here to do that automatically)."
64181

65-
# Help.
182+
.PHONY: latexpdf
183+
latexpdf:
184+
$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
185+
@echo "Running LaTeX files through pdflatex..."
186+
$(MAKE) -C $(BUILDDIR)/latex all-pdf
187+
@echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex."
66188

67-
.PHONY: help
68-
help:
69-
@echo "Please use \`make <target>' where <target> is one of"
70-
@echo " all to build all documents"
71-
@echo " publish to make all and push to gh-pages"
72-
@echo " <dir> to build a specific subdirectory"
73-
@echo " publish-<dir> to build and push a specific subdirectory"
189+
.PHONY: latexpdfja
190+
latexpdfja:
191+
$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
192+
@echo "Running LaTeX files through platex and dvipdfmx..."
193+
$(MAKE) -C $(BUILDDIR)/latex all-pdf-ja
194+
@echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex."
74195

75-
.PHONY: usage
76-
usage: help
196+
.PHONY: text
197+
text:
198+
$(SPHINXBUILD) -b text $(ALLSPHINXOPTS) $(BUILDDIR)/text
199+
@echo
200+
@echo "Build finished. The text files are in $(BUILDDIR)/text."
201+
202+
.PHONY: man
203+
man:
204+
$(SPHINXBUILD) -b man $(ALLSPHINXOPTS) $(BUILDDIR)/man
205+
@echo
206+
@echo "Build finished. The manual pages are in $(BUILDDIR)/man."
207+
208+
.PHONY: texinfo
209+
texinfo:
210+
$(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo
211+
@echo
212+
@echo "Build finished. The Texinfo files are in $(BUILDDIR)/texinfo."
213+
@echo "Run \`make' in that directory to run these through makeinfo" \
214+
"(use \`make info' here to do that automatically)."
215+
216+
.PHONY: info
217+
info:
218+
$(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo
219+
@echo "Running Texinfo files through makeinfo..."
220+
make -C $(BUILDDIR)/texinfo info
221+
@echo "makeinfo finished; the Info files are in $(BUILDDIR)/texinfo."
222+
223+
.PHONY: gettext
224+
gettext:
225+
$(SPHINXBUILD) -b gettext $(I18NSPHINXOPTS) $(BUILDDIR)/locale
226+
@echo
227+
@echo "Build finished. The message catalogs are in $(BUILDDIR)/locale."
228+
229+
.PHONY: changes
230+
changes:
231+
$(SPHINXBUILD) -b changes $(ALLSPHINXOPTS) $(BUILDDIR)/changes
232+
@echo
233+
@echo "The overview file is in $(BUILDDIR)/changes."
234+
235+
.PHONY: linkcheck
236+
linkcheck:
237+
$(SPHINXBUILD) -b linkcheck $(ALLSPHINXOPTS) $(BUILDDIR)/linkcheck
238+
@echo
239+
@echo "Link check complete; look for any errors in the above output " \
240+
"or in $(BUILDDIR)/linkcheck/output.txt."
241+
242+
.PHONY: doctest
243+
doctest:
244+
$(SPHINXBUILD) -b doctest $(ALLSPHINXOPTS) $(BUILDDIR)/doctest
245+
@echo "Testing of doctests in the sources finished, look at the " \
246+
"results in $(BUILDDIR)/doctest/output.txt."
247+
248+
.PHONY: coverage
249+
coverage:
250+
$(SPHINXBUILD) -b coverage $(ALLSPHINXOPTS) $(BUILDDIR)/coverage
251+
@echo "Testing of coverage in the sources finished, look at the " \
252+
"results in $(BUILDDIR)/coverage/python.txt."
253+
254+
.PHONY: xml
255+
xml:
256+
$(SPHINXBUILD) -b xml $(ALLSPHINXOPTS) $(BUILDDIR)/xml
257+
@echo
258+
@echo "Build finished. The XML files are in $(BUILDDIR)/xml."
259+
260+
.PHONY: pseudoxml
261+
pseudoxml:
262+
$(SPHINXBUILD) -b pseudoxml $(ALLSPHINXOPTS) $(BUILDDIR)/pseudoxml
263+
@echo
264+
@echo "Build finished. The pseudo-XML files are in $(BUILDDIR)/pseudoxml."
265+
266+
.PHONY: dummy
267+
dummy:
268+
$(SPHINXBUILD) -b dummy $(ALLSPHINXOPTS) $(BUILDDIR)/dummy
269+
@echo
270+
@echo "Build finished. Dummy builder generates no files."

‎document/README.md

Lines changed: 11 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -1,23 +1,20 @@
1-
# WebAssembly Specifications
1+
# WebAssembly Specification
22

3-
This directory contains the source code for the WebAssembly spec documents, as served from the [webassembly.github.io/spec](https://webassembly.github.io/spec) pages.
4-
It uses [Sphinx](http://www.sphinx-doc.org/) and [Bikeshed](https://github.com/tabatkins/bikeshed).
3+
This is (meant to become) the official WebAssembly "language" specification.
54

6-
To install Sphinx:
5+
It uses [Sphinx](http://www.sphinx-doc.org/). To install that:
76
```
87
pip install sphinx
98
```
10-
11-
To install Bikeshed, see the instructions [here](https://tabatkins.github.io/bikeshed/#installing).
12-
13-
14-
To build everything locally (result appears in `_build/`):
9+
To make HTML (result in `_build/html`):
1510
```
16-
make all
11+
make html
1712
```
18-
19-
To build everything and update [webassembly.github.io/spec](https://webassembly.github.io/spec) with it:
13+
To make PDF (result in `_build/latex`, requires LaTeX):
14+
```
15+
make pdf
2016
```
21-
make publish
17+
To make all:
18+
```
19+
make all
2220
```
23-
Please make sure to only use that once a change has approval.

‎document/appendix-algorithm/index.rst

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,6 @@
1+
Appendix: Validation Algorithm
2+
------------------------------
3+
4+
.. todo::
5+
6+
Describe algorithm, state correctness properties (soundness, completeness)

‎document/appendix-names/index.rst

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,6 @@
1+
Appendix: Name Section
2+
----------------------
3+
4+
.. todo::
5+
6+
Describe

‎document/appendix-properties/index.rst

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,6 @@
1+
Appendix: Formal Properties
2+
---------------------------
3+
4+
.. todo::
5+
6+
Describe and sketch proof (progress, preservation, uniqueness)

‎document/appendix-textual/index.rst

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,8 @@
1+
.. text-format:
2+
3+
Appendix: Text Format
4+
---------------------
5+
6+
.. todo::
7+
8+
Describe

0 commit comments

Comments
 (0)