English [en]

Thanks to your support, 2015 marks 30 years of the FSF! In the next 30 years, we want to do even more to defend computer user rights. To kick off in that direction, we're setting our highest-ever fundraising goal of $525,000 by January 31st. Read more.

$525K
64% (340K)
Count me in

`help2man' Reference Manual

help2man

help2man produces simple manual pages from the ‘--help’ and ‘--version’ output of other commands.

Overview of help2man

help2man is a tool for automatically generating simple manual pages from program output.

Although manual pages are optional for GNU programs other projects, such as Debian require them (see Man Pages)

This program is intended to provide an easy way for software authors to include a manual page in their distribution without having to maintain that document.

Given a program which produces reasonably standard ‘--help’ and ‘--version’ outputs, help2man can re-arrange that output into something which resembles a manual page.

How to Run help2man

The format for running the help2man program is:

     help2man [option]... executable

help2man supports the following options:

‘-n string’
‘--name=string’
Use string as the description for the ‘NAME’ paragraph of the manual page.

By default (for want of anything better) this paragraph contains ‘manual page for program version’.

This option overrides an include file ‘[name]’ section (see Including text).

‘-s section’
‘--section section’
Use section as the section for the man page. The default section is 1.
‘-m manual’
‘--manual=manual’
Set the name of the manual section to section, used as a centred heading for the manual page. By default ‘User Commands’ is used for pages in section 1, ‘Games’ for section 6 and ‘System Administration Utilities’ for sections 8 and 1M.
‘-S source’
‘--source=source’
The program source is used as a page footer, and often contains the name of the organisation or a suite of which the program is part. By default the value is the package name and version.
‘-L locale’
‘--locale=locale’
Select output locale (default ‘C’). Both the program and help2man must support the given locale (see Localised man pages).
‘-i file’
‘--include=file’
Include material from file (see Including text).
‘-I file’
‘--opt-include=file’
A variant of ‘--include’ for use in Makefile pattern rules which does not require file to exist.
‘-o file’
‘--output=file’
Send output to file rather than stdout.
‘-p text’
‘--info-page=text’
Name of Texinfo manual.
‘-N’
‘--no-info’
Suppress inclusion of a ‘SEE ALSO’ paragraph directing the reader to the Texinfo documentation.
‘-l’
‘--libtool’
Drop lt- prefix from instances of the program name in the synopsis (libtool creates wrapper scripts in the build directory which invoke foo as .libs/lt-foo).
‘--help’
‘--version’
Show help or version information.

By default help2man passes the standard ‘--help’ and ‘--version’ options to the executable although alternatives may be specified using:

‘-h option’
‘--help-option=option’
Help option string.
‘-v option’
‘--version-option=option’
Version option string.
‘--version-string=string’
Version string.
‘--no-discard-stderr’
Include stderr when parsing option output.

--help Recommendations

Here are some recommendations for what to include in your --help output. Including these gives help2man the best chance at generating a respectable man page, as well as benefitting users directly.

See Command-Line Interfaces, and Man Pages, for the official GNU standards relating to --help and man pages.

The argp and popt programming interfaces let you specify option descriptions for --help in the same structure as the rest of the option definition; you may wish to consider using these routines for option parsing instead of getopt.

Including Additional Text in the Output

Additional static text may be included in the generated manual page by using the ‘--include’ and ‘--opt-include’ options (see Invoking help2man). While these files can be named anything, for consistency we suggest to use the extension .h2m for help2man include files.

The format for files included with these option is simple:

     [section]
     text
     
     /pattern/
     text

Blocks of verbatim *roff text are inserted into the output either at the start of the given ‘[section]’ (case insensitive), or after a paragraph matching ‘/pattern/’.

Patterns use the Perl regular expression syntax and may be followed by the ‘i’, ‘s’ or ‘m’ modifiers (see perlre(1))

Lines before the first section or pattern which begin with ‘-’ are processed as options. Anything else is silently ignored and may be used for comments, RCS keywords and the like.

The section output order (for those included) is:

     NAME
     SYNOPSIS
     DESCRIPTION
     OPTIONS
     ENVIRONMENT
     FILES
     EXAMPLES
     other
     AUTHOR
     REPORTING BUGS
     COPYRIGHT
     SEE ALSO

Any ‘[name]’ or ‘[synopsis]’ sections appearing in the include file will replace what would have automatically been produced (although you can still override the former with ‘--name’ if required).

Other sections are prepended to the automatically produced output for the standard sections given above, or included at other (above) in the order they were encountered in the include file.

Using help2man With make

A suggested use of help2man in Makefiles is to have the manual page depend not on the binary, but on the source file(s) in which the ‘--help’ and ‘--version’ output are defined.

This usage allows a manual page to be generated by the maintainer and included in the distribution without requiring the end-user to have help2man installed.

An example rule for the program prog could be:

     prog.1: $(srcdir)/main.c
             -$(HELP2MAN) --output=$@ --name='an example program' ./prog

The value of HELP2MAN may be set in configure.in using either of:

     AM_MISSING_PROG(HELP2MAN, help2man, $missing_dir)

for automake, or something like:

     AC_PATH_PROG(HELP2MAN, help2man, false // No help2man //)

for autoconf alone.

Producing Native Language Manual Pages

Manual pages may be produced for any locale supported by both the program and help2man with the ‘--locale’ (‘-L’) option.

     help2man -L fr_FR@euro -o cp.fr.1 cp

See http://translationproject.org/domain/help2man.html for the languages currently supported by help2man, and see Reports for how to submit other translations.

Changing the Location of Message Catalogs

When creating localised manual pages from a program's build directory it is probable that the translations installed in the standard location will not be (if installed at all) correct for the version of the program being built.

A preloadable library is provided with help2man which will intercept bindtextdomain calls configuring the location of message catalogs for the domain given by $TEXTDOMAIN and override the location to the path given by $LOCALEDIR.

So for example:

     mkdir -p tmp/fr/LC_MESSAGES
     cp po/fr.gmo tmp/fr/LC_MESSAGES/prog.mo
     LD_PRELOAD="/usr/lib/help2man/bindtextdomain.so" \
       LOCALEDIR=tmp \
       TEXTDOMAIN=prog \
       help2man -L fr_FR@euro -i prog.fr.h2m -o prog.fr.1 prog
     rm -rf tmp

will cause prog to load the message catalog from ‘tmp’ rather than ‘/usr/share/locale’.

Notes:

Example help2man Output

Given a hypothetical program foo which produces the following output:

     $ foo --version
     GNU foo 1.1
     
     Copyright (C) 2011 Free Software Foundation, Inc.
     This is free software; see the source for copying conditions.  There is NO
     warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
     
     Written by A. Programmer.
     $ foo --help
     GNU `foo' does nothing interesting except serve as an example for
     `help2man'.
     
     Usage: foo [OPTION]...
     
     Options:
       -a, --option      an option
       -b, --another-option[=VALUE]
                         another option
     
           --help        display this help and exit
           --version     output version information and exit
     
     Examples:
       foo               do nothing
       foo --option      the same thing, giving `--option'
     
     Report bugs to <[email protected]>.

