Merge branch 'branch/2021-05-27/sphinx' into master for GitHUb pull r…

…equest 67 <#67>.

design/abq.txt

@@ -51,7 +51,7 @@ Interface
 client structures: clients must not depend on its implementation
 details.
 
-``ABQInit(Arena arena, ABQ abq, void *owner, Count elements, Size elementSize)``
+``void ABQInit(Arena arena, ABQ abq, void *owner, Count elements, Size elementSize)``
 
 Initialize the queue ``abq``. The parameter ``arena`` is the arena
 whose control pool should be used to allocate the memory for the

design/bt.txt

@@ -518,8 +518,8 @@ for the following two functions::
        return (i>>5) + (i&31);
     }
 
-``ACT_ON_RANGE(Index base, Index limit, single_action, bits_action, word_action)``
-``ACT_ON_RANGE_HIGH(Index base, Index limit, single_action, bits_action, word_action)``
+``ACT_ON_RANGE(base, limit, single_action, bits_action, word_action)``
+``ACT_ON_RANGE_HIGH(base, limit, single_action, bits_action, word_action)``
 
 _`.iteration`: Many of the following functions involve iteration over
 ranges in a Bit Table. This is performed on whole words rather than

design/buffer.txt

@@ -544,7 +544,7 @@ itself.
 The pool class's ``bufferDestroy()`` method is called and then the
 buffer structure is uninitialized and freed.
 
-``BufferCheck(Buffer buffer)``
+``Bool BufferCheck(Buffer buffer)``
 
 _`.method.check`: The check method is straightforward, the non-trivial dependencies checked are:
 
@@ -582,7 +582,7 @@ between a reserve and commit. The result is only reliable if the
 client is not currently using the buffer, since it may update the
 alloc and init pointers asynchronously.
 
-``mps_ap_t (BufferAP)(Buffer buffer)``
+``mps_ap_t BufferAP(Buffer buffer)``
 
 Returns the ``APStruct`` substructure of a buffer.
 
@@ -653,7 +653,7 @@ again for any purpose.
 Some classes of pool may cause commit to fail under rare
 circumstances.
 
-``BufferTrip(Buffer buffer, Addr p, Size size)``
+``void BufferTrip(Buffer buffer, Addr p, Size size)``
 
 _`.method.trip`: Act on a tripped buffer. The pool which owns a buffer
 may asynchronously set the buffer limit to zero in order to get

design/clock.txt

