Merging branch/2023-01-13/rst-check for GitHub pull request 112 <#112>

Author: UNAA008

.github/workflows/rst-check.yml

@@ -0,0 +1,23 @@
+# .github/workflows/rst-check.yml -- check syntax of reStructuredText files
+#
+# This is a GitHub CI workflow
+# <https://docs.github.com/en/actions/using-workflows/about-workflows>
+# to check the syntax of reStructuredText files.
+
+name: reStructuredText syntax check
+
+on:
+  # Run as part of CI checks on branch push and on merged pull request.
+  - push
+  - pull_request
+  - workflow_dispatch # allow manual triggering
+
+jobs:
+  check-rst:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v3
+      - name: Install docutils
+        run: sudo apt-get install -y docutils
+      - name: Check reStructuredText syntax
+        run: tool/check-rst

design/arena.txt

@@ -293,7 +293,7 @@ that the private representation can share a common prefix with
 private representation whether such an object is allocated or not,
 without requiring an extra field.
 
-_`.tract.field.base`: The seg field is a pointer to the segment
+_`.tract.field.seg`: The seg field is a pointer to the segment
 containing the tract, or ``NULL`` if the tract is not contained in any
 segment.
 

design/config.txt

@@ -169,7 +169,7 @@ predefined when compiling the module sources::
 
     CONFIG_VAR_<variety-code>
 
-_`.var`: The variety codes are as follows:
+_`.var.codes`: The variety codes are as follows:
 
 _`.var.hot`: ``HOT``
 

design/poolamc.txt

@@ -14,14 +14,21 @@ AMC pool class
    single: pool class; AMC design
 
 
-Introduction
-~~~~~~~~~~~~
+Guide Introduction
+~~~~~~~~~~~~~~~~~~
+
+.. The intro and readership tags were found to be duplicated by
+   changelist 182116 / commit e9841d23a but not referenced.  But that
+   was just a consequence of two documents being smushed together by
+   RHSK in changelist 168424 / commit b0433b3e9: a guide and a design.
+   It would be good to sort that out.  See also
+   <https://github.com/Ravenbrook/mps/issues/128>.  RB 2023-01-14
 
-_`.intro`: This document contains a guide (`.guide`_) to the MPS AMC
+_`.guide.intro`: This document contains a guide (`.guide`_) to the MPS AMC
 pool class, followed by the historical initial design
 (`.initial-design`_).
 
-_`.readership`: Any MPS developer.
+_`.guide.readership`: Any MPS developer.
 
 
 Guide

design/poolawl.txt

@@ -246,7 +246,7 @@ segment sizes are rounded up to the arena grain size.
 
 _`.fun.awlsegcreate.where`: The segment is allocated using a
 generation preference, using the generation number stored in the
-``AWLStruct`` (the ``gen`` field), see `.poolstruct.gen`_ above.
+``AWLStruct`` (the ``gen`` field), see `.poolstruct`_ above.
 
 ``Res awlSegInit(Seg seg, Pool pool, Addr base, Size size, ArgList args)``
 

design/prmc.txt

@@ -105,7 +105,7 @@ design.mps.check_.
 
 ``Res MutatorContextInitFault(MutatorContext context, ...)``
 
-_`.if.init.thread`: Initialize with the context of the mutator at the
+_`.if.init.fault`: Initialize with the context of the mutator at the
 point where it was stopped by a protection fault. The arguments are
 platform-specific and the return may be ``void`` instead of ``Res`` if
 this always succeeds.

design/protix.txt

@@ -88,12 +88,9 @@ okay), the protection is set to ``PROT_READ|PROT_WRITE|PROT_EXEC``.
 .. _design.mps.prot.if.set: prot#.if.set
 
 _`.fun.set.assume.mprotect`: We assume that the call to ``mprotect()``
-always succeeds.
-
-_`.fun.set.assume.mprotect`: This is because we should always call the
-function with valid arguments (aligned, references to mapped pages,
-and with an access that is compatible with the access of the
-underlying object).
+always succeeds.  We should always call the function with valid
+arguments (aligned, references to mapped pages, and with an access
+that is compatible with the access of the underlying object).
 
 _`.fun.sync`: ``ProtSync()`` does nothing in this implementation as
 ``ProtSet()`` sets the protection without any delay.

design/protocol.txt

@@ -569,7 +569,7 @@ following:
   A function called by ``SomeClassGet()``. All the class
   initialization code is actually in this function.
 
-_`.impl.subclass`: The subclass test `.if.subclass`_ is implemented
+_`.impl.subclass`: The subclass test `.if.is-subclass`_ is implemented
 using an array of superclasses [Cohen_1991]_ giving a fast
 constant-time test.  (RB_ tried an approach using prime factors
 [Gibbs_2004]_ but found that they overflowed in 32-bits too easily to

design/shield.txt

@@ -257,7 +257,7 @@ _`.proof.sync`: As the depth of a segment cannot be negative
   |   ⇒ all segments are synced (by `.inv.unsynced.depth`_)
 
 _`.proof.access`: If the mutator is running then all segments must be
-synced (`.inv.unsynced.suspend`_). Which means that the hardware
+synced (`.inv.unsynced.suspended`_). Which means that the hardware
 protection (protection mode) must reflect the software protection
 (shield mode). Hence all shielded memory will be hardware protected
 while the mutator is running. This ensures `.prop.mutator.access`_.

design/tests.txt

@@ -32,15 +32,15 @@ _`.run`: Run these commands::
 
 where ``<makefile>`` is the appropriate makefile for the platform (see
 `manual/build.txt`_), ``<variety>`` is the variety (see
-design.mps.config.var_) and ``<target>`` is the collection of tests
+design.mps.config.var.codes_) and ``<target>`` is the collection of tests
 (see `.target`_ below). For example::
 
     make -f lii6ll VARIETY=cool testrun
 
 If ``<variety>`` is omitted, tests are run in both the cool and hot
 varieties.
 
-.. _design.mps.config.var: config#.var
+.. _design.mps.config.var.codes: config#.var.codes
 .. _manual/build.txt: https://www.ravenbrook.com/project/mps/master/manual/build.txt