Project

General

Profile

Feature #1437

Updated by Teemu Murtola over 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:
elsewhere):
* OPTIONS: AFAIK all @-foo@/@--foo-long@ switches Man pages should be produced and options typically go to installed by default also for builds from git. The problem is that this section requires executing the compiled binaries, which does not work in cross-compilation cases, and we currently have no reliable means everything currently in "FILES" belongs to "OPTIONS". detect when this is the case.
* FILES: seems It would be useful to be for the file-arguments, not the options have a _brief_ @-h@ help output with file arguments. We don't have many (any?) plain file arguments, I think. usage and brief option description; e.g. see @git commit -h@ vs @git commit --help@: 45 vs 450 lines.
* 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.
* OPTIONS: AFAIK all @-foo@/@--foo-long@ switches and options typically go to this section which means everything currently in "FILES" belongs to "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.
*
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?
* 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?
* With @GMX_BUILD_MDRUN_ONLY=ON@ we should install a share/man/man1/mdrun.1 (or perhaps symlink to gmx-mdrun.1?)
* 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.
*
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.
<pre>
Header[BR]
------[PAR]
* Itemized list.[BR]
* Another entry.[BR]
</pre>

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.

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.
*
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.
* 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.

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

Back