Generate well-formatted man-pages from the output of -h

Introduction

Many projects suffer from poor, missing, or out-of-date man pages. These tend to get out-of-sync with the main release, especially because they are tricky to write (the GROFF language isn't exactly familiar to most programmers, even with the asssistance of utilities such as manedit.

I think the most natural place for documentation is inside the program itself (invocation with "-h"), because it keeps the documentation and code together - this makes it much easier to keep them in sync, and to ensure the documentation is written at all. Furthermore, it allows the documentation to be more accurate: the output of "-h" can include information known to the program, such as #defined constants from the header file, or specific build-time details; these can't usually be dynamically inserted into man pages.
It does makethe binaries slightly bigger, but usually this isn't a problem.

Thus, help_to_man, a system designed for the maximum simplicity of integration and ease of use. It takes only a couple of minutes to add to your project, and it emits correct, standard man-pages. It also builds html man pages. Full details are in the README.txt, and there is an example project with makefile included herein.

Alternatives: there is already a program help2man but that is actually more complicated to use, and doesn't always get the output correct. Notably, it doesn't always escape text correctly from groff, it tends to create double-spaced text (blank-lines between every line), and it always re-wraps the output of -h, even when you may wish to prevent this. Furthermore, it's more complicated to use and less flexible. Also, man2html alone is designed to work as part of a CGI-script. so it adds unwanted headers; we remove them, set the font to fixed-width, and add spamblocks to any embedded email addresses.

Usage

1. Ensure your program emits help text with -h. (stdout or stderr is fine)
2. Copy the help_to_man script into your man/ directory, and re-name it your_program.X.sh where X is the manpage section you want (usually 1). [It's sufficiently short to be copied in its entirety every time.]
3. Edit it. Set the following:

    NAME			Your program's name
    BINARY			The binary path in the source tree (once built, it is called with -h)
    SYNOPSIS		A few words to summarise
    SECTION		The section to place it in. Usually 1. See "man man" for a list.
    SOURCE			The group of commands in which this belongs, if appropriate.
    DATE			Documentation date.
    SEE_ALSO		A list of other man pages, in the form:   "manpageA (1)"  "manpageB (1)"
    LEADING_SPACE		Prevent re-wrapping of the output of -h, if desired.
    LICENSE		License
    AUTHOR			Author/email.

4. In the makefile, run: bash man/your_program.X.sh (It must be bash, not sh.)
5. This generates the files: man/your_program.X.bz2 (preview with man) and man/your_program.X.html (preview with links).
6. Installation: manpages go in /usr/local/share/man/manX/
7. Full documentation is in the README.txt, Or read the source.
8. For a demonstration, just run "make".
9. This is Free Software released under the GNU GPL v3+. Please feel free to take it, modify it, package it etc.
10. Author: Richard Neill. Do ask if you would like further information and assistance.

Notes

This was originally written as part of my PhD Infrared Camera system. It should be possible to adapt it for much wider usage.

Download

Documents

Some selected files, from the tarball: Readme, the help_to_man script, and an example of the result.
README.txt
help_to_man.sh
demonstration.1

Navigation

Return to all programs, site home.