.. mode: -*- rst -*-

Documentation
=============

:Tag: design.mps.doc
:Author: Gareth Rees
:Date: 2018-09-18
:Status: draft design
:Revision: $Id$
:Copyright: See section `Copyright and License`_.
:Index terms: pair: documentation; design


Introduction
------------

_`.intro`: This is the design of the documentation system for the
Memory Pool System.

_`.readership`: This document is intended for any MPS developer.


Types
-----

_`.type`: The MPS has multiple types of documentation, suitable for
different audiences.

_`.type.comment`: Comments in the code provide information that is
required in order for developers to make correct edits to nearby code.
(Audience: MPS developers editing nearby code.)

_`.type.design`: Design documentation lists requirements and explains
how the code meets the requirements. (Audience: MPS developers working
on a subsystem.)

_`.type.devguide`: Developer guides provide general guidance for
developers, not specific to any particular subsystem. (Audience: MPS
developers generally.)

_`.type.procedure`: Procedures list the steps for carrying out
development tasks. (Audience: MPS developers who need to carry out
particular tasks reliably.)

_`.type.tutorial`: Tutorials describe how to use the MPS to meet
client program requirements. (Audience: beginner client program
developers.)

_`.type.reference`: Reference documentation specifies the public
features of the MPS. (Audience: expert client program developers.)

_`.type.mmref`: The Memory Management Reference describes general
principles of memory management, with cross-references to the MPS
documentation. (Audience: the world.)


Requirements
------------

_`.req.source`: Derived from [RB_2013-05-09]_.

_`.req.easy`: It must be easy to read and write documentation using
standard text editors. Barriers to documentation must be low.

_`.req.presentation`: It must be possible to process documentation
into presentation formats, for example web pages.

_`.req.single-source`: Documents must have a single source. Processing
into other formats must be automatic and not depend on hand editing or
maintaining parallel versions.

_`.req.durable`: The format of documents should be supported for the
foreseeable future. It must not require continual updating to keep up
with changes to processing software.

_`.req.design.ref`: It must be easy to reference points made in design
documents from the code.

_`.req.design.standalone`: Design documents must stand alone: they
must not require particular software to make them readable or
complete.


Implementation
--------------

_`.impl.rst`: Documents are written in reStructuredText_ (RST).

.. _reStructuredText: http://docutils.sourceforge.net/rst.html

_`.impl.design`: Design documents are written in plain RST (with no
custom directives) to meet `.req.design.standalone`_.

_`.impl.design.pelican`: Design documents are converted to HTML using
|RstReader|_ as part of `Charlotte
<https://info.ravenbrook.com/project/charlotte>`__.

.. |RstReader| replace:: ``pelican.readers.RstReader``
.. _RstReader: https://fossies.org/dox/pelican-3.7.1/classpelican_1_1readers_1_1RstReader.html

_`.impl.design.github`: Design documents are also `rendered as HTML by GitHub <https://docs.github.com/en/repositories/working-with-files/using-files/working-with-non-code-files#rendering-differences-in-prose-documents>`__.

_`.impl.manual`: The manual is written in RST using Sphinx_ extensions
and custom manual extensions (see `.ext`_).

.. _Sphinx: https://www.sphinx-doc.org/en/master/

_`.impl.manual.sphinx`: The manual is converted to HTML using the
Sphinx_ documentation generator.

_`.impl.manual.design`: Design documents are automatically processed
for inclusion in the manual using a set of formatting conventions (see
`.fmt`_).


Manual extensions
-----------------

_`.ext`: These are reStructuredText directives and roles used by the
MPS manual. See manual/source/extensions/mps/__init__.py.

_`.ext.aka`: The ``aka`` directive generates an "Also known as"
section. This should be used in a glossary entry, and should contain a
comma-separated, alphabetically ordered, list of glossary entries (in
italics) that are synonyms for this glossary entry.

_`.ext.bibref`: The ``bibref`` directive generates a "Related
publication" or "Related publications" section. This should be used in
a glossary entry, and should contain a comma-separated, alphabetically
ordered, list of ``:ref:`` roles referring to entries in the
bibliography.

_`.ext.deprecated`: The ``deprecated`` directive generates a
"Deprecated" section. It should be used in a description of a public
interface in the MPS Reference, and describe the first version in
which the interface was deprecated, and the interface that should be
used instead. There may be an initial "starting with version 1.115"
paragraph, but this is unnecessary if the directive is used in the
"Deprecated interfaces" chapter.

_`.ext.historical`: The ``historical`` directive generates a
"Historical note" section. This should be used in a glossary entry,
and should contain material of historical interest, for example the
origin of the term, or ways in which it was formerly used.

_`.ext.link`: The ``link`` directive generates a "Related link" or
"Related links" section. This should be used in a glossary entry, and
should contain a comma-separated list of references to URLs.

_`.ext.note`: The ``note`` directive generates a "Note" or "Notes"
section. This should consist of a paragraph or a numbered list
containing especially important information about an interface that a
user should be aware of when using it.

