GNU Mailutils |
|
General-Purpose Mail Package |
Official GNU Software |
Running prog --help
displays the short usage summary
for prog utility (see Common Options). This summary is
organized by groups of semantically close options. The options
within each group are printed in the following order: a short option,
eventually followed by a list of corresponding long option names,
followed by a short description of the option. For example, here is an
excerpt from the actual sieve --help output:
-c, --compile-only Compile script and exit -d, --debug[=FLAGS] Debug flags -e, --email=ADDRESS Override user email address
The exact visual representation of the help output is configurable via
ARGP_HELP_FMT
environment variable. The value of this variable
is a comma-separated list of format variable assignments. There
are two kinds of format variables. An offset variable keeps the
offset of some part of help output text from the leftmost column on
the screen. A boolean variable is a flag that toggles some
output feature on or off. Depending on the type of the corresponding
variable, there are two kinds of assignments:
The assignment to an offset variable has the following syntax:
variable=value
where variable is the variable name, and value is a numeric value to be assigned to the variable.
To assign true
value to a variable, simply put this variable name. To
assign false
value, prefix the variable name with ‘no-’. For
example:
# Assigntrue
value: dup-args # Assignfalse
value: no-dup-args
Following variables are declared:
If true, arguments for an option are shown with both short and long options, even when a given option has both forms, for example:
-e ADDRESS, --email=ADDRESS Override user email address
If false, then if an option has both short and long forms, the argument is only shown with the long one, for example:
-e, --email=ADDRESS Override user email address
and a message indicating that the argument is applicable to both
forms is printed below the options. This message can be disabled
using dup-args-note
(see below).
The default is false.
If this variable is true, which is the default, the following notice is displayed at the end of the help output:
Mandatory or optional arguments to long options are also mandatory or optional for any corresponding short options.
Setting no-dup-args-note
inhibits this message. Normally, only
one of variables dup-args
or dup-args-note
should be set.
Column in which short options start. Default is 2.
$ sieve --help|grep ADDRESS -e, --email=ADDRESS Override user email address $ ARGP_HELP_FMT=short-opt-col=6 sieve --help|grep ARCHIVE -e, --email=ADDRESS Override user email address
Column in which long options start. Default is 6. For example:
$ sieve --help|grep ADDRESS -e, --email=ADDRESS Override user email address $ ARGP_HELP_FMT=long-opt-col=16 sieve --help|grep ADDRESS -e, --email=ADDRESS Override user email address
Column in which doc options start. A doc option isn’t actually
an option, but rather an arbitrary piece of documentation that is
displayed in much the same manner as the options. For example, in
the output of folder --help
:
Usage: folder [OPTION...] [action] [msg] GNU MH folder Actions are: --list List the contents of the folder stack ...
the string ‘Actions are:’ is a doc option. Thus, if you set ARGP_HELP_FMT=doc-opt-col=6 the above part of the help output will look as follows:
Usage: folder [OPTION...] [action] [msg] GNU MH folder Actions are: --list List the contents of the folder stack ...
Column in which option description starts. Default is 29.
$ sieve --help|grep ADDRESS -e, --email=ADDRESS Override user email address $ ARGP_HELP_FMT=opt-doc-col=19 sieve --help|grep ADDRESS -e, --email=ADDRESS Override user email address $ ARGP_HELP_FMT=opt-doc-col=9 sieve --help|grep -i ADDRESS -e, --email=ADDRESS Override user email address
Notice, that the description starts on a separate line if
opt-doc-col
value is too small.
Column in which group headers are printed. A group header is a descriptive text preceding an option group. For example, in the following text:
Sieve options -I, --includedir=DIR Append directory DIR to the list of include directories
the text ‘Sieve options’ is a group header.
The default value is 1.
Indentation of wrapped usage lines. Affects --usage output. Default is 12.
Right margin of the text output. Used for wrapping.
This document was generated on January 2, 2022 using makeinfo.
Verbatim copying and distribution of this entire article is permitted in any medium, provided this notice is preserved.