-This is help2man.info, produced by makeinfo version 5.1 from
+This is help2man.info, produced by makeinfo version 6.7 from
help2man.texi.
-This file documents the GNU 'help2man' command which produces simple
-manual pages from the '--help' and '--version' output of other commands.
+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, 2012, 2013 Free Software Foundation, Inc.
+2011, 2012, 2013, 2014, 2015, 2020, 2021 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
\1f
File: help2man.info, Node: Top, Next: Overview, Up: (dir)
-'help2man'
+‘help2man’
**********
-'help2man' produces simple manual pages from the '--help' and
-'--version' output of other commands.
+‘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.
+* 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'.
+* Makefile usage:: Using ‘help2man’ with ‘make’.
* Localised man pages:: Producing native language manual pages.
-* Example:: Example 'help2man' output.
+* Example:: Example ‘help2man’ output.
* Reports:: Reporting bugs or suggestions.
-* Availability:: Obtaining 'help2man'.
+* Availability:: Obtaining ‘help2man’.
\1f
File: help2man.info, Node: Overview, Next: Invoking help2man, Prev: Top, Up: Top
-1 Overview of 'help2man'
+1 Overview of ‘help2man’
************************
-'help2man' is a tool for automatically generating simple manual pages
+‘help2man’ is a tool for automatically generating simple manual pages
from program output.
Although manual pages are optional for GNU programs other projects,
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
+ Given a program which produces reasonably standard ‘--help’ and
+‘--version’ outputs, ‘help2man’ can re-arrange that output into
something which resembles a manual page.
\1f
File: help2man.info, Node: Invoking help2man, Next: --help recommendations, Prev: Overview, Up: Top
-2 How to Run 'help2man'
+2 How to Run ‘help2man’
***********************
-The format for running the 'help2man' program is:
+The format for running the ‘help2man’ program is:
help2man [OPTION]... EXECUTABLE
- 'help2man' supports the following options:
+ ‘help2man’ supports the following options:
-'-n STRING'
-'--name=STRING'
- Use STRING as the description for the 'NAME' paragraph of the
+‘-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'.
+ ‘manual page for PROGRAM VERSION’.
- This option overrides an include file '[name]' section (*note
+ This option overrides an include file ‘[name]’ section (*note
Including text::).
-'-s SECTION'
-'--section SECTION'
+‘-s SECTION’
+‘--section SECTION’
Use SECTION as the section for the man page. The default section
is 1.
-'-m MANUAL'
-'--manual=MANUAL'
+‘-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.
+ 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'
+‘-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
+‘-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'
+‘-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
+‘-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'.
+‘-o FILE’
+‘--output=FILE’
+ Send output to FILE rather than ‘stdout’.
-'-p TEXT'
-'--info-page=TEXT'
+‘-p TEXT’
+‘--info-page=TEXT’
Name of Texinfo manual.
-'-N'
-'--no-info'
- Suppress inclusion of a 'SEE ALSO' paragraph directing the reader
+‘-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').
+‘-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'
+‘--help’
+‘--version’
Show help or version information.
- By default 'help2man' passes the standard '--help' and '--version'
+ By default ‘help2man’ passes the standard ‘--help’ and ‘--version’
options to the executable although alternatives may be specified using:
-'-h OPTION'
-'--help-option=OPTION'
+‘-h OPTION’
+‘--help-option=OPTION’
Help option string.
-'-v OPTION'
-'--version-option=OPTION'
+‘-v OPTION’
+‘--version-option=OPTION’
Version option string.
-'--version-string=STRING'
+‘--version-string=STRING’
Version string.
-'--no-discard-stderr'
+‘--no-discard-stderr’
Include stderr when parsing option output.
\1f
File: help2man.info, Node: --help recommendations, Next: Including text, Prev: Invoking help2man, Up: Top
-3 '--help' Recommendations
+3 ‘--help’ Recommendations
**************************
-Here are some recommendations for what to include in your '--help'
-output. Including these gives 'help2man' the best chance at generating
+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 (standards)Command-Line Interfaces::, and *note (standards)Man
-Pages::, for the official GNU standards relating to '--help' and man
-pages.
+ See *note (standards)Command-Line Interfaces:: and *note
+(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
+ • 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):
or: cp [OPTION]... SOURCE... DIRECTORY
...
- Use 'argv[0]' for the program name in these synopses, just as it
+ 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'.
+ ‘--version’.
- * A very brief explanation of what the program does, including
- default and/or typical behaviour. For example, here is 'cp''s:
+ • 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
+ • 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
+ 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
+ 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:
-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',
+ 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
+ • 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
+ etc. For example, ‘cp’ discusses ‘VERSION_CONTROL’ and sparse
files.
- * A few examples of typical usage, at your discretion. One good
+ • 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
+ • 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
+ 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'.
+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 ‘Copyright’ will appear in the ‘COPYRIGHT’ section. Outside of
+these heuristics, a line consisting of ‘*Words*’ will start a new
+section, and ‘Words:’ a new sub-section.
\1f
File: help2man.info, Node: Including text, Next: Makefile usage, Prev: --help recommendations, Up: Top
*****************************************
Additional static text may be included in the generated manual page by
-using the '--include' and '--opt-include' options (*note Invoking
+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.
+we suggest to use the extension ‘.h2m’ for ‘help2man’ include files.
The format for files included with these option is simple:
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/'.
+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.)
+by the ‘i’, ‘s’ or ‘m’ modifiers (*note perlre(1): (*manpages*)perlre.)
- Lines before the first section or pattern which begin with '-' are
+ 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.
SYNOPSIS
DESCRIPTION
OPTIONS
+ _other_
ENVIRONMENT
FILES
EXAMPLES
- _other_
AUTHOR
REPORTING BUGS
COPYRIGHT
SEE ALSO
- Any '[name]' or '[synopsis]' sections appearing in the include file
+ 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).
+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]', '[=section]' or '[>section]' to place
+by using the syntax ‘[<section]’, ‘[=section]’ or ‘[>section]’ to place
the additional text before, in place of, or after the default output
respectively.
\1f
File: help2man.info, Node: Makefile usage, Next: Localised man pages, Prev: Including text, Up: Top
-5 Using 'help2man' With 'make'
+5 Using ‘help2man’ With ‘make’
******************************
-A suggested use of 'help2man' in Makefiles is to have the manual page
+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.
+‘--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.
+‘help2man’ installed.
- An example rule for the program 'prog' could be:
+ 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:
+ The value of ‘HELP2MAN’ may be set in ‘configure.in’ using either of:
- AM_MISSING_PROG(HELP2MAN, help2man, $missing_dir)
+ AM_MISSING_PROG(HELP2MAN, help2man)
- for 'automake', or something like:
+ for ‘automake’, or something like:
AC_PATH_PROG(HELP2MAN, help2man, false // No help2man //)
- for 'autoconf' alone.
+ for ‘autoconf’ alone.
\1f
File: help2man.info, Node: Localised man pages, Next: Example, Prev: Makefile usage, Up: Top
****************************************
Manual pages may be produced for any locale supported by both the
-program and 'help2man' with the '--locale' ('-L') option.
+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
+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
+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'.
+ 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:
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'.
+ 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
+ • 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::).
+ • 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::).
\1f
File: help2man.info, Node: Example, Next: Reports, Prev: Localised man pages, Up: Top
-7 Example 'help2man' Output
+7 Example ‘help2man’ Output
***************************
-Given a hypothetical program 'foo' which produces the following output:
+Given a hypothetical program ‘foo’ which produces the following output:
$ foo --version
GNU foo 1.1
Report bugs to <bug-gnu-utils@gnu.org>.
- 'help2man' will produce 'nroff' input for a manual page which will be
+ ‘help2man’ will produce ‘nroff’ input for a manual page which will be
formatted something like this:
FOO(1) User Commands FOO(1)
Report bugs to <bug-gnu-utils@gnu.org>.
COPYRIGHT
- Copyright (C) 2011 Free Software Foundation, Inc.
+ 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.
\1f
File: help2man.info, Node: Availability, Prev: Reports, Up: Top
-9 Obtaining 'help2man'
+9 Obtaining ‘help2man’
**********************
The latest version of this distribution is available online from GNU
\1f
Tag Table:
-Node: Top\7f1141
-Node: Overview\7f1906
-Node: Invoking help2man\7f2603
-Node: --help recommendations\7f5158
-Node: Including text\7f8524
-Node: Makefile usage\7f10460
-Node: Localised man pages\7f11391
-Node: Example\7f13227
-Node: Reports\7f15832
-Node: Availability\7f16286
+Node: Top\7f1177
+Node: Overview\7f1984
+Node: Invoking help2man\7f2701
+Node: --help recommendations\7f5460
+Node: Including text\7f9336
+Node: Makefile usage\7f11338
+Node: Localised man pages\7f12299
+Node: Example\7f14203
+Node: Reports\7f16823
+Node: Availability\7f17277
\1f
End Tag Table
+
+\1f
+Local Variables:
+coding: utf-8
+End:
projects / platform / upstream / help2man.git / blobdiff