help2man - GNU Project - Free Software Foundation

help2man - GNU Project - Free Software Foundation
Skip to main text
JOIN THE FSF
GNU
Operating System
Supported by the
Free Software Foundation
Site navigation
Skip
ABOUT GNU
PHILOSOPHY
LICENSES
EDUCATION
SOFTWARE
DISTROS
DOCS
MALWARE
HELP GNU
AUDIO & VIDEO
GNU ART
FUN
GNU'S WHO?
SOFTWARE DIRECTORY
HARDWARE
help2man
Reference Manual
Table of Contents
Overview of
help2man
How to Run
help2man
--help
Recommendations
Including Additional Text in the Output
Using
help2man
With
make
Producing Native Language Manual Pages
Changing the Location of Message Catalogs
Example
help2man
Output
Reporting Bugs or Suggestions
Obtaining
help2man
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
in
GNU
Coding Standards
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 ‘
’). 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
in
GNU Coding Standards
and
Man Pages
in
GNU Coding Standards
, for the
official GNU standards relating to
--help
and man pages.
A synopsis of how to invoke the program. If different usages of the
program have different invocations, then list them all. For example
(edited for brevity):
Usage: cp [OPTION]... SOURCE DEST
or: cp [OPTION]... SOURCE... DIRECTORY
Use
argv[0]
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
A very brief explanation of what the program does, including default
and/or typical behaviour. For example, here is
cp
’s:
Copy SOURCE to DEST, or multiple SOURCE(s) to DIRECTORY.
A list of options, indented to column 2. If the program supports
one-character options, put those first, then the equivalent long option
(if any). If the option takes an argument, include that too, giving it
a meaningful name. Align the descriptions in a convenient column, if
desired. Note that to be correctly recognised by
help2man
the description must be separated from the options by at least two
spaces and descriptions continued on subsequent lines must start at
the same column.
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.
Any useful additional information about program behaviour, such as
influential environment variables, further explanation of options, etc.
For example,
cp
discusses
VERSION_CONTROL
and sparse
files.
A few examples of typical usage, at your discretion. One good example
is usually worth a thousand words of description, so this is
highly recommended.
In closing, a line stating how to email bug reports. Typically,
mailing-address
will be ‘
bug-
program
@gnu.org
’; please
use this form for GNU programs whenever possible. It’s also good to
mention the home page of the program, other mailing lists, etc.
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
By default
help2man
has some heuristics for identifying
manual page sections: a line consisting of ‘
Options:
’ for example
will cause the following text to appear in the
OPTIONS
section,
and a line beginning with ‘
’ will appear in the
section. Outside of these heuristics, a line
consisting of ‘
*Words*
’ will start a new section, and
Words:
’ a new sub-section.
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 ‘
’, ‘
’ or ‘
’ modifiers (see
perlre(1)
in
The
perlre(1)
manual page
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
other
ENVIRONMENT
FILES
EXAMPLES
AUTHOR
REPORTING BUGS
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.
Placement of the text within the section may be explicitly requested
by using the syntax ‘
[’, ‘
[=section]
’ or
[>section]
’ to place the additional text before, in place of, or
after the default output respectively.
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)
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
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:
The generalisation of ‘
fr_FR@euro
’ to ‘
fr
’ in the example
above is done by
gettext
, if a more specific match were available
it would also have been re-mapped.
This preload has only been tested against
eglibc
2.11.2 and
gettext
0.18.1.1 on a GNU/Linux system; let me know if it
does (or doesn’t) work for you (see
Reports
).
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 .
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 .
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
bug-help2man@gnu.org
Note to translators: Translations are handled though the
Translation Project
see
for details.
Obtaining
help2man
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 (FSF) is a nonprofit with a worldwide
mission to promote computer user freedom. We defend the rights of all
software users.”
JOIN
DONATE
SHOP
Please send general FSF & GNU inquiries to

There are also
other ways to contact
the FSF. Broken links and other corrections or suggestions can be sent
to

Please see the
Translations
README
for information on coordinating and contributing translations
of this article.
Copyright © 2020 Free Software Foundation, Inc.
This page is licensed under a
Creative
Commons Attribution-NoDerivatives 4.0 International License
Copyright Infringement Notification
Updated:
$Date: 2020/07/02 21:59:26 $