Commit d482c65e d482c65ebc371b07d64450d169b513d389185d0d by Sergey Poznyakoff

Add new file

1 parent 75072662
@c This is part of the GNU Mailutils manual.
@c Copyright (C) 1999,2000,2001,2002,2003,2004,2005,2006,2007,2008
@c Free Software Foundation, Inc.
@c See file mailutils.texi for copying conditions.
@comment *******************************************************************
@node Usage Vars
@appendix Configuring Help Summary
Running @command{@var{prog} --help} displays the short usage summary
for @var{prog} utility (@pxref{Common Options}). This summary is
organized by @dfn{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 @kbd{sieve --help} output:
@verbatim
-c, --compile-only Compile script and exit
-d, --debug[=FLAGS] Debug flags
-e, --email=ADDRESS Override user email address
@end verbatim
@vrindex ARGP_HELP_FMT, environment variable
The exact visual representation of the help output is configurable via
@env{ARGP_HELP_FMT} environment variable. The value of this variable
is a comma-separated list of @dfn{format variable} assignments. There
are two kinds of format variables. An @dfn{offset variable} keeps the
offset of some part of help output text from the leftmost column on
the screen. A @dfn{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:
@table @asis
@item Offset assignment
The assignment to an offset variable has the following syntax:
@smallexample
@var{variable}=@var{value}
@end smallexample
@noindent
where @var{variable} is the variable name, and @var{value} is a
numeric value to be assigned to the variable.
@item Boolean assignment
To assign @code{true} value to a variable, simply put this variable name. To
assign @code{false} value, prefix the variable name with @samp{no-}. For
example:
@smallexample
@group
# Assign @code{true} value:
dup-args
# Assign @code{false} value:
no-dup-args
@end group
@end smallexample
@end table
Following variables are declared:
@deftypevr {Help Output} boolean dup-args
If true, arguments for an option are shown with both short and long
options, even when a given option has both forms, for example:
@smallexample
-e ADDRESS, --email=ADDRESS Override user email address
@end smallexample
If false, then if an option has both short and long forms, the
argument is only shown with the long one, for example:
@smallexample
-e, --email=ADDRESS Override user email address
@end smallexample
@noindent
and a message indicating that the argument is applicable to both
forms is printed below the options. This message can be disabled
using @code{dup-args-note} (see below).
The default is false.
@end deftypevr
@deftypevr {Help Output} boolean dup-args-note
If this variable is true, which is the default, the following notice
is displayed at the end of the help output:
@quotation
Mandatory or optional arguments to long options are also mandatory or
optional for any corresponding short options.
@end quotation
Setting @code{no-dup-args-note} inhibits this message. Normally, only
one of variables @code{dup-args} or @code{dup-args-note} should be set.
@end deftypevr
@deftypevr {Help Output} offset short-opt-col
Column in which short options start. Default is 2.
@smallexample
@group
$ @kbd{sieve --help|grep ADDRESS}
-e, --email=ADDRESS Override user email address
$ @kbd{ARGP_HELP_FMT=short-opt-col=6 sieve --help|grep ARCHIVE}
-e, --email=ADDRESS Override user email address
@end group
@end smallexample
@end deftypevr
@deftypevr {Help Output} offset long-opt-col
Column in which long options start. Default is 6. For example:
@smallexample
@group
$ @kbd{sieve --help|grep ADDRESS}
-e, --email=ADDRESS Override user email address
$ @kbd{ARGP_HELP_FMT=long-opt-col=16 sieve --help|grep ADDRESS}
-e, --email=ADDRESS Override user email address
@end group
@end smallexample
@end deftypevr
@deftypevr {Help Output} offset doc-opt-col
Column in which @dfn{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 @command{folder --help}:
@verbatim
Usage: folder [OPTION...] [action] [msg]
GNU MH folder
Actions are:
--list List the contents of the folder stack
...
@end verbatim
@noindent
the string @samp{Actions are:} is a doc option. Thus, if you set
@kbd{ARGP_HELP_FMT=doc-opt-col=6} the above part of the help output
will look as follows:
@verbatim
Usage: folder [OPTION...] [action] [msg]
GNU MH folder
Actions are:
--list List the contents of the folder stack
...
@end verbatim
@end deftypevr
@deftypevr {Help Output} offset opt-doc-col
Column in which option description starts. Default is 29.
@smallexample
@group
$ @kbd{sieve --help|grep ADDRESS}
-e, --email=ADDRESS Override user email address
$ @kbd{ARGP_HELP_FMT=opt-doc-col=19 sieve --help|grep ADDRESS}
-e, --email=ADDRESS Override user email address
$ @kbd{ARGP_HELP_FMT=opt-doc-col=9 sieve --help|grep -i ADDRESS}
-e, --email=ADDRESS
Override user email address
@end group
@end smallexample
@noindent
Notice, that the description starts on a separate line if
@code{opt-doc-col} value is too small.
@end deftypevr
@deftypevr {Help Output} offset header-col
Column in which @dfn{group headers} are printed. A group header is a
descriptive text preceding an option group. For example, in the
following text:
@verbatim
Sieve options
-I, --includedir=DIR Append directory DIR to the
list of include directories
@end verbatim
@noindent
the text @samp{Sieve options} is a group header.
The default value is 1.
@end deftypevr
@deftypevr {Help Output} offset usage-indent
Indentation of wrapped usage lines. Affects @option{--usage}
output. Default is 12.
@end deftypevr
@deftypevr {Help Output} offset rmargin
Right margin of the text output. Used for wrapping.
@end deftypevr