help2man produces simple manual pages from the ‘--help’ and ‘--version’ output of other commands.
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.
The format for running the help2man program is:
help2man [option]... executable
help2man supports the following options:
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).
By default help2man passes the standard ‘--help’ and ‘--version’ options to the executable although alternatives may be specified using:
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.
Usage: cp [OPTION]... SOURCE DEST or: cp [OPTION]... SOURCE... DIRECTORY ...
argv for the program name in these synopses, just as it
is, with no directory stripping. This is in contrast to the canonical
(constant) name of the program which is used in --version.
Copy SOURCE to DEST, or multiple SOURCE(s) to DIRECTORY.
Here again is an (edited) excerpt from cp, showing a short option with an equivalent long option, a long option only, and a short option only:
-a, --archive same as -dpR --backup[=CONTROL] make a backup of each ... -b like --backup but ...
For programs that take many options, it may be desirable to split the option list into sections such as `Global', `Output control', or whatever makes sense in the particular case. It is usually best to alphabetise (by short option name first, then long) within each section, or the entire list if there are no sections.
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
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.
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
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.
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.
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’.
gettext, if a more specific match were available it would also have been re-mapped.
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 <firstname.lastname@example.org>.
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@example.com>. 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)
If you find problems or have suggestions about this program or manual, please report them to firstname.lastname@example.org.
Note to translators: Translations are handled though the Translation Project see http://translationproject.org/html/translators.html for details.
The latest version of this distribution is available online from GNU mirrors:
If automatic redirection fails, the list of mirrors is at:
Or if need be you can use the main GNU ftp server:
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.