Update relative link aliases in design when building the manual.

Update design so that relative links only occur in link aliases, where
they can be recognized by a regular expression.

mps/design/config.txt

@@ -69,9 +69,11 @@ Definitions
 
 _`.def.platform`: A *platform* is a combination of an architecture
 (`.def.arch`_), an operating system (`.def.os`_), and a builder
-(`.def.builder`_).  The set of supported platforms is maintained in the
+(`.def.builder`_). The set of supported platforms is maintained in the
 `Platforms section of "Building the Memory Pool System"
-<../manual/html/guide/build.html#platforms>`_.
+<platforms_>`_.
+
+.. _platforms: ../manual/html/guide/build.html#platforms
 
 _`.def.arch`: An *architecture* is processor type with associated calling
 conventions and other binary interface stuff these days often called the
@@ -113,9 +115,10 @@ source code.  Since `version 1.110`_ we made it possible to simply
 include the file ``mps.c`` in a client's build process, without
 requiring a separate build of the MPS or linking a library.  This is
 described `section 2.3.1, "Compiling for production" of the MPS manual
-<../manual/html/guide/build.html#compiling-for-production>`_.
+<compiling_>`_.
 
 .. _`version 1.110`: https://www.ravenbrook.com/project/mps/version/1.110/
+.. _compiling: ../manual/html/guide/build.html#compiling-for-production
 
 _`.no-gen`: No generated code or external tools are required.  On most
 platforms the only tool is the C compiler.  On 64-bit Windows we require
@@ -127,7 +130,9 @@ messy code bases which used a great number of ``#ifdef`` statements.
 These quickly became very expensive to maintain and develop.  The
 general rule in the MPS is "no ``#ifdefs``".  Instead, platform-specific
 code is kept in separate source files and selected by carefully controlled
-``#ifdefs``, such as in `mps.c <../code/mps.c>`_.
+``#ifdefs``, such as in mps.c_.
+
+.. _mps.c: ../code/mps.c
 
 _`.min-dep`: Dependency on a particular configuration should be
 minimized and localized when developing code.  This is enshrined in the
@@ -244,12 +249,15 @@ be suffixed with on or more target parameter codes (defined below). In
 particular, the names of assembly language sources must include the
 target parameter code for the relevant architecture.
 
-_`.mod.example`: For example, the stack scanner is defined in `ss.h
-<../code/ss.h>`_ (which is platform-independent).  It has some
-platform-independent C in `ss.c <../code/ss.c>`_ and, for example,
-`ssw3i6mv.c <../code/ssw3i6mv.c>`_ is specific to Windows on the x64
+_`.mod.example`: For example, the stack scanner is defined in ss.h_
+(which is platform-independent). It has some platform-independent C in
+ss.c_ and, for example, ssw3i6mv.c_ is specific to Windows on the x64
 architecture built with Microsoft Visual C.
 
+.. _ss.c: ../code/ss.c
+.. _ss.h: ../code/ss.h
+.. _ssw3i6mv.c: ../code/ssw3i6mv.c
+
 
 Build system rationale
 ......................
@@ -346,8 +354,8 @@ identifiers beginning "CONFIG\_" should only appear in impl.h.config.
 Code may depend on configuration parameters in certain, limited ways, as
 defined below (`.conf`_).
 
-.. _`config.h`: <../code/config.h>
-.. _`mpstd.h`: <../code/mpstd.h>
+.. _config.h: ../code/config.h
+.. _mpstd.h: ../code/mpstd.h
 
 
 Target platform detection
@@ -428,12 +436,14 @@ usually just ``unsigned long`` but under Microsoft C on 64-bit Windows
 
     #define MPS_T_ULONGEST      unsigned __int64
 
-_`.pf.pf-string`: The declaration of ``MPS_PF_STRING`` defines a string
-that is used to identify the target platform in `version.c
-<../code/version.c>`_.  For example::
+_`.pf.pf-string`: The declaration of ``MPS_PF_STRING`` defines a
+string that is used to identify the target platform in version.c_. For
+example::
 
     #define MPS_PF_STRING   "w3i6mv"
 
+.. _version.c: ../code/version.c
+
 
 Target varieties
 ................

mps/design/critical-path.txt

@@ -222,7 +222,9 @@ MPS, we encourage clients to compile the MPS in the same translation
 unit as their format code, so that the compiler can be intelligent
 about inlining parts of ``_mps_fix2()`` in the format scanner. The
 instructions for doing this are in `Building the Memory Pool System
