help2man

Overview
Invoking help2man
Including text
Example
Downloading help2man

Overview

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.

Invoking 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 @samp{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.

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

-N

--no-info

Suppress inclusion of a SEE ALSO paragraph directing the reader to the Texinfo documentation.

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

Including text

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

Example

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

Downloading help2man

help2man can be found on http://ftp.gnu.org/gnu/help2man/ or one of the mirrors.

Return to GNU's home page.

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.

Verbatim copying and distribution of this entire article is permitted in any medium, provided this notice is preserved.