help2man

Generate a man page for an executable

$ help2man [executable]

$ help2man [executable] [[-n|--name]] [name]

$ help2man [executable] [[-s|--section]] [section]

$ help2man [executable] [[-o|--output]] [path/to/file]

$ help2man --help

help2man [OPTIONS] PROGRAM_NAME [PROGRAM_ARGUMENTS]

Example:
help2man -o mytool.1 ./mytool
This creates mytool.1 by running ./mytool and parsing its default help output.

-o FILE, --output=FILE
    Write the generated man page to FILE instead of standard output.

-n NAME, --name=NAME
    Override the program name used in the man page title.

-s SECTION, --section=SECTION
    Specify the manual section number (e.g., 1 for executables, 3 for library functions). Defaults to 1.

-m TEXT, --manual=TEXT
    Set the text for the manual header/footer line (e.g., 'GNU Tools').

-p TEXT, --pagemargin=TEXT
    Set the text for the page margin line.

-L LOCALE, --locale=LOCALE
    Set the locale for output message parsing.

-i FILE, --include=FILE
    Include content from FILE verbatim into the man page (e.g., for AUTHORS, BUGS sections).

-I FILE, --exclude=FILE
    Exclude options listed in FILE from the generated man page.

--source=TEXT
    Set the source of the man page (e.g., 'GNU Coreutils').

--date=DATE
    Set the date of the man page. Uses current date by default.

--help-option=STRING
    Use STRING instead of --help to get the program's help output.

--usage-option=STRING
    Use STRING instead of --usage to get the program's usage output.

--version-option=STRING
    Use STRING instead of --version to get the program's version output.

--no-info
    Suppress the standard 'Report bugs to...' information.

--warnings
    Enable warning messages during parsing regarding potential issues.

help2man is a valuable utility for automating the creation of basic manual pages from a program's standard output, typically its --help or --usage message.

It parses this output to extract key information such as the program name, synopsis, description, and command-line options. By generating man pages directly from the help text, help2man helps developers maintain consistency between their program's runtime help and its official documentation, reducing the effort required to keep both synchronized. It is commonly used in Makefiles during software compilation to ensure that an up-to-date man page is always available alongside the executable. While effective for simple cases, its reliance on the help message's format means that complex or non-standard help outputs might require manual intervention or produce less ideal results.

help2man's effectiveness is directly tied to the consistency and clarity of the target program's --help output.

Programs with non-standard, very brief, or overly complex help messages may result in incomplete or poorly formatted man pages. It is not designed to replace comprehensive, hand-written man pages that provide detailed examples, usage scenarios, or intricate explanations of options beyond what's available in a typical --help output. It's a tool for quick generation, not deep documentation.

help2man is most effectively utilized within software build processes, such as Makefiles. A common pattern is to include a target that runs help2man against the newly compiled executable. This ensures that every build automatically generates or updates the man page, keeping it current with any changes in the program's --help output, thus streamlining documentation maintenance.

While help2man excels at parsing help messages, it also provides mechanisms to include additional, custom content. The -i or --include option allows developers to inject pre-written text files (e.g., containing AUTHORS, BUGS, COPYRIGHT, or EXAMPLES sections) directly into the generated man page. This flexibility allows for richer documentation beyond what's present in a typical --help output.

help2man was first developed by Carlo Wood in 1995. Its primary motivation was to automate and simplify the process of generating man pages for GNU tools, which often follow a consistent format for their --help output. Over the years, it has been maintained and integrated into various open-source projects' build systems, becoming a standard utility for maintaining synchronized command-line help and manual documentation with minimal developer effort.

man(1), groff(1), pandoc(1), txt2man(1)