The format of choice for authoring project documentation.

Last Significant Update:

2024-07-12

Status:

Draft

Comments to:

mensurae@jkoshy.net

Requirements

  • Documentation should be easy to create and edit.  Markup formats that are close to plain text are preferred to formats like DocBook+XML that are difficult to read directly.

  • The documentation sources should be translatable into a variety of output formats (i.e., to HTML, PDF, etc.)

  • Documentation should be subject to revision control.

  • Documentation fragments should be easy to re-use across delivery platforms (the Web, PDF documents, etc.).

  • The documentation format should be expressive, and suited for marking up technical documentation.

  • The documentation format should be easy to extend with custom markup if need be.

Selection

  • For general documentation: AsciiDoc (https://www.asciidoc.org/).

    AsciiDoc offers an “almost plain text” markup syntax, while retaining much of the precision of markup offered by Docbook/XML.  The downside for the AsciiDoc format is that (currently) only a small number of tools process it.

  • For manual pages: the mdoc markup language.

    This markup format is the standard for BSD manual pages.

Alternatives Considered

Markdown

A text format that is easy to use, but one that is limited in its precision of markup.

Docbook+XML

A markup format that is widely used for technical publications, but also one that is “noisy” due to it being XML.