1Help formatting {#page_onlinehelp}
2===============
3
4Some parts of \Gromacs use in-source strings as a documentation source.  The
5most notable use of these is the description and options list printed out by
6the `-h` command line, and this case is exposed also to code that uses \Gromacs
7as a library to write command-line tools.  The help text is declared as an
8array of strings:
9
10    const char *const desc[] = {
11        "First paragraph.",
12        "",
13        "Second paragraph",
14        "with more text",
15        "and [TT]some formatting[tt].",
16    };
17
18The array variable is then passed to a function that exposes it as the help
19text.  Some of the help content is also generated based on, e.g., the list of
20options that the program declares.
21
22The same approach is also used internally in \Gromacs in a few other places.
23The same help text is used for console output (like in the `-h` case), as well
24as for producing reStructuredText.  The reStructuredText output is passed to
25Sphinx to produce a HTML user guide and Unix man pages.
26
27Formatting markup
28=================
29
30Partly due to historical reasons, the markup allowed within the help text is a
31mixture of reStructuredText and \Gromacs-specific markup.  The allowed
32formatting is currently not that extensive, but basic constructs should work.
33
34The general approach to formatting is that the text is written to
35reStructuredText as-is, after replacement of the \Gromacs-specific markup, with
36line breaks between each string in the input array.  This means that the commas
37at the end of each line (separating the strings) are critical for proper
38formatting.  This also means that any reStructuredText construct will appear
39correctly in the HTML and man pages (as long as the output format supports it).
40
41For console output, there input string is parsed for some basic
42reStructuredText constructs to be able to rewrap the text to the console width
43(currently fixed at 78 characters).  This parsing is one major constraint on
44what reStructuredText constructs can be used; paragraph-level markup that is
45not recognized by this parser results in messy console output.  Inline markup
46is currently not processed in any way, so any construct that renders reasonably
47in plain text can in principle be used.
48
49reStructuredText
50----------------
51
52The following reStructuredText constructs are recognized and work for console
53output:
54 - Paragraphs, i.e., blocks of text separated by an empty line.  Text within
55   each paragraph is wrapped separately, and indentation is preserved (as long
56   as the whole paragraph has the same indentation level, which is expected for
57   reStructuredText).  This means that block quotes are also rendered
58   reasonably, since they are just indented paragraphs.
59 - Literal blocks, i.e., indented paragraphs where the preceding paragraph ends
60   with `::`.  Line breaks within such paragraphs are preserved.  The rules for
61   handling the `::` are the same as in reStructuredText.
62   Multiple paragraphs within a literal block are not currently supported.
63 - Titles, i.e., a line underlined by a punctuation character.
64   Title formatting is currently preserved as-is, so it must be manually
65   ensured that the used punctuation character properly fits into the context
66   (i.e., other titles in the same generated reStructuredText document).
67   Titles with both under- and overline are not currently supported.
68 - Bullet lists.  Only lists that start with `*` are currently recognized.
69   Indentation for the second and subsequent lines is determined from
70   the first non-space character after the bullet and/or from the second line
71   in the input (if these are not the same, the minimum is used).
72   Note that in reStructuredText, the `*` must not be indented with respect to
73   the preceding paragraph; otherwise, the bullet list is rendered within a
74   block quote.  Also, an empty line needs to precede a bullet list.
75 - Enumerated lists.  Only lists that start with digits are supported (e.g.,
76   `1.`).  Multi-digit numbers can be used.
77   Indentation is determined as for bullet lists.
78   Lists are not renumbered automatically.
79
80\Gromacs-specific markup
81------------------------
82
83Markup within paragraphs is currently done with \Gromacs-specific constructs
84limited with brackets.  In the future, some of these may get replaced with more
85reStructuredText constructs.  The following are used:
86 - `[TT]`/`[tt]`: text between these tags is formatted in a monospace font.
87 - `[BB]`/`[bb]`: text between these tags is formatted in a bold font.
88 - `[IT]`/`[it]`: text between these tags is formatted in an italic font.
89 - `[MAG]`/`[mag]`: text between these tags is rendered between `|` (bar)
90   characters (which is a special character in reStructuredText).
91 - `[PAR]`: this is replaced by two newlines to produce a paragraph break.
92   For any new help text, an explicit empty line is preferred.
93Various other markup constructs, mainly related to math, are also used in some
94places, but currently these are always replaced with the same text irrespective
95of the output format, and a new approach is needed for proper math support.
96
97Additionally, the following replacements are possible (not necessarily in all
98contexts):
99 - `[REF]`/`[ref]`: replaced with a link to a section that describes the term
100   between these tags.  Only affects the reStructuredText output; the tags are
101   simply removed from console output.
102   The mechanism for managing these crosslinks would need additional work.
103 - `[THISMODULE]`: replaced with the name of the current module/command
104   (e.g., `gmx angle`).
105 - `[PROGRAM]`: replaced with the name of the current executable (e.g., `gmx`).
106
107\if libapi
108Implementation
109==============
110
111See \ref module_onlinehelp module documentation for implementation details.
112
113See \ref page_wrapperbinary for details of how the reStructuredText help is
114exported and processed further.
115\endif
116