Configuring Help Summary (GNU tar 1.35)

## Appendix C Configuring Help Summary

Running `tar --help` displays the short `tar` option summary (see GNU `tar` documentation). 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 `tar --help` output:

     Main operation mode:

      -A, --catenate, --concatenate   append tar files to an archive
      -c, --create               create a new archive
      -d, --diff, --compare      find differences between archive and
                                 file system
          --delete               delete from the archive

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:

        -f ARCHIVE, --file=ARCHIVE use archive file or device ARCHIVE

  If false, then if an option has both short and long forms, the argument is only shown with the long one, for example:

        -f, --file=ARCHIVE         use archive file or device ARCHIVE

  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.

      $ tar --help|grep ARCHIVE
        -f, --file=ARCHIVE   use archive file or device ARCHIVE
      $ ARGP_HELP_FMT=short-opt-col=6 tar --help|grep ARCHIVE
            -f, --file=ARCHIVE   use archive file or device ARCHIVE

Help Output: `offset` long-opt-col ¶

  Column in which long options start. Default is 6. For example:

      $ tar --help|grep ARCHIVE
        -f, --file=ARCHIVE   use archive file or device ARCHIVE
      $ ARGP_HELP_FMT=long-opt-col=16 tar --help|grep ARCHIVE
        -f,           --file=ARCHIVE   use archive file or device ARCHIVE

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 description of `--format` option:

        -H, --format=FORMAT        create archive of the given format.

       FORMAT is one of the following:

          gnu                      GNU tar 1.13.x format
          oldgnu                   GNU format as per tar <= 1.12
          pax                      POSIX 1003.1-2001 (pax) format
          posix                    same as pax
          ustar                    POSIX 1003.1-1988 (ustar) format
          v7                       old V7 tar format

  the format names are doc options. Thus, if you set `ARGP_HELP_FMT=doc-opt-col=6` the above part of the help output will look as follows:

        -H, --format=FORMAT        create archive of the given format.

       FORMAT is one of the following:

              gnu                      GNU tar 1.13.x format
              oldgnu                   GNU format as per tar <= 1.12
              pax                      POSIX 1003.1-2001 (pax) format
              posix                    same as pax
              ustar                    POSIX 1003.1-1988 (ustar) format
              v7                       old V7 tar format

Help Output: `offset` opt-doc-col ¶

  Column in which option description starts. Default is 29.

      $ tar --help|grep ARCHIVE
        -f, --file=ARCHIVE         use archive file or device ARCHIVE
      $ ARGP_HELP_FMT=opt-doc-col=19 tar --help|grep ARCHIVE
        -f, --file=ARCHIVE   use archive file or device ARCHIVE
      $ ARGP_HELP_FMT=opt-doc-col=9 tar --help|grep ARCHIVE
        -f, --file=ARCHIVE
                 use archive file or device ARCHIVE

  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:

       Main operation mode:

        -A, --catenate, --concatenate   append tar files to
                                   an archive
        -c, --create               create a new archive

  ‘`Main operation mode:`’ is the 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.