.. mode: -*- rst -*- Documentation ============= :Tag: design.mps.doc :Author: Gareth Rees :Date: 2018-09-18 :Status: draft design :Revision: $Id: //info.ravenbrook.com/project/mps/master/design/doc.txt#13 $ :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 `__. .. |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 `__. _`.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; . into manual style:: [Citation] Author. Date. "`Title `__". _`.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; . 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 `_. 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.