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).

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.

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.

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.

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 <bug-gnu-utils@gnu.org>.

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