kmx git

This is help2man.info, produced by makeinfo version 4.13 from
help2man.texi.

INFO-DIR-SECTION Software development
START-INFO-DIR-ENTRY
* help2man: (help2man).      Automatic manual page generation.
END-INFO-DIR-ENTRY

   This file documents the GNU `help2man' command which produces simple
manual pages from the `--help' and `--version' output of other commands.

   Copyright (C) 1999, 2000, 2001, 2002, 2003, 2004, 2005, 2009, 2010,
2011 Free Software Foundation, Inc.

   Permission is granted to make and distribute verbatim copies of this
manual provided the copyright notice and this permission notice are
preserved on all copies.

   Permission is granted to copy and distribute modified versions of
this manual under the conditions for verbatim copying, provided that
the entire resulting derived work is distributed under the terms of a
permission notice identical to this one.

   Permission is granted to copy and distribute translations of this
manual into another language, under the above conditions for modified
versions, except that this permission notice may be stated in a
translation approved by the Foundation.


File: help2man.info,  Node: Top,  Next: Overview,  Up: (dir)

`help2man'
**********

`help2man' produces simple manual pages from the `--help' and
`--version' output of other commands.

* Menu:

* Overview::                    Overview of `help2man'.
* Invoking help2man::           How to run `help2man'.
* --help recommendations::      Recommended formatting for --help output.
* Including text::              Including additional text in the output.
* Makefile usage::              Using `help2man' with `make'.
* Localised man pages::         Producing native language manual pages.
* Example::                     Example `help2man' output.
* Reports::                     Reporting bugs or suggestions.
* Availability::                Obtaining `help2man'.


File: help2man.info,  Node: Overview,  Next: Invoking help2man,  Prev: Top,  Up: Top

1 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 (*note Man Pages: (standards)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.


File: help2man.info,  Node: Invoking help2man,  Next: --help recommendations,  Prev: Overview,  Up: Top

2 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 (*note
     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 (*note Localised man
     pages::).

`-i FILE'
`--include=FILE'
     Include material from FILE (*note 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.


File: help2man.info,  Node: --help recommendations,  Next: Including text,  Prev: Invoking help2man,  Up: Top

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

   *Note Command-Line Interfaces: (standards)Command-Line Interfaces,
and *note Man Pages: (standards)Man Pages, 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'.


File: help2man.info,  Node: Including text,  Next: Makefile usage,  Prev: --help recommendations,  Up: Top

4 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 (*note 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 (*note perlre(1): (*manpages*)perlre.)

   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.


File: help2man.info,  Node: Makefile usage,  Next: Localised man pages,  Prev: Including text,  Up: Top

5 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, $missing_dir)

   for `automake', or something like:

     AC_PATH_PROG(HELP2MAN, help2man, false // No help2man //)

   for `autoconf' alone.


File: help2man.info,  Node: Localised man pages,  Next: Example,  Prev: Makefile usage,  Up: Top

6 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 `http://translationproject.org/domain/help2man.html' for the
languages currently supported by `help2man', and *note Reports:: for
how to submit other translations.

6.1 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 (*note Reports::).


File: help2man.info,  Node: Example,  Next: Reports,  Prev: Localised man pages,  Up: Top

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

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

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

     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)


File: help2man.info,  Node: Reports,  Next: Availability,  Prev: Example,  Up: Top

8 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 (http://translationproject.org/) see
`http://translationproject.org/html/translators.html' for details.


File: help2man.info,  Node: Availability,  Prev: Reports,  Up: Top

9 Obtaining `help2man'
**********************

The latest version of this distribution is available online from GNU
mirrors:

     `http://ftpmirror.gnu.org/help2man/'

   If automatic redirection fails, the list of mirrors is at:

     `http://www.gnu.org/order/ftp.html'

   Or if need be you can use the main GNU ftp server:
     `http://ftp.gnu.org/gnu/help2man/'



Tag Table:
Node: Top1134
Node: Overview1900
Node: Invoking help2man2607
Node: --help recommendations5165
Node: Including text8564
Node: Makefile usage10272
Node: Localised man pages11203
Node: Example13039
Node: Reports15644
Node: Availability16098

End Tag Table
gnu/help2man/help2man.info

Commit

help2man.info
