Gromacs  2016.6
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Groups Pages
Help formatting

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:

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:

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

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.