(tar.info.gz) Configuring Help Summary
Info Catalog
(tar.info.gz) Changes
(tar.info.gz) Top
(tar.info.gz) Fixing Snapshot Files
Appendix B Configuring Help Summary
***********************************
Running 'tar --help' displays the short 'tar' option summary (
help). 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.
Info Catalog
(tar.info.gz) Changes
(tar.info.gz) Top
(tar.info.gz) Fixing Snapshot Files
automatically generated by
info2html