Feature #1437

Updated by Teemu Murtola about 5 years ago

Various suggestions to improve the man pages/HTML help/output of @-h@ or the process that generates them have been raised (some in #969, some elsewhere). Collected them here and grouped somewhat.

Formatting of man pages:
* OPTIONS: AFAIK all @-foo@/@--foo-long@ switches and options typically go to this section which means everything currently in "FILES" belongs to "OPTIONS". *Done* (for 5.0, there is a single OPTIONS section for all the command-line options).
* FILES: seems to be for the file-arguments, not the options with file arguments. We don't have many (any?) plain file arguments, I think. *Done* (see above)
* SYNOPSIS: file arguments are normally not listed with the default values, but in a generic way, right? Also, the current formatting is somewhat off of what the synopsis typically looks like: lacks the [] and | hints, the different forms of invocation would be nice to separate (MD, EM, etc.). Moving toward a more standard SYNOPSIS section would be useful not only for the sake of standardization, but also because IMO it'd make it more readable and suggestive. *Partially done* (for 5.0, the synopsis uses a bit more standard notation)
* There are a few stray spaces at the beginning or end of lines (e.g. @man gmx-mdrun@ DESCRIPTION 1st par 1st line, 2nd par 2nd line both beginning and end). Would it be easy to strip these away? *Done* (for 5.0)
* Because of limitations in the markup commands available, multiple tools have resorted to hardcoded formatting like below. This looks horrible in particular in the HTML pages, but also not very good on man pages.
* Itemized list.[BR]
* Another entry.[BR]
*Done* (for 5.1, some reStructuredText paragraph formatting is supported to get rid of all [BR] tags in the input); some changes still pending review in Gerrit

Console help:
* It would be useful to have a _brief_ @-h@ help output with usage and brief option description; e.g. see @git commit -h@ vs @git commit --help@: 45 vs 450 lines.
* Additionally, formatting like the above example doesn't work currently very nicely for console output either, because it strips leading whitespace from each output line. *Done* (for 5.1)

Build system for man pages:
* Man pages should be produced and installed by default also for builds from git. The problem is that this requires executing the compiled binaries, which does not work in cross-compilation cases, and we currently have no reliable means to detect when this is the case. *Obsolete* (@GMX_BUILD_HELP=AUTO@ did something for this, but it already got superseded by using Sphinx for generating the man pages, which makes it difficult to produce and install the man pages by default)
* Current approach of generating uniform headers and footers for the HTML pages is horrible, with a mixture of C++ and CMake code doing string replacements and cutting and pasting file fragments to get the final files. Also, links on HTML pages that are not automatically generated are hard to maintain and check that they are actually working. *Done* (for 5.1, all HTML documentation is produced with Sphinx)
* With @GMX_BUILD_MDRUN_ONLY=ON@ we should install a share/man/man1/mdrun.1 (or perhaps symlink to gmx-mdrun.1?)

Content of man pages:
* How/where should we document relevant env. vars - often there is a separate section for this (see e.g. @man git@)?
* Could be nice to add in the future a few more sections like "FURTHER DOCUMENTATION", "REPORTING BUGS", etc. (got inspired by @man git@). This will require code to format new sections, right?
* Just realized that the main binary is called @gmx@, but we install @share/man/man7/gromacs.7@. As one would typically expect to have a man page corresponding to the binary's name, perhaps we should add a @gmx.7@ -> @gromacs.7@ symlink.

Our current support for nroff formatting is very limited. The new formatter produces slightly nicer-looking man pages than the old one, but they are still ugly. However, nroff is ancient, and it appears that typically people generate man pages using some tools from a more user-friendly format. If we want to put some effort into cleaning them up, we should also invest in choosing such a tool; ideally, it would also allow us to generate the whole HTML online reference from the same input format, including the headers/footers and links between the pages. For example, the mentioned @git@ man pages appear to be generated from asciidoc. *Done* (now the man pages are generated using Sphinx)

Some preceding discussion is in #969, on the possible alternative formats and on the man page improvements.