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

.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
 
 

procedure/release-build.rst

@@ -280,7 +280,7 @@ B. Document History
 .. _NB: mailto:[email protected]
 .. _RHSK: mailto:[email protected]
 .. _GDR: mailto:[email protected]
-.. _PNJ  mailto:[email protected]
+.. _PNJ: mailto:[email protected]
 
 C. Copyright and License
 ------------------------

tool/check-rst

@@ -0,0 +1,77 @@
+#!/bin/sh
+# tool/check-rst -- check syntax of reStructuredText in the MPS source tree
+# Richard Brooksby, Ravenbrook Limited, 2023-01-13
+#
+# Copyright (c) 2023 Ravenbrook Limited. See end of file for license.
+#
+# This script finds reStructuredText files in the MPS tree and runs
+# them through docutils to check for syntax errors.
+#
+# It can be invoked from the command line of from Continuous
+# Integration scripts.  See .github/workflows/rst-check.yml
+#
+# This script excludes manual/source because the reStructuredText
+# there is in an extended Sphinx format that can't be checked by the
+# basic docutils.  It can be checked by building the manual.  See
+# manual/Makefile.
+
+{
+    find . -path ./manual/source -prune -o \
+	 -path ./manual/tool -prune -o \
+	 -type f -name '*.rst' -print
+    find . -type f -name '*.txt' -print |
+	while read -r f; do
+	    if head -1 -- "$f" | grep -F -q -e '-*- rst -*-'; then
+		echo "$f"
+	    fi
+	done
+} | {
+    code=0
+    while read -r f; do
+	if ! rst2html --report=2 --exit-status=2 "$f" > /dev/null; then
+	    code=1
+	fi
+    done
+    exit "$code"
+}
+
+# A. REFERENCES
+#
+# [None]
+#
+#
+# B. DOCUMENT HISTORY
+#
+# 2023-01-13 RB Created.
+#
+#
+# C. COPYRIGHT AND LICENSE
+#
+# Copyright (C) 2023 Ravenbrook Limited <https://www.ravenbrook.com/>.
+#
+# Redistribution and use in source and binary forms, with or without
+# modification, are permitted provided that the following conditions are
+# met:
+#
+# 1. Redistributions of source code must retain the above copyright
+#    notice, this list of conditions and the following disclaimer.
+#
+# 2. Redistributions in binary form must reproduce the above copyright
+#    notice, this list of conditions and the following disclaimer in the
+#    documentation and/or other materials provided with the
+#    distribution.
+#
+# THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS
+# IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
+# TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A
+# PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
+# HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
+# SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
+# LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
+# DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
+# THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+# (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+# OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+#
+#
+# $Id$