1 This is help2man.info, produced by makeinfo version 5.2 from
4 This file documents the GNU ‘help2man’ command which produces simple
5 manual pages from the ‘--help’ and ‘--version’ output of other commands.
7 Copyright (C) 1999, 2000, 2001, 2002, 2003, 2004, 2005, 2009, 2010,
8 2011, 2012, 2013, 2014 Free Software Foundation, Inc.
10 Permission is granted to make and distribute verbatim copies of this
11 manual provided the copyright notice and this permission notice are
12 preserved on all copies.
14 Permission is granted to copy and distribute modified versions of
15 this manual under the conditions for verbatim copying, provided that the
16 entire resulting derived work is distributed under the terms of a
17 permission notice identical to this one.
19 Permission is granted to copy and distribute translations of this
20 manual into another language, under the above conditions for modified
21 versions, except that this permission notice may be stated in a
22 translation approved by the Foundation.
23 INFO-DIR-SECTION Software development
25 * help2man: (help2man). Automatic manual page generation.
29 File: help2man.info, Node: Top, Next: Overview, Up: (dir)
34 ‘help2man’ produces simple manual pages from the ‘--help’ and
35 ‘--version’ output of other commands.
39 * Overview:: Overview of ‘help2man’.
40 * Invoking help2man:: How to run ‘help2man’.
41 * --help recommendations:: Recommended formatting for –help output.
42 * Including text:: Including additional text in the output.
43 * Makefile usage:: Using ‘help2man’ with ‘make’.
44 * Localised man pages:: Producing native language manual pages.
45 * Example:: Example ‘help2man’ output.
46 * Reports:: Reporting bugs or suggestions.
47 * Availability:: Obtaining ‘help2man’.
50 File: help2man.info, Node: Overview, Next: Invoking help2man, Prev: Top, Up: Top
52 1 Overview of ‘help2man’
53 ************************
55 ‘help2man’ is a tool for automatically generating simple manual pages
58 Although manual pages are optional for GNU programs other projects,
59 such as Debian require them (*note (standards)Man Pages::)
61 This program is intended to provide an easy way for software authors
62 to include a manual page in their distribution without having to
63 maintain that document.
65 Given a program which produces reasonably standard ‘--help’ and
66 ‘--version’ outputs, ‘help2man’ can re-arrange that output into
67 something which resembles a manual page.
70 File: help2man.info, Node: Invoking help2man, Next: --help recommendations, Prev: Overview, Up: Top
72 2 How to Run ‘help2man’
73 ***********************
75 The format for running the ‘help2man’ program is:
77 help2man [OPTION]… EXECUTABLE
79 ‘help2man’ supports the following options:
83 Use STRING as the description for the ‘NAME’ paragraph of the
86 By default (for want of anything better) this paragraph contains
87 ‘manual page for PROGRAM VERSION’.
89 This option overrides an include file ‘[name]’ section (*note
94 Use SECTION as the section for the man page. The default section
99 Set the name of the manual section to SECTION, used as a centred
100 heading for the manual page. By default ‘User Commands’ is used
101 for pages in section 1, ‘Games’ for section 6 and ‘System
102 Administration Utilities’ for sections 8 and 1M.
106 The program source is used as a page footer, and often contains the
107 name of the organisation or a suite of which the program is part.
108 By default the value is the package name and version.
112 Select output locale (default ‘C’). Both the program and
113 ‘help2man’ must support the given LOCALE (*note Localised man
118 Include material from FILE (*note Including text::).
122 A variant of ‘--include’ for use in Makefile pattern rules which
123 does not require FILE to exist.
127 Send output to FILE rather than ‘stdout’.
131 Name of Texinfo manual.
135 Suppress inclusion of a ‘SEE ALSO’ paragraph directing the reader
136 to the Texinfo documentation.
140 Drop ‘lt-’ prefix from instances of the program name in the
141 synopsis (‘libtool’ creates wrapper scripts in the build directory
142 which invoke ‘foo’ as ‘.libs/lt-foo’).
146 Show help or version information.
148 By default ‘help2man’ passes the standard ‘--help’ and ‘--version’
149 options to the executable although alternatives may be specified using:
152 ‘--help-option=OPTION’
156 ‘--version-option=OPTION’
157 Version option string.
159 ‘--version-string=STRING’
162 ‘--no-discard-stderr’
163 Include stderr when parsing option output.
166 File: help2man.info, Node: --help recommendations, Next: Including text, Prev: Invoking help2man, Up: Top
168 3 ‘--help’ Recommendations
169 **************************
171 Here are some recommendations for what to include in your ‘--help’
172 output. Including these gives ‘help2man’ the best chance at generating
173 a respectable man page, as well as benefitting users directly.
175 See *note (standards)Command-Line Interfaces:: and *note
176 (standards)Man Pages::, for the official GNU standards relating to
177 ‘--help’ and man pages.
179 • A synopsis of how to invoke the program. If different usages of
180 the program have different invocations, then list them all. For
181 example (edited for brevity):
183 Usage: cp [OPTION]... SOURCE DEST
184 or: cp [OPTION]... SOURCE... DIRECTORY
187 Use ‘argv[0]’ for the program name in these synopses, just as it
188 is, with no directory stripping. This is in contrast to the
189 canonical (constant) name of the program which is used in
192 • A very brief explanation of what the program does, including
193 default and/or typical behaviour. For example, here is ‘cp’’s:
195 Copy SOURCE to DEST, or multiple SOURCE(s) to DIRECTORY.
197 • A list of options, indented to column 2. If the program supports
198 one-character options, put those first, then the equivalent long
199 option (if any). If the option takes an argument, include that
200 too, giving it a meaningful name. Align the descriptions in a
201 convenient column, if desired. Note that to be correctly
202 recognised by ‘help2man’ the description must be separated from the
203 options by at least two spaces and descriptions continued on
204 subsequent lines must start at the same column.
206 Here again is an (edited) excerpt from ‘cp’, showing a short option
207 with an equivalent long option, a long option only, and a short
210 -a, --archive same as -dpR
211 --backup[=CONTROL] make a backup of each ...
212 -b like --backup but ...
214 For programs that take many options, it may be desirable to split
215 the option list into sections such as ‘Global’, ‘Output control’,
216 or whatever makes sense in the particular case. It is usually best
217 to alphabetise (by short option name first, then long) within each
218 section, or the entire list if there are no sections.
220 • Any useful additional information about program behaviour, such as
221 influential environment variables, further explanation of options,
222 etc. For example, ‘cp’ discusses ‘VERSION_CONTROL’ and sparse
225 • A few examples of typical usage, at your discretion. One good
226 example is usually worth a thousand words of description, so this
227 is highly recommended.
229 • In closing, a line stating how to email bug reports. Typically,
230 MAILING-ADDRESS will be ‘bug-PROGRAM@gnu.org’; please use this form
231 for GNU programs whenever possible. It’s also good to mention the
232 home page of the program, other mailing lists, etc.
234 The ‘argp’ and ‘popt’ programming interfaces let you specify option
235 descriptions for ‘--help’ in the same structure as the rest of the
236 option definition; you may wish to consider using these routines for
237 option parsing instead of ‘getopt’.
239 By default ‘help2man’ has some heuristics for identifying manual page
240 sections: a line consisting of ‘Options:’ for example will cause the
241 following text to appear in the ‘OPTIONS’ section, and a line beginning
242 with ‘Copyright’ will appear in the ‘COPYRIGHT’ section. Outside of
243 these heuristics, a line consisting of ‘*Words*’ will start a new
244 section, and ‘Words:’ a new sub-section.
247 File: help2man.info, Node: Including text, Next: Makefile usage, Prev: --help recommendations, Up: Top
249 4 Including Additional Text in the Output
250 *****************************************
252 Additional static text may be included in the generated manual page by
253 using the ‘--include’ and ‘--opt-include’ options (*note Invoking
254 help2man::). While these files can be named anything, for consistency
255 we suggest to use the extension ‘.h2m’ for ‘help2man’ include files.
257 The format for files included with these option is simple:
265 Blocks of verbatim *roff text are inserted into the output either at
266 the start of the given ‘[section]’ (case insensitive), or after a
267 paragraph matching ‘/pattern/’.
269 Patterns use the Perl regular expression syntax and may be followed
270 by the ‘i’, ‘s’ or ‘m’ modifiers (*note perlre(1): (*manpages*)perlre.)
272 Lines before the first section or pattern which begin with ‘-’ are
273 processed as options. Anything else is silently ignored and may be used
274 for comments, RCS keywords and the like.
276 The section output order (for those included) is:
291 Any ‘[name]’ or ‘[synopsis]’ sections appearing in the include file
292 will replace what would have automatically been produced (although you
293 can still override the former with ‘--name’ if required).
295 Other sections are prepended to the automatically produced output for
296 the standard sections given above, or included at _other_ (above) in the
297 order they were encountered in the include file.
299 Placement of the text within the section may be explicitly requested
300 by using the syntax ‘[<section]’, ‘[=section]’ or ‘[>section]’ to place
301 the additional text before, in place of, or after the default output
305 File: help2man.info, Node: Makefile usage, Next: Localised man pages, Prev: Including text, Up: Top
307 5 Using ‘help2man’ With ‘make’
308 ******************************
310 A suggested use of ‘help2man’ in Makefiles is to have the manual page
311 depend not on the binary, but on the source file(s) in which the
312 ‘--help’ and ‘--version’ output are defined.
314 This usage allows a manual page to be generated by the maintainer and
315 included in the distribution without requiring the end-user to have
316 ‘help2man’ installed.
318 An example rule for the program ‘prog’ could be:
320 prog.1: $(srcdir)/main.c
321 -$(HELP2MAN) --output=$@ --name='an example program' ./prog
323 The value of ‘HELP2MAN’ may be set in ‘configure.in’ using either of:
325 AM_MISSING_PROG(HELP2MAN, help2man)
327 for ‘automake’, or something like:
329 AC_PATH_PROG(HELP2MAN, help2man, false // No help2man //)
331 for ‘autoconf’ alone.
334 File: help2man.info, Node: Localised man pages, Next: Example, Prev: Makefile usage, Up: Top
336 6 Producing Native Language Manual Pages
337 ****************************************
339 Manual pages may be produced for any locale supported by both the
340 program and ‘help2man’ with the ‘--locale’ (‘-L’) option.
342 help2man -L fr_FR@euro -o cp.fr.1 cp
344 See <http://translationproject.org/domain/help2man.html> for the
345 languages currently supported by ‘help2man’, and *note Reports:: for how
346 to submit other translations.
348 6.1 Changing the Location of Message Catalogs
349 =============================================
351 When creating localised manual pages from a program’s build directory it
352 is probable that the translations installed in the standard location
353 will not be (if installed at all) correct for the version of the program
356 A preloadable library is provided with ‘help2man’ which will
357 intercept ‘bindtextdomain’ calls configuring the location of message
358 catalogs for the domain given by ‘$TEXTDOMAIN’ and override the location
359 to the path given by ‘$LOCALEDIR’.
363 mkdir -p tmp/fr/LC_MESSAGES
364 cp po/fr.gmo tmp/fr/LC_MESSAGES/PROG.mo
365 LD_PRELOAD="/usr/lib/help2man/bindtextdomain.so" \
368 help2man -L fr_FR@euro -i PROG.fr.h2m -o PROG.fr.1 PROG
371 will cause PROG to load the message catalog from ‘tmp’ rather than
375 • The generalisation of ‘fr_FR@euro’ to ‘fr’ in the example above is
376 done by ‘gettext’, if a more specific match were available it would
377 also have been re-mapped.
379 • This preload has only been tested against ‘eglibc’ 2.11.2 and
380 ‘gettext’ 0.18.1.1 on a GNU/Linux system; let me know if it does
381 (or doesn’t) work for you (*note Reports::).
384 File: help2man.info, Node: Example, Next: Reports, Prev: Localised man pages, Up: Top
386 7 Example ‘help2man’ Output
387 ***************************
389 Given a hypothetical program ‘foo’ which produces the following output:
394 Copyright (C) 2011 Free Software Foundation, Inc.
395 This is free software; see the source for copying conditions. There is NO
396 warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
398 Written by A. Programmer.
400 GNU `foo' does nothing interesting except serve as an example for
403 Usage: foo [OPTION]...
406 -a, --option an option
407 -b, --another-option[=VALUE]
410 --help display this help and exit
411 --version output version information and exit
415 foo --option the same thing, giving `--option'
417 Report bugs to <bug-gnu-utils@gnu.org>.
419 ‘help2man’ will produce ‘nroff’ input for a manual page which will be
420 formatted something like this:
422 FOO(1) User Commands FOO(1)
426 foo - manual page for foo 1.1
432 GNU `foo' does nothing interesting except serve as an example for
439 -b, --another-option[=VALUE]
442 --help display this help and exit
445 output version information and exit
451 the same thing, giving `--option'
454 Written by A. Programmer.
457 Report bugs to <bug-gnu-utils@gnu.org>.
460 Copyright © 2011 Free Software Foundation, Inc.
461 This is free software; see the source for copying conditions.
462 There is NO warranty; not even for MERCHANTABILITY or FITNESS FOR A
466 The full documentation for foo is maintained as a Texinfo manual.
467 If the info and foo programs are properly installed at your site,
472 should give you access to the complete manual.
475 foo 1.1 May 2011 FOO(1)
478 File: help2man.info, Node: Reports, Next: Availability, Prev: Example, Up: Top
480 8 Reporting Bugs or Suggestions
481 *******************************
483 If you find problems or have suggestions about this program or manual,
484 please report them to <bug-help2man@gnu.org>.
486 Note to translators: Translations are handled though the Translation
487 Project (http://translationproject.org/) see
488 <http://translationproject.org/html/translators.html> for details.
491 File: help2man.info, Node: Availability, Prev: Reports, Up: Top
493 9 Obtaining ‘help2man’
494 **********************
496 The latest version of this distribution is available online from GNU
499 <http://ftpmirror.gnu.org/help2man/>
501 If automatic redirection fails, the list of mirrors is at:
503 <http://www.gnu.org/order/ftp.html>
505 Or if need be you can use the main GNU ftp server:
506 <http://ftp.gnu.org/gnu/help2man/>
512 Node: Overview
\7f1966
513 Node: Invoking help2man
\7f2683
514 Node: --help recommendations
\7f5442
515 Node: Including text
\7f9318
516 Node: Makefile usage
\7f11320
517 Node: Localised man pages
\7f12281
518 Node: Example
\7f14185
519 Node: Reports
\7f16805
520 Node: Availability
\7f17259