@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