diff --git a/.github/workflows/rst-check.yml b/.github/workflows/rst-check.yml new file mode 100644 index 0000000000..329b1b2043 --- /dev/null +++ b/.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 +# +# 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 diff --git a/.travis.yml b/.travis.yml index 2153440b00..796c776d84 100644 --- a/.travis.yml +++ b/.travis.yml @@ -4,7 +4,7 @@ # Some branches don't need builds. Add them here to avoid using build # resources and unnecessary build messages. See # . -if: NOT branch IN (branch/2023-01-07/pull-request-merge-procedure) +if: NOT branch IN (branch/2023-01-13/rst-check) # The main build matrix for POSIX-like systems. language: c # see . diff --git a/design/arena.txt b/design/arena.txt index d368829683..e8df0817c2 100644 --- a/design/arena.txt +++ b/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. diff --git a/design/config.txt b/design/config.txt index 0afb21d778..7f6337c9e5 100644 --- a/design/config.txt +++ b/design/config.txt @@ -169,7 +169,7 @@ predefined when compiling the module sources:: CONFIG_VAR_ -_`.var`: The variety codes are as follows: +_`.var.codes`: The variety codes are as follows: _`.var.hot`: ``HOT`` diff --git a/design/poolamc.txt b/design/poolamc.txt index 5771ba5a1c..670dafd00a 100644 --- a/design/poolamc.txt +++ b/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 + . 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 diff --git a/design/poolawl.txt b/design/poolawl.txt index cd2625d3c6..ebad6106ee 100644 --- a/design/poolawl.txt +++ b/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)`` diff --git a/design/prmc.txt b/design/prmc.txt index 6c55634a8b..8a5d71ad01 100644 --- a/design/prmc.txt +++ b/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. diff --git a/design/protix.txt b/design/protix.txt index 88a764f66a..529b43990a 100644 --- a/design/protix.txt +++ b/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. diff --git a/design/protocol.txt b/design/protocol.txt index 8d285fd9e1..93ac13efd0 100644 --- a/design/protocol.txt +++ b/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 diff --git a/design/shield.txt b/design/shield.txt index 489bec6743..248b72c434 100644 --- a/design/shield.txt +++ b/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`_. diff --git a/design/tests.txt b/design/tests.txt index 4613447bd4..c6c2686f5f 100644 --- a/design/tests.txt +++ b/design/tests.txt @@ -32,7 +32,7 @@ _`.run`: Run these commands:: where ```` is the appropriate makefile for the platform (see `manual/build.txt`_), ```` is the variety (see -design.mps.config.var_) and ```` is the collection of tests +design.mps.config.var.codes_) and ```` is the collection of tests (see `.target`_ below). For example:: make -f lii6ll VARIETY=cool testrun @@ -40,7 +40,7 @@ design.mps.config.var_) and ```` is the collection of tests If ```` 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 diff --git a/procedure/release-build.rst b/procedure/release-build.rst index eff46a9299..233789e71a 100644 --- a/procedure/release-build.rst +++ b/procedure/release-build.rst @@ -280,7 +280,7 @@ B. Document History .. _NB: mailto:nb@ravenbrook.com .. _RHSK: mailto:rhsk@ravenbrook.com .. _GDR: mailto:gdr@ravenbrook.com -.. _PNJ mailto:pnj@ravenbrook.com +.. _PNJ: mailto:pnj@ravenbrook.com C. Copyright and License ------------------------ diff --git a/tool/check-rst b/tool/check-rst new file mode 100755 index 0000000000..66052e4a76 --- /dev/null +++ b/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 . +# +# 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$