_`.ext.opposite`: The ``opposite`` directive generates an "Opposite
term" or "Opposite terms" section. This should be used in a glossary
entry, and should contain a comma-separated, alphabetically ordered,
list of ``:term:`` roles referring to glossary entries with opposite
meaning.

_`.ext.relevance`: The ``relevance`` directive generates a "Relevance
to memory management" section. This should be used in a glossary
entry, and should contain an explanation of how the term relates to
memory management, if this is not obvious.

_`.ext.see`: The ``see`` directive generates a "See" section. This
should be used in a glossary entry, and should contain a single
``:term:`` role referring to the entry for which the currente entry is
a synonym.

_`.ext.seealso`: The ``seealso`` directive generates a "See also"
section. This should be used in a glossary entry, and should contain a
comma-separated, alphabetically ordered, list of ``:term:`` roles
referring to glossary entries that relate to the entry but are neither
synonyms for it (`.ext.aka`_), nor opposites (`.ext.opposite`_), nor
similar (`.ext.similar`_).

_`.ext.similar`: The ``similar`` directive generates a "Similar term"
or "Similar terms" section. This should be used in a glossary entry,
and should contain a comma-separated, alphabetically ordered, list of
``:term:`` roles referring to glossary entries with similar meaning to
the entry but which are not synonyms for it (`.ext.aka`_).

_`.ext.specific`: The ``mps:specific`` directive generates an "In the
MPS" section. This should be used in a glossary entry, and should
contain an explanation of how the glossary entry pertains to the MPS.
If the term is idiosyncratic to the MPS, for example "spare committed
memory" then the entire glossary entry should consist of a single
``mps:specific`` directive to make it clear that the term is not in
general use.


Design formatting conventions
-----------------------------

_`.fmt`: This section lists formatting conventions used in the design
documentation that are used to generate extended markup when the
design document is converted for use in the MPS manual. See
manual/source/extensions/mps/designs.py.

_`.fmt.function-decl`: A paragraph consisting of a function
declaration on a single line formatted as code, for example::

    ``void LandFinish(Land land)``

is translated into a ``c:function`` directive::

    .. c:function:: void LandFinish(Land land)


_`.fmt.macro-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)

_`.fmt.macro`: 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::

    ``typedef LandStruct *Land``

is translated into a ``c:type`` directive::

    .. c:type:: LandStruct *Land

_`.fmt.function-ref`: A word formatted as code and suffixed by ``()``,
for example::

    This saves a separate call to ``LandDelete()``, and uses the
    knowledge of exactly where we found the range.

is translated into a ``:c:func:`` role::

    This saves a separate call to :c:func:`LandDelete`, and uses the
    knowledge of exactly where we found the range.

_`.fmt.type-ref`: The name of an MPS type formatted as code, for
example::

    The function must return a ``Bool`` indicating whether to continue
    with the iteration.

is translated into a ``:c:type:`` role::

    The function must return a :c:type:`Bool` indicating whether to
    continue with the iteration.

The list of MPS types thus converted is given by the ``TYPES`` global
in designs.py, plus any word matching ``mps_[a-z_]+_[stu]``, plus any
word ending ``Class``, ``Function``, ``Method``, ``Struct``, or
``Union``.

_`.fmt.tag`: A paragraph starting with an MPS tag, for example::

    _`.type.land`: The type of a generic land instance.

is translated into an ``:mps:tag:`` role::

    :mps:tag:`type.land` The type of a generic land instance.

_`.fmt.ref`: Cross-references to tags, for example::

    A *node* is used in the typical data structure sense to mean an
    element of a tree (see also `.type.tree`_).

is translated into an ``:mps:ref:`` role::

    A *node* is used in the typical data structure sense to mean an
    element of a tree (see also :mps:ref:`.type.tree`).

_`.fmt.history`: The section "Document History" is removed.

_`.fmt.copyright`: The section "Copyright and License" is removed.

_`.fmt.sections`: Section numbers are removed.

_`.fmt.metadata`: Metadata roles are removed, except for:

_`.fmt.metadata.tag`: ``:Tag:``, which is translated into an
``mps:prefix`` directive; and

_`.fmt.metadata.index`: ``:Index Terms:``, which is is translated into
an ``index`` directive.

_`.fmt.citation`: Citations are translated from design style::

    [Citation] "Title"; Author; Date; <URL>.

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
----------

.. [RB_2013-05-09]
   "MPS design document format and process";
   Richard Brooksby; Ravenbrook Limited; 2013-05-09;
   <https://info.ravenbrook.com/mail/2013/05/09/14-54-55/0/>.


Document History
----------------

- 2018-09-18 GDR_ Created based on [RB_2013-05-09]_.
- 2023-02-15 RB_ Updating for migration to GitHub.

.. _GDR: https://www.ravenbrook.com/consultants/gdr/
.. _RB: mailto:rb@ravenbrook.com


Copyright and License
---------------------

Copyright © 2018–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.
