From: Teemu Murtola Date: Fri, 29 May 2015 10:10:11 +0000 (+0300) Subject: Document current help formatting X-Git-Url: http://biod.pnpi.spb.ru/gitweb/?a=commitdiff_plain;h=96108bf8a48fb45def6e1679265a2b38ca087c93;p=alexxy%2Fgromacs.git Document current help formatting Add basic Doxygen documentation for the onlinehelp module. Most notably, this describes the markup used for the in-source comments, including the latest developments that allow bullet lists, enumerated lists, and some titles. Change-Id: I25be2bcd4c590356d4af0fa5671bbeddcd1afe1f --- diff --git a/docs/doxygen/lib/wrapperbinary.md b/docs/doxygen/lib/wrapperbinary.md index fd8c81c5dd..98f6fcc50d 100644 --- a/docs/doxygen/lib/wrapperbinary.md +++ b/docs/doxygen/lib/wrapperbinary.md @@ -97,6 +97,9 @@ The build system provides a target, `make sphinx-programs`, that generates reStructuredText help for the commands, which in turn is used to generate man and HTML help. Internally, this executes `gmx help -export rst`, which triggers special handling in the internal help module. +See documentation for +\linktodevmanual{build-system,special targets in the build system} for details +of which targets to use for generating the documentation.. If this option is set, the help module loops through all the modules in the binary, writing help for each into a separate file. The help module writes @@ -107,8 +110,6 @@ using a different help context than for console output). Additionally, a list of all the modules is generated (`gromacs.7` for man pages, and alphabetical and by-topic lists for the HTML pages). -TODO: Document/link to existing documentation for targets that use the rst help - Handling C %main() functions {#section_wrapperbinary_cmain} ---------------------------- diff --git a/docs/doxygen/user/mainpage.md b/docs/doxygen/user/mainpage.md index 68d021b769..8a984a817e 100644 --- a/docs/doxygen/user/mainpage.md +++ b/docs/doxygen/user/mainpage.md @@ -52,6 +52,8 @@ give an overview of some of the topics that are documented: - \subpage page_analysisframework
Provides an overview of the framework that the \Gromacs library provides for writing (trajectory) analysis tools. + - \subpage page_onlinehelp
+ Provides an overview of the formatting markup available in help texts. - \subpage page_usinglibrary
Provides general guidance for writing software that uses the \Gromacs library. diff --git a/docs/doxygen/user/onlinehelp.md b/docs/doxygen/user/onlinehelp.md new file mode 100644 index 0000000000..3c70c6dea0 --- /dev/null +++ b/docs/doxygen/user/onlinehelp.md @@ -0,0 +1,117 @@ +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 diff --git a/src/gromacs/onlinehelp-doc.h b/src/gromacs/onlinehelp-doc.h new file mode 100644 index 0000000000..8a7e1f7223 --- /dev/null +++ b/src/gromacs/onlinehelp-doc.h @@ -0,0 +1,62 @@ +/* + * 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 + */ +/*! \internal \file + * \brief + * Dummy header for \ref module_onlinehelp documentation. + */ diff --git a/src/gromacs/onlinehelp/helptopicinterface.h b/src/gromacs/onlinehelp/helptopicinterface.h index 2a6479ed27..79dfbc390b 100644 --- a/src/gromacs/onlinehelp/helptopicinterface.h +++ b/src/gromacs/onlinehelp/helptopicinterface.h @@ -1,7 +1,7 @@ /* * 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. @@ -32,19 +32,6 @@ * 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 - */ /*! \libinternal \file * \brief * Declares gmx::HelpTopicInterface.