docs/doxygen/user/onlinehelp.md

   1 Help formatting {#page_onlinehelp}
   2 ===============
   3
   4 Some parts of \Gromacs use in-source strings as a documentation source.  The
   5 most notable use of these is the description and options list printed out by
   6 the `-h` command line, and this case is exposed also to code that uses \Gromacs
   7 as a library to write command-line tools.  The help text is declared as an
   8 array 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
  18 The array variable is then passed to a function that exposes it as the help
  19 text.  Some of the help content is also generated based on, e.g., the list of
  20 options that the program declares.
  21
  22 The same approach is also used internally in \Gromacs in a few other places.
  23 The same help text is used for console output (like in the `-h` case), as well
  24 as for producing reStructuredText.  The reStructuredText output is passed to
  25 Sphinx to produce a HTML user guide and Unix man pages.
  26
  27 Formatting markup
  28 =================
  29
  30 Partly due to historical reasons, the markup allowed within the help text is a
  31 mixture of reStructuredText and \Gromacs-specific markup.  The allowed
  32 formatting is currently not that extensive, but basic constructs should work.
  33
  34 The general approach to formatting is that the text is written to
  35 reStructuredText as-is, after replacement of the \Gromacs-specific markup, with
  36 line breaks between each string in the input array.  This means that the commas
  37 at the end of each line (separating the strings) are critical for proper
  38 formatting.  This also means that any reStructuredText construct will appear
  39 correctly in the HTML and man pages (as long as the output format supports it).
  40
  41 For console output, there input string is parsed for some basic
  42 reStructuredText 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
  44 what reStructuredText constructs can be used; paragraph-level markup that is
  45 not recognized by this parser results in messy console output.  Inline markup
  46 is currently not processed in any way, so any construct that renders reasonably
  47 in plain text can in principle be used.
  48
  49 reStructuredText
  50 ----------------
  51
  52 The following reStructuredText constructs are recognized and work for console
  53 output:
  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
  83 Markup within paragraphs is currently done with \Gromacs-specific constructs
  84 limited with brackets.  In the future, some of these may get replaced with more
  85 reStructuredText 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.
  93 Various other markup constructs, mainly related to math, are also used in some
  94 places, but currently these are always replaced with the same text irrespective
  95 of the output format, and a new approach is needed for proper math support.
  96
  97 Additionally, the following replacements are possible (not necessarily in all
  98 contexts):
  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
 108 Implementation
 109 ==============
 110
 111 See \ref module_onlinehelp module documentation for implementation details.
 112
 113 See \ref page_wrapperbinary for details of how the reStructuredText help is
 114 exported and processed further.
 115 \endif