@@ -60,13 +60,13 @@ macro must assign a timestamp to ``lvalue`` with the value ``(high
 _`.if.get`: Assign an ``EventClock`` timestamp for the current time to
 ``lvalue``, which is an lvalue with type ``EventClock``.
 
-``EVENT_CLOCK_PRINT(FILE *stream, EventClock clock)``
+``EVENT_CLOCK_PRINT(stream, clock)``
 
 _`.if.print`: Write the value of ``clock`` to the standard C output
 file handle ``stream`` as 16 hexadecimal digits (with leading zeros,
 and capital letters A to F).
 
-``EVENT_CLOCK_WRITE(mps_lib_FILE *stream, EventClock clock)``
+``EVENT_CLOCK_WRITE(stream, clock)``
 
 _`.if.write`: Write the value of ``clock`` to the output stream
 ``stream`` as 16 hexadecimal digits (with leading zeros, and capital

design/doc.txt

@@ -205,6 +205,20 @@ is translated into a ``c:function`` directive::
 
     .. c:function:: void LandFinish(Land land)
 
+
+_`.fmt.function-decl`: A paragraph consisting of a macro
+declaration on a single line formatted as code, for example::
+
+    ``RING_FOR(node, ring, next)``
+
+is translated into a ``c:macro`` directive::
+
+    .. c:macro:: RING_FOR(node, ring, next)
+
+Macros are identified by having names consisting of capital letters,
+numbers, and underscore, or appearing in the list of exceptions given
+by the ``MACROS`` global in designs.py.
+
 _`.fmt.type-def`: A paragraph consisting of a type definition on a
 single line formatted as code, for example::
 

design/fix.txt

@@ -32,7 +32,7 @@ object referred to by the ref (the one that it is supposed to be
 fixing) has not previously been marked (that is, this is the first
 reference to this object that has been fixed), and that the object was
 white (that is, in condemned space), it should (but need not) set the
-field to ``FALSE`` in the passed ``ScanState````wasMarked`` .
+``wasMarked`` field to ``FALSE`` in the passed ``ScanState``.
 
 _`.was-marked.otherwise`: Otherwise, the fix method must
 leave the ``wasMarked`` field unchanged.

design/interface-c.txt

@@ -213,7 +213,7 @@ from `mail.richard.1996-08-07.09-49`_.
 ``COMPATLVALUE(lvalue1, lvalue2)``
 
 _`.check.types.compat.lvalue`: This macro checks the assignment
-compatibility of two lvalues. It uses ``sizeof()`` to ensure that the
+compatibility of two lvalues. It uses ``sizeof`` to ensure that the
 assignments have no effect. ::
 
     #define COMPATLVALUE(lv1, lv2) \
@@ -224,7 +224,7 @@ assignments have no effect. ::
 _`.check.types.compat.type`: This macro checks that two types are
 assignment-compatible and equal in size. The hack here is that it
 generates an lvalue for each type by casting zero to a pointer to the
-type. The use of ``sizeof()`` avoids the undefined behaviour that
+type. The use of ``sizeof`` avoids the undefined behaviour that
 would otherwise result from dereferencing a null pointer. ::
 
     #define COMPATTYPE(t1, t2) \

design/locus.txt

@@ -401,7 +401,7 @@ specification to place the new allocation immediately above/below a
 given tract; if that is not possible, it returns ``ResFAIL`` (this
 will make it useful for reallocation functionality).
 
-``ArenaSetTotalLoci(Arena arena, Size nLoci, Size nZoneGroups)``
+``void ArenaSetTotalLoci(Arena arena, Size nLoci, Size nZoneGroups)``
 
 _`.function.set-total`: A function to tell the arena the expected
 number of (non-miscible client) loci, and of zone groups.

design/object-debug.txt

@@ -342,7 +342,13 @@ fenceposts around an object. The ``NULL`` method checks tails.
 _`.interface.tags.alloc`: Two functions to extend the existing
 ``mps_alloc()`` (request.???.??? proposes to remove the varargs)
 
-``void (*mps_objects_step_t)(mps_addr_t addr, size_t size, mps_fmt_t format, mps_pool_t pool, void *tag_data, void *p)``
+``typedef void (*mps_objects_step_t)(mps_addr_t addr, size_t size, mps_fmt_t format, mps_pool_t pool, void *tag_data, void *p)``
+
+_`.interface.tags.walker.type`: Type of walker function for
+``mps_pool_walk()`` and ``mps_arena_walk()``.
+
+``void mps_pool_walk(mps_arena_t arena, mps_pool_t pool, mps_objects_step_t step, void *p)``
+
 ``void mps_arena_walk(mps_arena_t arena, mps_objects_step_t step, void *p)``
 
 _`.interface.tags.walker`: Functions to walk all the allocated

design/prmc.txt

@@ -124,7 +124,7 @@ protection module can single-step the instruction which is causing the
 fault. Return ``TRUE`` if ``MutatorContextStepInstruction()`` is
 capable of single-stepping the instruction, or ``FALSE`` if not.
 
-``Bool Res MutatorContextStepInstruction(MutatorContext context)``
+``Res MutatorContextStepInstruction(MutatorContext context)``
 
 _`.if.step`: Single-step the instruction which is causing the fault.
 Update the mutator context according to the emulation or execution of

design/ring.txt

@@ -122,7 +122,7 @@ parent-children rings it returns the number of children.
 Iteration
 .........
 
-``RING_FOR(Ring node, Ring ring, Ring next)``
+``RING_FOR(node, ring, next)``
 
 _`.for`: A macro is used for iterating over the elements in a ring.
 This macro is called ``RING_FOR()``. ``RING_FOR()`` takes three arguments.
@@ -163,11 +163,11 @@ Element access
 
 _`.next`: ``RingNext()`` returns the next node in the ring.
 
-``Ring (RingPrev)(Ring ring)``
+``Ring RingPrev(Ring ring)``
 
 _`.prev`: ``RingPrev()`` returns the previous node in the ring.
 
-``RING_ELT(type, field, Ring node)``
+``RING_ELT(type, field, node)``
 
 _`.elt`: ``RING_ELT()`` is a macro that converts a pointer to a ring
 structure into a pointer to the enclosing parent structure.
@@ -182,17 +182,17 @@ result is a pointer to the enclosing structure.
 Append / Remove
 ...............
 
-``void RingAppend(Ring ring, Ring new)``
+``void RingAppend(ring, new)``
 
 _`.append`: ``RingAppend()`` appends a singleton ring to a ring (such
 that the newly added element will be last in the iteration sequence).
 
-``void (RingInsert)(Ring ring, Ring new)``
+``void RingInsert(Ring ring, Ring new)``
 
 _`.insert`: ``RingInsert()`` adds a singleton ring to a ring (such that
 the newly added element will be first in the iteration sequence).
 
-``void (RingRemove)(Ring old)``
+``void RingRemove(Ring old)``
 
 _`.remove`: ``RingRemove()`` removes an element from a ring. The newly
 removed element becomes a singleton ring. It is an error for the

design/stack-scan.txt

@@ -256,7 +256,7 @@ entry to the MPS (see `.sol.setjmp`_ and `.sol.stack.nest`_). Return
 _`.if.scan.begin-end`: This function must be called between
 ``STACK_CONTEXT_BEGIN()`` and ``STACK_CONTEXT_END()``.
 
-``STACK_CONTEXT_SAVE(StackContext sc)``
+``STACK_CONTEXT_SAVE(sc)``
 
 _`.if.save`: Store the mutator context in the structure ``sc``.
 
@@ -269,7 +269,7 @@ violation of design.mps.config.no-spaghetti_ in ss.h.
 
 .. _design.mps.config.no-spaghetti: config#.no-spaghetti
 
-``STACK_CONTEXT_BEGIN(Arena arena)``
+``STACK_CONTEXT_BEGIN(arena)``
 
 _`.if.begin`: Start an MPS operation that may need to know the mutator
 context (see `.sol.entry-points`_). This macro must be used like this::
@@ -289,7 +289,7 @@ This macro stores the mutator context in a ``StackContext`` structure
 allocated on the stack, and sets ``arena->stackWarm`` to the hot end
 of the current frame (using `.sol.stack.hot`_).
 
-``STACK_CONTEXT_END(Arena arena)``
+``STACK_CONTEXT_END(arena)``
 
 _`.if.end`: Finish the MPS operation that was started by
 ``STACK_CONTEXT_BEGIN()``.

manual/Makefile

@@ -3,7 +3,7 @@
 
 # You can set these variables from the command line.
 SPHINXOPTS    =
-SPHINXBUILD   = sphinx-build
+SPHINXBUILD   = tool/bin/sphinx-build
 PAPER         =
 BUILDDIR      = .
 
@@ -43,38 +43,38 @@ clean:
 	-rm -rf $(BUILDDIR)/{changes,devhelp,dirhtml,doctest,doctrees,epub,html,htmlhelp,json,latex,linkcheck,locale,man,pickle,qthelp,singlehtml,texinfo,text}
 	-find $(BUILDDIR)/source/design -name '*.rst' ! -name 'index.rst' ! -name 'old.rst' -exec rm -f '{}' ';'
 
-html:
+html: $(SPHINXBUILD)
 	$(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html
 	@echo
 	@echo "Build finished. The HTML pages are in $(BUILDDIR)/html."
 
-dirhtml:
+dirhtml: $(SPHINXBUILD)
 	$(SPHINXBUILD) -b dirhtml $(ALLSPHINXOPTS) $(BUILDDIR)/dirhtml
 	@echo
 	@echo "Build finished. The HTML pages are in $(BUILDDIR)/dirhtml."
 
-singlehtml:
+singlehtml: $(SPHINXBUILD)
 	$(SPHINXBUILD) -b singlehtml $(ALLSPHINXOPTS) $(BUILDDIR)/singlehtml
 	@echo
 	@echo "Build finished. The HTML page is in $(BUILDDIR)/singlehtml."
 
-pickle:
+pickle: $(SPHINXBUILD)
 	$(SPHINXBUILD) -b pickle $(ALLSPHINXOPTS) $(BUILDDIR)/pickle
 	@echo
 	@echo "Build finished; now you can process the pickle files."
 
-json:
+json: $(SPHINXBUILD)
 	$(SPHINXBUILD) -b json $(ALLSPHINXOPTS) $(BUILDDIR)/json
 	@echo
 	@echo "Build finished; now you can process the JSON files."
 
-htmlhelp:
+htmlhelp: $(SPHINXBUILD)
 	$(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:
+qthelp: $(SPHINXBUILD)
 	$(SPHINXBUILD) -b qthelp $(ALLSPHINXOPTS) $(BUILDDIR)/qthelp
 	@echo
 	@echo "Build finished; now you can run "qcollectiongenerator" with the" \
@@ -83,7 +83,7 @@ qthelp:
 	@echo "To view the help file:"
 	@echo "# assistant -collectionFile $(BUILDDIR)/qthelp/MemoryPoolSystem.qhc"
 
-devhelp:
+devhelp: $(SPHINXBUILD)
 	$(SPHINXBUILD) -b devhelp $(ALLSPHINXOPTS) $(BUILDDIR)/devhelp
 	@echo
 	@echo "Build finished."
@@ -92,74 +92,74 @@ devhelp:
 	@echo "# ln -s $(BUILDDIR)/devhelp $$HOME/.local/share/devhelp/MemoryPoolSystem"
 	@echo "# devhelp"
 
-epub:
+epub: $(SPHINXBUILD)
 	$(SPHINXBUILD) -b epub $(ALLSPHINXOPTS) $(BUILDDIR)/epub
 	@echo
 	@echo "Build finished. The epub file is in $(BUILDDIR)/epub."
 
-latex:
+latex: $(SPHINXBUILD)
 	$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
 	@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:
+latexpdf: $(SPHINXBUILD)
 	$(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."
 
-text:
+text: $(SPHINXBUILD)
 	$(SPHINXBUILD) -b text $(ALLSPHINXOPTS) $(BUILDDIR)/text
 	@echo
 	@echo "Build finished. The text files are in $(BUILDDIR)/text."
 
-man:
+man: $(SPHINXBUILD)
 	$(SPHINXBUILD) -b man $(ALLSPHINXOPTS) $(BUILDDIR)/man
 	@echo
 	@echo "Build finished. The manual pages are in $(BUILDDIR)/man."
 
-texinfo:
+texinfo: $(SPHINXBUILD)
 	$(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:
+info: $(SPHINXBUILD)
 	$(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:
+gettext: $(SPHINXBUILD)
 	$(SPHINXBUILD) -b gettext $(I18NSPHINXOPTS) $(BUILDDIR)/locale
 	@echo
 	@echo "Build finished. The message catalogs are in $(BUILDDIR)/locale."
 
-changes:
+changes: $(SPHINXBUILD)
 	$(SPHINXBUILD) -b changes $(ALLSPHINXOPTS) $(BUILDDIR)/changes
 	@echo
 	@echo "The overview file is in $(BUILDDIR)/changes."
 
-linkcheck:
+linkcheck: $(SPHINXBUILD)
 	$(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:
+doctest: $(SPHINXBUILD)
 	$(SPHINXBUILD) -b doctest $(ALLSPHINXOPTS) $(BUILDDIR)/doctest
 	@echo "Testing of doctests in the sources finished, look at the " \
 	      "results in $(BUILDDIR)/doctest/output.txt."
 
 tools: tool/bin/sphinx-build
 
 tool/bin/sphinx-build: tool/bin/pip
-	tool/bin/pip install sphinx
+	tool/bin/pip install 'sphinx < 5' # Layout breaks in Sphinx >= 5.  See <https://github.com/Ravenbrook/mps/issues/121>.
 	@echo "You can now use \`make SPHINXBUILD=tool/bin/sphinx-build html' etc."
 	@echo "Or add tool/bin to your path."
 
 tool/bin/pip:
-	virtualenv tool
+	python3 -mvenv tool