help2man is a tool for automatically generating simple manual pages from program output.
It 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 resonably standard --help and --version outputs, help2man will attempt to 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).
stdout
.
help2man
passes the standard --help and
--version options to the executable although alternatives may
be specified using:
Additional static text may be included in the generated manual page by using the --include and --opt-include options (see Invoking help2man).
The format for files included with these option is simple:
[section] text /pattern/ textBlocks 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 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 is:
NAME SYNOPSIS DESCRIPTION OPTIONS EXAMPLES other AUTHOR REPORTING BUGS COPYRIGHT SEE ALSOAny [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.
Given a hypothetical program foo which produces the following output:
$ foo --version GNU foo 1.1 Copyright (C) 1999 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 for a manual page which will be formatted something like this:
FOO(1) FSF 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 <bug-gnu-utils@gnu.org>. COPYRIGHT Copyright (C) 1999 Free Software Foundation, Inc. This is free software; see the source for copying condi- tions. 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. GNU foo 1.1 December 1999 1
help2man can be found on http://ftp.gnu.org/gnu/help2man/ or one of the mirrors.
Please send FSF & GNU inquiries & questions to gnu@gnu.org. There are also other ways to contact the FSF.
Please send comments on these web pages to webmasters@gnu.org, send other questions to gnu@gnu.org.
Copyright (C) 1999 Free Software Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111, USA
Verbatim copying and distribution of this entire article is permitted in any medium, provided this notice is preserved.
Updated: 03 Dec 2001 bod