--- /dev/null
+Help formatting {#page_onlinehelp}
+===============
+
+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 (but
+ varying indentation is not currently implemented). The rules for handling
+ the `::` are the same as in reStructuredText.
+ - 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 either 2 (if the bullet
+ text is on a single line in input), or determined from the second line in
+ the input.
+ 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.
+ - Enumerated lists. Only lists that start with digits are supported (e.g.,
+ `1.`). Multi-digit numbers can be used.
+ Indentation for the second and subsequent lines is determined either from
+ the first non-space character after the period (if there is a single line in
+ the input), or from the second line in the input.
+ 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`).
+
+\if libapi
+Implementation
+==============
+
+See \ref module_onlinehelp module documentation for implementation details.
+
+See \ref page_wrapperbinary for details of how the reStructuredText help is
+exported and processed further.
+\endif
--- /dev/null
+/*
+ * This file is part of the GROMACS molecular simulation package.
+ *
+ * Copyright (c) 2015, by the GROMACS development team, led by
+ * Mark Abraham, David van der Spoel, Berk Hess, and Erik Lindahl,
+ * and including many others, as listed in the AUTHORS file in the
+ * top-level source directory and at http://www.gromacs.org.
+ *
+ * GROMACS is free software; you can redistribute it and/or
+ * modify it under the terms of the GNU Lesser General Public License
+ * as published by the Free Software Foundation; either version 2.1
+ * of the License, or (at your option) any later version.
+ *
+ * GROMACS is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
+ * Lesser General Public License for more details.
+ *
+ * You should have received a copy of the GNU Lesser General Public
+ * License along with GROMACS; if not, see
+ * http://www.gnu.org/licenses, or write to the Free Software Foundation,
+ * Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
+ *
+ * If you want to redistribute modifications to GROMACS, please
+ * consider that scientific software is very special. Version
+ * control is crucial - bugs must be traceable. We will be happy to
+ * consider code for inclusion in the official distribution, but
+ * derived work must not be called official GROMACS. Details are found
+ * in the README & COPYING files - if they are missing, get the
+ * official version at http://www.gromacs.org.
+ *
+ * To help us fund GROMACS development, we humbly ask that you cite
+ * the research papers on the package. Check out http://www.gromacs.org.
+ */
+/*! \libinternal \defgroup module_onlinehelp Help Formatting for Online Help (onlinehelp)
+ * \ingroup group_utilitymodules
+ * \brief
+ * Provides functionality for formatting help text for console and reStructuredText.
+ *
+ * This module provides helper functions and classes for formatting text to the
+ * console and as reStructuredText through a single interface. The main
+ * components of the module are:
+ * - gmx::HelpWriterContext provides a single interface that can produce both
+ * output formats from the same input strings and API calls. Whenever
+ * possible, the output format should be abstracted using this interface,
+ * but in some cases code still writes out raw reStructuredText.
+ * - helpformat.h provides some general text-processing classes, currently
+ * focused on producing aligned tables for console output.
+ * - helptopicinterface.h, helptopic.h, and helpmanager.h provide classes for
+ * managing a hierarchy of help topics and printing out help from this
+ * hierarchy.
+ *
+ * The formatting syntax for strings accepted by this module is described in
+ * \ref page_onlinehelp. The module is currently exposed outside \Gromacs only
+ * through this formatting syntax, not any API calls.
+ *
+ * \author Teemu Murtola <teemu.murtola@gmail.com>
+ */
+/*! \internal \file
+ * \brief
+ * Dummy header for \ref module_onlinehelp documentation.
+ */
/*
* This file is part of the GROMACS molecular simulation package.
*
- * Copyright (c) 2012,2014, by the GROMACS development team, led by
+ * Copyright (c) 2012,2014,2015, by the GROMACS development team, led by
* Mark Abraham, David van der Spoel, Berk Hess, and Erik Lindahl,
* and including many others, as listed in the AUTHORS file in the
* top-level source directory and at http://www.gromacs.org.
* To help us fund GROMACS development, we humbly ask that you cite
* the research papers on the package. Check out http://www.gromacs.org.
*/
-/*! \libinternal \defgroup module_onlinehelp Help Formatting for Online Help (onlinehelp)
- * \ingroup group_utilitymodules
- * \brief
- * Provides functionality for formatting help text for console and other
- * formats.
- *
- * This module provides helper functions and classes for formatting console
- * help, as well as man pages and HTML help from the source code. It should
- * not be necessary to call any methods in this module outside the \Gromacs
- * library.
- *
- * \author Teemu Murtola <teemu.murtola@gmail.com>
- */
/*! \libinternal \file
* \brief
* Declares gmx::HelpTopicInterface.
biod.pnpi.spb.ru / alexxy / gromacs.git / commitdiff