1
  2
  3
  4
  5
  6
  7
  8
  9
 10
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
.. highlight:: none


.. index::
   pair: documentation; design

.. _design-doc:


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

.. mps:prefix:: design.mps.doc


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

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

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


Types
-----

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

:mps:tag:`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.)

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

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

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

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

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

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


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

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

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

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

:mps:tag:`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.

:mps:tag:`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.

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

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


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

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

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

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

:mps:tag:`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

:mps:tag:`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>`__.

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

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

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

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


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

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

:mps:tag:`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.

:mps:tag:`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.

:mps:tag:`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.

:mps:tag:`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.

:mps:tag:`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.

:mps:tag:`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.

:mps:tag:`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.

:mps:tag:`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.

:mps:tag:`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.

:mps:tag:`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 (:mps:ref:`.ext.aka`), nor opposites (:mps:ref:`.ext.opposite`), nor
similar (:mps:ref:`.ext.similar`).

:mps:tag:`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 (:mps:ref:`.ext.aka`).

:mps:tag:`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
-----------------------------

:mps:tag:`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.

:mps:tag:`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)


:mps:tag:`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)

:mps:tag:`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 :c:macro:`MACROS` global in designs.py.

:mps:tag:`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

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

    This saves a separate call to :c:func:`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.

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

    The function must return a :c:type:`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 :c:macro:`TYPES` global
in designs.py, plus any word matching ``mps_[a-z_]+_[stu]``, plus any
word ending ``Class``, ``Function``, ``Method``, ``Struct``, or
``Union``.

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

    :mps:tag:`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.

:mps:tag:`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 :mps:ref:`.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`).

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

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

:mps:tag:`fmt.sections` Section numbers are removed.

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

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

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

:mps:tag:`fmt.citation` Citations are translated from design style::

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

into manual style::

    [Citation] Author. Date. "`Title <URL>`__".

:mps:tag:`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] Richard Brooksby. Ravenbrook Limited. 2013-05-09. "`MPS design document format and process <https://info.ravenbrook.com/mail/2013/05/09/14-54-55/0/>`__".