-<../manual/build.txt>`_, part of the manual.
+<build.txt_>`_, part of the manual.
+
+.. _build.txt: ../manual/build.txt
 
 
 The second stage fix in the MPM
@@ -326,12 +328,11 @@ So far this document has described the ways in which the garbage
 collector is designed around optimising the critical path.  There are a
 few other things that the MPS does that are important.
 
-Firstly, inlining is very important.  The first stage fix is inlined
-into the format scanner by being implemented in macros in
-mps.h_.  And to get even better inlining, `we
-recommend <../manual/build.txt>`_ that the whole MPS is compiled in a
-single translation unit with the client format and that strong global
-optimisation is applied.
+Firstly, inlining is very important. The first stage fix is inlined
+into the format scanner by being implemented in macros in mps.h_. And
+to get even better inlining, `we recommend <build.txt_>`_ that the
+whole MPS is compiled in a single translation unit with the client
+format and that strong global optimisation is applied.
 
 Secondly, we are very careful with code annotations on the critical
 path.  Assertions, statistics, and telemetry are all disabled on the

mps/design/doc.txt

@@ -281,6 +281,20 @@ into manual style::
 
     [Citation] Author. Date. "`Title <URL>`__".
 
+_`.fmt.link.relative`: Project-relative links must be specified using
+`named hyperlink targets`_ whose targets start with ``../``, for
+example::
+
+    ``#ifdefs``, such as in mps.c_.
+
+    .. _mps.c: ../code/mps.c
+
+The target is adjusted to reflect the different location of the manual
+sources relative to the design sources.
+
+.. _named hyperlink targets: https://docutils.sourceforge.io/docs/ref/rst/restructuredtext.html#hyperlink-targets
+
+
 
 References
 ----------

mps/design/interface-c.txt

@@ -87,10 +87,10 @@ Naming conventions
 
 _`.naming`: The external interface names should adhere to the
 documented interface conventions; these are found in the “`Interface
-conventions`_” chapter of the Reference Manual. They are
+conventions <interface.html_>`_” chapter of the Reference Manual. They are
 paraphrased/recreated here.
 
-.. _Interface conventions: ../topic/interface.html
+.. _interface.html: ../topic/interface.html
 
 _`.naming.file`: All files in the external interface have names
 starting with ``mps``.

mps/manual/source/extensions/mps/designs.py

@@ -50,6 +50,7 @@ typename = re.compile(r'``({0}|[A-Z][A-Za-z0-9_]*'
                       .format('|'.join(map(re.escape, TYPES.split()))))
 design_ref = re.compile(r'^( *\.\. _design\.mps\.(?:[^:\n]+): (?:[^#:\n]+))$', re.MULTILINE)
 design_frag_ref = re.compile(r'^( *\.\. _design\.mps\.([^:\n]+)\.([^:\n]+): (?:[^#:\n]+))#(.+)$', re.MULTILINE)
+relative_link = re.compile(r'^( *\.\. _[\w\.]+: +\.\./)', re.MULTILINE)
 history = re.compile(r'^Document History\n.*',
                      re.MULTILINE | re.IGNORECASE | re.DOTALL)
 
@@ -124,6 +125,7 @@ def convert_file(name, source, dest):
     s = citation.sub(citation_sub, s)
     s = design_ref.sub(r'\1.html', s)
     s = design_frag_ref.sub(r'\1.html#design.mps.\2.\3', s)
+    s = relative_link.sub(r'\1../../', s)
     s = history.sub('', s)
     # Don't try to format all the quoted code blocks as C.
     s = '.. highlight:: none\n\n' + s