Next: , Previous: Date Input Formats, Up: Top

Appendix C Configuring Help Summary

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:

Offset assignment
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.

Boolean assignment
To assign true value to a variable, simply put this variable name. To assign false value, prefix the variable name with ‘no-’. For example: 
          # Assign true value:
          dup-args
          # Assign false value:
          no-dup-args

Following variables are declared:

— 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: 

            -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.

— 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:

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.

— Help Output: offset short-opt-col

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
— Help Output: offset long-opt-col

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
— Help Output: offset doc-opt-col

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
       ...

— Help Output: offset opt-doc-col

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.

— Help Output: offset header-col

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.

— Help Output: offset usage-indent

Indentation of wrapped usage lines. Affects --usage output. Default is 12.

— Help Output: offset rmargin

Right margin of the text output. Used for wrapping.