Some parts of GROMACS use in-source strings as a documentation source. The most notable use of these is the description and options list printed out by the -h command line, and this case is exposed also to code that uses GROMACS as a library to write command-line tools. The help text is declared as an array of strings:

const char *const desc[] = {
    "First paragraph.",
    "",
    "Second paragraph",
    "with more text",
    "and [TT]some formatting[tt].",
};

The array variable is then passed to a function that exposes it as the help text. Some of the help content is also generated based on, e.g., the list of options that the program declares.

The same approach is also used internally in GROMACS in a few other places. The same help text is used for console output (like in the -h case), as well as for producing reStructuredText. The reStructuredText output is passed to Sphinx to produce a HTML user guide and Unix man pages.

Formatting markup

Partly due to historical reasons, the markup allowed within the help text is a mixture of reStructuredText and GROMACS-specific markup. The allowed formatting is currently not that extensive, but basic constructs should work.

The general approach to formatting is that the text is written to reStructuredText as-is, after replacement of the GROMACS-specific markup, with line breaks between each string in the input array. This means that the commas at the end of each line (separating the strings) are critical for proper formatting. This also means that any reStructuredText construct will appear correctly in the HTML and man pages (as long as the output format supports it).

For console output, there input string is parsed for some basic reStructuredText constructs to be able to rewrap the text to the console width (currently fixed at 78 characters). This parsing is one major constraint on what reStructuredText constructs can be used; paragraph-level markup that is not recognized by this parser results in messy console output. Inline markup is currently not processed in any way, so any construct that renders reasonably in plain text can in principle be used.

reStructuredText

The following reStructuredText constructs are recognized and work for console output:

Paragraphs, i.e., blocks of text separated by an empty line. Text within each paragraph is wrapped separately, and indentation is preserved (as long as the whole paragraph has the same indentation level, which is expected for reStructuredText). This means that block quotes are also rendered reasonably, since they are just indented paragraphs.
Literal blocks, i.e., indented paragraphs where the preceding paragraph ends with ::. Line breaks within such paragraphs are preserved. The rules for handling the :: are the same as in reStructuredText. Multiple paragraphs within a literal block are not currently supported.
Titles, i.e., a line underlined by a punctuation character. Title formatting is currently preserved as-is, so it must be manually ensured that the used punctuation character properly fits into the context (i.e., other titles in the same generated reStructuredText document). Titles with both under- and overline are not currently supported.
Bullet lists. Only lists that start with * are currently recognized. Indentation for the second and subsequent lines is determined from the first non-space character after the bullet and/or from the second line in the input (if these are not the same, the minimum is used). Note that in reStructuredText, the * must not be indented with respect to the preceding paragraph; otherwise, the bullet list is rendered within a block quote. Also, an empty line needs to precede a bullet list.
Enumerated lists. Only lists that start with digits are supported (e.g., 1.). Multi-digit numbers can be used. Indentation is determined as for bullet lists. Lists are not renumbered automatically.

GROMACS-specific markup

Markup within paragraphs is currently done with GROMACS-specific constructs limited with brackets. In the future, some of these may get replaced with more reStructuredText constructs. The following are used:

[TT]/[tt]: text between these tags is formatted in a monospace font.
[BB]/[bb]: text between these tags is formatted in a bold font.
[IT]/[it]: text between these tags is formatted in an italic font.
[MAG]/[mag]: text between these tags is rendered between | (bar) characters (which is a special character in reStructuredText).
[PAR]: this is replaced by two newlines to produce a paragraph break. For any new help text, an explicit empty line is preferred. Various other markup constructs, mainly related to math, are also used in some places, but currently these are always replaced with the same text irrespective of the output format, and a new approach is needed for proper math support.

Additionally, the following replacements are possible (not necessarily in all contexts):

[REF]/[ref]: replaced with a link to a section that describes the term between these tags. Only affects the reStructuredText output; the tags are simply removed from console output. The mechanism for managing these crosslinks would need additional work.
[THISMODULE]: replaced with the name of the current module/command (e.g., gmx angle).
[PROGRAM]: replaced with the name of the current executable (e.g., gmx).

Implementation

See Help Formatting for Online Help (onlinehelp) module documentation for implementation details.

See Wrapper binary implementation for details of how the reStructuredText help is exported and processed further.