help2man will produce nroff input for a manual page which will be formatted something like this:

     FOO(1)                         User Commands                        FOO(1)
     
     
     NAME
            foo - manual page for foo 1.1
     
     SYNOPSIS
            foo [OPTION]...
     
     DESCRIPTION
            GNU  `foo'  does nothing interesting except serve as an example for
            `help2man'.
     
     OPTIONS
            -a, --option
                   an option
     
            -b, --another-option[=VALUE]
                   another option
     
            --help display this help and exit
     
            --version
                   output version information and exit
     
     EXAMPLES
            foo    do nothing
     
            foo --option
                   the same thing, giving `--option'
     
     AUTHOR
            Written by A. Programmer.
     
     REPORTING BUGS
            Report bugs to <[email protected]>.
     
     COPYRIGHT
            Copyright © 2011 Free Software Foundation, Inc.
            This is free software;  see  the  source  for  copying  conditions.
            There is NO warranty; not even for MERCHANTABILITY or FITNESS FOR A
            PARTICULAR PURPOSE.
     
     SEE ALSO
            The full documentation for foo is maintained as a  Texinfo  manual.
            If  the  info and foo programs are properly installed at your site,
            the command
     
                   info foo
     
            should give you access to the complete manual.
     
     
     foo 1.1                          May 2011                           FOO(1)

Reporting Bugs or Suggestions

If you find problems or have suggestions about this program or manual, please report them to [email protected].

Note to translators: Translations are handled though the Translation Project see http://translationproject.org/html/translators.html for details.

Obtaining help2man

The latest version of this distribution is available online from GNU mirrors:

     http://ftpmirror.gnu.org/help2man/

If automatic redirection fails, the list of mirrors is at:

     http://www.gnu.org/order/ftp.html

Or if need be you can use the main GNU ftp server:

     http://ftp.gnu.org/gnu/help2man/

Table of Contents

[FSF logo] “Our mission is to preserve, protect and promote the freedom to use, study, copy, modify, and redistribute computer software, and to defend the rights of Free Software users.”

The Free Software Foundation is the principal organizational sponsor of the GNU Operating System. Support GNU and the FSF by buying manuals and gear, joining the FSF as an associate member, or making a donation, either directly to the FSF or via Flattr.

back to top