tar: Configuring Help Summary
1
1 Appendix C Configuring Help Summary
1 ***********************************
1
11 Running 'tar --help' displays the short 'tar' option summary (⇒
help). This summary is organized by "groups" of semantically close
1 options. The options within each group are printed in the following
1 order: a short option, eventually followed by a list of corresponding
1 long option names, followed by a short description of the option. For
1 example, here is an excerpt from the actual 'tar --help' output:
1
1 Main operation mode:
1
1 -A, --catenate, --concatenate append tar files to an archive
1 -c, --create create a new archive
1 -d, --diff, --compare find differences between archive and
1 file system
1 --delete delete from the archive
1
1 The exact visual representation of the help output is configurable
1 via 'ARGP_HELP_FMT' environment variable. The value of this variable is
1 a comma-separated list of "format variable" assignments. There are two
1 kinds of format variables. An "offset variable" keeps the offset of
1 some part of help output text from the leftmost column on the screen. A
1 "boolean" variable is a flag that toggles some output feature on or off.
1 Depending on the type of the corresponding variable, there are two kinds
1 of assignments:
1
1 Offset assignment
1
1 The assignment to an offset variable has the following syntax:
1
1 VARIABLE=VALUE
1
1 where VARIABLE is the variable name, and VALUE is a numeric value
1 to be assigned to the variable.
1
1 Boolean assignment
1
1 To assign 'true' value to a variable, simply put this variable
1 name. To assign 'false' value, prefix the variable name with
1 'no-'. For example:
1
1 # Assign true value:
1 dup-args
1 # Assign false value:
1 no-dup-args
1
1 Following variables are declared:
1
1 -- Help Output: boolean dup-args
1 If true, arguments for an option are shown with both short and long
1 options, even when a given option has both forms, for example:
1
1 -f ARCHIVE, --file=ARCHIVE use archive file or device ARCHIVE
1
1 If false, then if an option has both short and long forms, the
1 argument is only shown with the long one, for example:
1
1 -f, --file=ARCHIVE use archive file or device ARCHIVE
1
1 and a message indicating that the argument is applicable to both
1 forms is printed below the options. This message can be disabled
1 using 'dup-args-note' (see below).
1
1 The default is false.
1
1 -- Help Output: boolean dup-args-note
1 If this variable is true, which is the default, the following
1 notice is displayed at the end of the help output:
1
1 Mandatory or optional arguments to long options are also
1 mandatory or optional for any corresponding short options.
1
1 Setting 'no-dup-args-note' inhibits this message. Normally, only
1 one of variables 'dup-args' or 'dup-args-note' should be set.
1
1 -- Help Output: offset short-opt-col
1 Column in which short options start. Default is 2.
1
1 $ tar --help|grep ARCHIVE
1 -f, --file=ARCHIVE use archive file or device ARCHIVE
1 $ ARGP_HELP_FMT=short-opt-col=6 tar --help|grep ARCHIVE
1 -f, --file=ARCHIVE use archive file or device ARCHIVE
1
1 -- Help Output: offset long-opt-col
1 Column in which long options start. Default is 6. For example:
1
1 $ tar --help|grep ARCHIVE
1 -f, --file=ARCHIVE use archive file or device ARCHIVE
1 $ ARGP_HELP_FMT=long-opt-col=16 tar --help|grep ARCHIVE
1 -f, --file=ARCHIVE use archive file or device ARCHIVE
1
1 -- Help Output: offset doc-opt-col
1 Column in which "doc options" start. A doc option isn't actually
1 an option, but rather an arbitrary piece of documentation that is
1 displayed in much the same manner as the options. For example, in
1 the description of '--format' option:
1
1 -H, --format=FORMAT create archive of the given format.
1
1 FORMAT is one of the following:
1
1 gnu GNU tar 1.13.x format
1 oldgnu GNU format as per tar <= 1.12
1 pax POSIX 1003.1-2001 (pax) format
1 posix same as pax
1 ustar POSIX 1003.1-1988 (ustar) format
1 v7 old V7 tar format
1
1 the format names are doc options. Thus, if you set
1 'ARGP_HELP_FMT=doc-opt-col=6' the above part of the help output
1 will look as follows:
1
1 -H, --format=FORMAT create archive of the given format.
1
1 FORMAT is one of the following:
1
1 gnu GNU tar 1.13.x format
1 oldgnu GNU format as per tar <= 1.12
1 pax POSIX 1003.1-2001 (pax) format
1 posix same as pax
1 ustar POSIX 1003.1-1988 (ustar) format
1 v7 old V7 tar format
1
1 -- Help Output: offset opt-doc-col
1 Column in which option description starts. Default is 29.
1
1 $ tar --help|grep ARCHIVE
1 -f, --file=ARCHIVE use archive file or device ARCHIVE
1 $ ARGP_HELP_FMT=opt-doc-col=19 tar --help|grep ARCHIVE
1 -f, --file=ARCHIVE use archive file or device ARCHIVE
1 $ ARGP_HELP_FMT=opt-doc-col=9 tar --help|grep ARCHIVE
1 -f, --file=ARCHIVE
1 use archive file or device ARCHIVE
1
1 Notice, that the description starts on a separate line if
1 'opt-doc-col' value is too small.
1
1 -- Help Output: offset header-col
1 Column in which "group headers" are printed. A group header is a
1 descriptive text preceding an option group. For example, in the
1 following text:
1
1 Main operation mode:
1
1 -A, --catenate, --concatenate append tar files to
1 an archive
1 -c, --create create a new archive
1 'Main operation mode:' is the group header.
1
1 The default value is 1.
1
1 -- Help Output: offset usage-indent
1 Indentation of wrapped usage lines. Affects '--usage' output.
1 Default is 12.
1
1 -- Help Output: offset rmargin
1 Right margin of the text output. Used for wrapping.
1