Package: tar
Version: 1.35+dfsg-3
Severity: minor
Tags: patch
Dear Maintainer,
* What led up to the situation?
Checking for defects with
[test-][g|n]roff -mandoc -t -K utf8 -ww -b -z <man page>
[test-groff is a script in the repository for "groff"]
* What was the outcome of this action?
an.tmac:<stdin>:231: warning: cannot nest .TP or .TQ inside .TP; supply a tag
* What outcome did you expect instead?
No output (warnings).
-.-
Here are some notes and editorial fixes for the manual.
Notes and a patch are in the attachments.
-- System Information:
Debian Release: trixie/sid
APT prefers testing
APT policy: (500, 'testing')
Architecture: amd64 (x86_64)
Kernel: Linux 6.7.12-amd64 (SMP w/2 CPU threads; PREEMPT)
Locale: LANG=is_IS.iso88591, LC_CTYPE=is_IS.iso88591 (charmap=ISO-8859-1),
LANGUAGE not set
Shell: /bin/sh linked to /usr/bin/dash
Init: sysvinit (via /sbin/init)
Versions of packages tar depends on:
ii libacl1 2.3.2-2
ii libc6 2.38-11
ii libselinux1 3.5-2+b2
tar recommends no packages.
Versions of packages tar suggests:
ii bzip2 1.0.8-5.1
ii ncompress 5.0-2
pn tar-doc <none>
pn tar-scripts <none>
ii xz-utils 5.6.1+really5.4.5-1
-- no debconf information
Any program (person), that produces man pages, should check its content for
defects by using
groff -mandoc -t -ww -b -z [ -K utf8 | k ] <man page>
The same goes for man pages that are used as an input.
For a style guide use
mandoc -T lint
-.-
So any generator should check its products with the above mentioned
'groff' and additionally with 'nroff ...'.
This is just a simple quality control measure.
The generator may have to be corrected to get a better man page,
the source file may, and any additional file may.
-.-
The difference between the formatted outputs can be seen with:
nroff -man <file1> > <out1>
nroff -man <file2> > <out2>
diff -u <out1> <out2>
and for groff, using
"printf '%s\n%s\n' '.kern 0' '.ss 12 0' | groff -man -Z - "
instead of "nroff -man"
Add the option "-t", if the file contains a table.
Read the output of "diff -u" with "less -R" or similar.
-.-.
If "man" (man-db) is used to check the manual for warnings,
the following must be set:
The option "-warnings=w"
The environmental variable:
export MAN_KEEP_STDERR=yes (or any non-empty value)
or
(produce only warnings):
export MANROFFOPT="-ww -z"
export MAN_KEEP_STDERR=yes (or any non-empty value)
-.-.
Output from "mandoc -T lint tar.1": (possibly shortened list)
mandoc: tar.1:24:2: WARNING: skipping paragraph macro: sp after SS
mandoc: tar.1:39:2: WARNING: skipping paragraph macro: sp after SS
mandoc: tar.1:89:2: WARNING: skipping paragraph macro: PP empty
mandoc: tar.1:90:1: WARNING: skipping paragraph macro: sp after PP
mandoc: tar.1:230:2: WARNING: line scope broken: TP breaks TP
mandoc: tar.1:857:2: WARNING: empty block: RS
mandoc: tar.1:1252:2: WARNING: skipping paragraph macro: sp after SS
mandoc: tar.1:1268:2: WARNING: skipping paragraph macro: PP empty
mandoc: tar.1:1280:82: STYLE: input text line longer than 80 bytes: from their
disk coun...
-.-.
Change two HYPHEN-MINUSES (code 0x2D) to an em-dash (\(em),
if one is intended. An en-dash is usually surrounded by a space,
while an em-dash is used without spaces.
"man" (1 byte characters in input) transforms an en-dash (\(en) to one
HYPHEN-MINUS,
and an em-dash to two HYPHEN-MINUSES without considering the space
around it.
If "--" are two single "-" (end of options) then use "\-\-".
tar.1:155:tar --create --file etc.tar --verbose /etc
tar.1:159:tar --cre --file=etc.tar --verb /etc
tar.1:634:--file=remotehost:/dev/sr0
tar.1:647:--rsh-command=/usr/bin/ssh
tar.1:1147:Keywords applicable for \fBtar --create\fR:
tar.1:1183:Keywords applicable for \fBtar --extract\fR:
tar.1:1215:$ tar --warning=decompress-program -x -f archive.Z
-.-.
Change (or include a "FIXME" paragraph about) misused SI (metric)
numeric prefixes (or names) to the binary ones, like Ki (kibi), Mi
(mebi), Gi (gibi), or Ti (tebi), if indicated.
If the metric prefixes are correct, add the definitions or an
explanation to avoid misunderstanding.
751:suffix\fR, e.g. \fB\-\-record-size=10K\fR, for 10 Kilobytes. See the
1258: B Kilobytes \fISIZE\fR x 1024
1260: G Gigabytes \fISIZE\fR x 1024^3
1261: K Kilobytes \fISIZE\fR x 1024
1262: k Kilobytes \fISIZE\fR x 1024
1263: M Megabytes \fISIZE\fR x 1024^2
1265: T Terabytes \fISIZE\fR x 1024^4
-.-.
Mark a full stop (.) and the exclamation mark (!) with "\&",
if it does not mean an end of a sentence.
This is a preventive action,
the paragraph could be reshaped, e.g., after changes.
When typing, one does not always notice when the line wraps after the
period.
There are too many examples of input lines in manual pages,
that end with an abbreviation point.
This marking is robust, and independent of the position on the line.
It corresponds to "\ " in TeX, and to "@:" in Texinfo.
86:can be either a regular file or a device (e.g. a tape drive, hence the name
125:clustered together after a single dash, e.g. \fB\-vkp\fR. An option
127:the end of such a cluster, e.g. \fB\-vkpf a.tar\fR.
284:effect only if the archive is open for reading (e.g. with
450:Current blocking factor, i.e. number of 512-byte blocks in a record.
611:pattern, e.g. \fB\-\-xattrs\-exclude='user.*'\fR to include only
673:Current blocking factor, i.e. number of 512-byte blocks in a record.
751:suffix\fR, e.g. \fB\-\-record-size=10K\fR, for 10 Kilobytes. See the
867:order-sensitive, i.e. it affects all options that follow.
984:names separated by ASCII \fBLF\fR (i.e. one name per line). The
1007:command line, i.e. any names starting with a dash are treated as
1294:a compression option (e.g. \fB\-z\fR) was used and the external
-.-.
Change -- in x--y to \(em (em-dash), or, if an
option, to \-\-
155:tar --create --file etc.tar --verbose /etc
159:tar --cre --file=etc.tar --verb /etc
1147:Keywords applicable for \fBtar --create\fR:
1183:Keywords applicable for \fBtar --extract\fR:
1215:$ tar --warning=decompress-program -x -f archive.Z
-.-.
Change a HYPHEN-MINUS (code 0x2D) to a minus(-dash) (\-),
if it
is in front of a name for an option,
is a symbol for standard input,
is a single character used to indicate an option,
or is in the NAME section (man-pages(7)).
N.B. - (0x2D), processed as a UTF-8 file, is changed to a hyphen
(0x2010, groff \[u2010] or \[hy]) in the output.
134:tar -cvf etc.tar /etc
138:tar -c -v -f etc.tar /etc
155:tar --create --file etc.tar --verbose /etc
159:tar --cre --file=etc.tar --verb /etc
634:--file=remotehost:/dev/sr0
647:--rsh-command=/usr/bin/ssh
1147:Keywords applicable for \fBtar --create\fR:
1183:Keywords applicable for \fBtar --extract\fR:
1215:$ tar --warning=decompress-program -x -f archive.Z
-.-.
Find a repeated word
! 750 --> can
-.-.
Strings longer than 3/4 of a standard line length (80)
780
\fB\-\-pax\-option\fR=\fIkeyword\fR[[:]=\fIvalue\fR][,\fIkeyword\fR[[:]=\fIvalue\fR]]...
-.-.
Add a comma (or \&) after "e.g." and "i.e.", or use English words
(man-pages(7)).
Abbreviation points should be protected against being interpreted as
an end of sentence, if they are not, and that independent of the
current place on the line.
86:can be either a regular file or a device (e.g. a tape drive, hence the name
125:clustered together after a single dash, e.g. \fB\-vkp\fR. An option
127:the end of such a cluster, e.g. \fB\-vkpf a.tar\fR.
284:effect only if the archive is open for reading (e.g. with
450:Current blocking factor, i.e. number of 512-byte blocks in a record.
611:pattern, e.g. \fB\-\-xattrs\-exclude='user.*'\fR to include only
673:Current blocking factor, i.e. number of 512-byte blocks in a record.
751:suffix\fR, e.g. \fB\-\-record-size=10K\fR, for 10 Kilobytes. See the
867:order-sensitive, i.e. it affects all options that follow.
984:names separated by ASCII \fBLF\fR (i.e. one name per line). The
1007:command line, i.e. any names starting with a dash are treated as
1294:a compression option (e.g. \fB\-z\fR) was used and the external
-.-.
Wrong distance between sentences.
Separate the sentences and subordinate clauses; each begins on a new
line. See man-pages(7) ("Conventions for source file layout") and
"info groff" ("Input Conventions").
The best procedure is to always start a new sentence on a new line,
at least, if you are typing on a computer.
Remember coding: Only one command ("sentence") on each (logical) line.
E-mail: Easier to quote exactly the relevant lines.
Generally: Easier to edit the sentence.
Patches: Less unaffected text.
Search for two adjacent words is easier, when they belong to the same line,
and the same phrase.
The amount of space between sentences in the output can then be
controlled with the ".ss" request.
N.B
The number of lines affected can be too large to be in the patch.
86:can be either a regular file or a device (e.g. a tape drive, hence the name
125:clustered together after a single dash, e.g. \fB\-vkp\fR. An option
127:the end of such a cluster, e.g. \fB\-vkpf a.tar\fR.
284:effect only if the archive is open for reading (e.g. with
388:Type of the file. It is a single letter with the following meaning:
418:Time of last access. It is a decimal number, representing seconds
450:Current blocking factor, i.e. number of 512-byte blocks in a record.
611:pattern, e.g. \fB\-\-xattrs\-exclude='user.*'\fR to include only
673:Current blocking factor, i.e. number of 512-byte blocks in a record.
751:suffix\fR, e.g. \fB\-\-record-size=10K\fR, for 10 Kilobytes. See the
867:order-sensitive, i.e. it affects all options that follow.
984:names separated by ASCII \fBLF\fR (i.e. one name per line). The
1007:command line, i.e. any names starting with a dash are treated as
1178:Suppresses warnings about unreadable files or directories. This
1294:a compression option (e.g. \fB\-z\fR) was used and the external
-.-.
Split lines longer than 80 characters into two or more lines.
Appropriate break points are the end of a sentence and a subordinate
clause; after punctuation marks.
tar.1: line 40 length 114
\fBtar\fR {\fB\-\-catenate\fR|\fB\-\-concatenate\fR} [\fIOPTIONS\fR]
\fB\-\-file\fR \fIARCHIVE\fR \fIARCHIVE\fR...
tar.1: line 42 length 89
\fBtar\fR \fB\-\-create\fR [\fB\-\-file\fR \fIARCHIVE\fR] [\fIOPTIONS\fR]
[\fIFILE\fR...]
tar.1: line 44 length 107
\fBtar\fR {\fB\-\-diff\fR|\fB\-\-compare\fR} [\fB\-\-file\fR \fIARCHIVE\fR]
[\fIOPTIONS\fR] [\fIFILE\fR...]
tar.1: line 46 length 91
\fBtar\fR \fB\-\-delete\fR [\fB\-\-file\fR \fIARCHIVE\fR] [\fIOPTIONS\fR]
[\fIMEMBER\fR...]
tar.1: line 48 length 89
\fBtar\fR \fB\-\-append\fR [\fB\-\-file\fR \fIARCHIVE\fR] [\fIOPTIONS\fR]
[\fIFILE\fR...]
tar.1: line 50 length 89
\fBtar\fR \fB\-\-list\fR [\fB\-\-file\fR \fIARCHIVE\fR] [\fIOPTIONS\fR]
[\fIMEMBER\fR...]
tar.1: line 52 length 95
\fBtar\fR \fB\-\-test\-label\fR [\fB\-\-file\fR \fIARCHIVE\fR] [\fIOPTIONS\fR]
[\fILABEL\fR...]
tar.1: line 54 length 89
\fBtar\fR \fB\-\-update\fR [\fB\-\-file\fR \fIARCHIVE\fR] [\fIOPTIONS\fR]
[\fIFILE\fR...]
tar.1: line 56 length 108
\fBtar\fR {\fB\-\-extract\fR|\fB\-\-get\fR} [\fB\-\-file\fR \fIARCHIVE\fR]
[\fIOPTIONS\fR] [\fIMEMBER\fR...]
tar.1: line 660 length 92
\fB\-F\fR, \fB\-\-info\-script\fR=\fICOMMAND\fR,
\fB\-\-new\-volume\-script\fR=\fICOMMAND\fR
tar.1: line 780 length 88
\fB\-\-pax\-option\fR=\fIkeyword\fR[[:]=\fIvalue\fR][,\fIkeyword\fR[[:]=\fIvalue\fR]]...
tar.1: line 1280 length 82
from their disk counterparts. If \fBtar\fR was given one of the
\fB\-\-create\fR,
-.-.
Change a HYPHEN-MINUS (code 0x55, 2D) to a dash
(\-, minus) if it matches "[[:alph:]]-[[:alpha:]]" in the name of an
option).
Facilitates the copy and paste of an option in UTF-8 text.
Is not needed in ordinary words like "mother-in-law", that are not
copied and pasted to a command line (which needs ASCII code)
600:.B \-\-no-selinux
647:--rsh-command=/usr/bin/ssh
751:suffix\fR, e.g. \fB\-\-record-size=10K\fR, for 10 Kilobytes. See the
-.-
Output from "test-groff -b -mandoc -dAD=l -rF0 -rHY=0 -K utf8 -t -ww -z -K
utf8":
an.tmac:<stdin>:231: warning: cannot nest .TP or .TQ inside .TP; supply a tag
--- tar.1 2024-05-30 16:22:37.950249152 +0000
+++ tar.1.new 2024-05-30 18:45:39.823463611 +0000
@@ -21,7 +21,6 @@ tar \- an archiving utility
\fBtar\fR {\fBA\fR|\fBc\fR|\fBd\fR|\fBr\fR|\fBt\fR|\fBu\fR|\fBx\fR}\
[\fBGnSkUWOmpsMBiajJzZhPlRvwo\fR] [\fIARG\fR...]
.SS UNIX-style usage
-.sp
\fBtar\fR \fB\-A\fR [\fIOPTIONS\fR] \fB\-f\fR \fIARCHIVE\fR \fIARCHIVE\fR...
.sp
\fBtar\fR \fB\-c\fR [\fB\-f\fR \fIARCHIVE\fR] [\fIOPTIONS\fR] [\fIFILE\fR...]
@@ -36,24 +35,32 @@ tar \- an archiving utility
.sp
\fBtar\fR \fB\-x\fR [\fB\-f\fR \fIARCHIVE\fR] [\fIOPTIONS\fR] [\fIMEMBER\fR...]
.SS GNU-style usage
+\fBtar\fR {\fB\-\-catenate\fR|\fB\-\-concatenate\fR} [\fIOPTIONS\fR] \
+\fB\-\-file\fR \fIARCHIVE\fR \fIARCHIVE\fR...
.sp
-\fBtar\fR {\fB\-\-catenate\fR|\fB\-\-concatenate\fR} [\fIOPTIONS\fR]
\fB\-\-file\fR \fIARCHIVE\fR \fIARCHIVE\fR...
-.sp
-\fBtar\fR \fB\-\-create\fR [\fB\-\-file\fR \fIARCHIVE\fR] [\fIOPTIONS\fR]
[\fIFILE\fR...]
+\fBtar\fR \fB\-\-create\fR [\fB\-\-file\fR \fIARCHIVE\fR] [\fIOPTIONS\fR] \
+[\fIFILE\fR...]
.sp
-\fBtar\fR {\fB\-\-diff\fR|\fB\-\-compare\fR} [\fB\-\-file\fR \fIARCHIVE\fR]
[\fIOPTIONS\fR] [\fIFILE\fR...]
+\fBtar\fR {\fB\-\-diff\fR|\fB\-\-compare\fR} [\fB\-\-file\fR \fIARCHIVE\fR] \
+[\fIOPTIONS\fR] [\fIFILE\fR...]
.sp
-\fBtar\fR \fB\-\-delete\fR [\fB\-\-file\fR \fIARCHIVE\fR] [\fIOPTIONS\fR]
[\fIMEMBER\fR...]
+\fBtar\fR \fB\-\-delete\fR [\fB\-\-file\fR \fIARCHIVE\fR] [\fIOPTIONS\fR] \
+[\fIMEMBER\fR...]
.sp
-\fBtar\fR \fB\-\-append\fR [\fB\-\-file\fR \fIARCHIVE\fR] [\fIOPTIONS\fR]
[\fIFILE\fR...]
+\fBtar\fR \fB\-\-append\fR [\fB\-\-file\fR \fIARCHIVE\fR] [\fIOPTIONS\fR] \
+[\fIFILE\fR...]
.sp
-\fBtar\fR \fB\-\-list\fR [\fB\-\-file\fR \fIARCHIVE\fR] [\fIOPTIONS\fR]
[\fIMEMBER\fR...]
+\fBtar\fR \fB\-\-list\fR [\fB\-\-file\fR \fIARCHIVE\fR] [\fIOPTIONS\fR] \
+[\fIMEMBER\fR...]
.sp
-\fBtar\fR \fB\-\-test\-label\fR [\fB\-\-file\fR \fIARCHIVE\fR] [\fIOPTIONS\fR]
[\fILABEL\fR...]
+\fBtar\fR \fB\-\-test\-label\fR [\fB\-\-file\fR \fIARCHIVE\fR] \
+[\fIOPTIONS\fR] [\fILABEL\fR...]
.sp
-\fBtar\fR \fB\-\-update\fR [\fB\-\-file\fR \fIARCHIVE\fR] [\fIOPTIONS\fR]
[\fIFILE\fR...]
+\fBtar\fR \fB\-\-update\fR [\fB\-\-file\fR \fIARCHIVE\fR] [\fIOPTIONS\fR] \
+[\fIFILE\fR...]
.sp
-\fBtar\fR {\fB\-\-extract\fR|\fB\-\-get\fR} [\fB\-\-file\fR \fIARCHIVE\fR]
[\fIOPTIONS\fR] [\fIMEMBER\fR...]
+\fBtar\fR {\fB\-\-extract\fR|\fB\-\-get\fR} [\fB\-\-file\fR \fIARCHIVE\fR] \
+[\fIOPTIONS\fR] [\fIMEMBER\fR...]
.SH NOTE
This manpage is a short description of GNU \fBtar\fR. For a detailed
discussion, including examples and usage recommendations, refer to the
@@ -83,11 +90,10 @@ GNU
.B tar
is an archiving program designed to store multiple files in a single
file (an \fBarchive\fR), and to manipulate such archives. The archive
-can be either a regular file or a device (e.g. a tape drive, hence the name
+can be either a regular file or a device (e.g., a tape drive), hence the name
of the program, which stands for \fBt\fRape \fBar\fRchiver), which can
be located either on the local or on a remote machine.
-.PP
-
+.
.SS Option styles
Options to GNU \fBtar\fR can be given in three different styles.
In
@@ -122,20 +128,20 @@ argument must follow the option letter w
whitespace, as in \fB\-g/tmp/snar.db\fR.
.PP
Any number of options not taking arguments can be
-clustered together after a single dash, e.g. \fB\-vkp\fR. An option
+clustered together after a single dash, e.g.\& \fB\-vkp\fR. An option
that takes an argument (whether mandatory or optional) can appear at
-the end of such a cluster, e.g. \fB\-vkpf a.tar\fR.
+the end of such a cluster, e.g.\& \fB\-vkpf a.tar\fR.
.PP
The example command above written in the
.B short-option style
could look like:
.PP
.EX
-tar -cvf etc.tar /etc
+tar \-cvf etc.tar /etc
.EE
or
.EX
-tar -c -v -f etc.tar /etc
+tar \-c \-v \-f etc.tar /etc
.EE
.PP
In
@@ -152,11 +158,11 @@ method.
Here are several ways of writing the example command in this style:
.PP
.EX
-tar --create --file etc.tar --verbose /etc
+tar \-\-create \-\-file etc.tar \-\-verbose /etc
.EE
or (abbreviating some options):
.EX
-tar --cre --file=etc.tar --verb /etc
+tar \-\-cre \-\-file=etc.tar \-\-verb /etc
.EE
.PP
The options in all three styles can be intermixed, although doing so
@@ -228,7 +234,6 @@ same name, corresponding to various vers
Extract files from an archive. Arguments are optional. When given,
they specify names of the archive members to be extracted.
.TP
-.TP
\fB\-\-show\-defaults\fR
Show built-in defaults for various \fBtar\fR options and exit.
.TP
@@ -254,7 +259,7 @@ dump and, consequently, must be dumped a
exist when creating an archive, it will be created and all files will
be added to the resulting archive (the \fBlevel 0\fR dump). To create
incremental archives of non-zero level \fBN\fR, you need a copy of the
-snapshot file created for level \fBN-1\fR, and use it as \fIFILE\fR.
+snapshot file created for level \fBN\-1\fR, and use it as \fIFILE\fR.
When listing or extracting, the actual content of \fIFILE\fR is not
inspected, it is needed only due to syntactical requirements. It is
@@ -281,7 +286,7 @@ the snapshot file before dumping, thereb
Assume the archive is seekable. Normally \fBtar\fR determines
automatically whether the archive can be seeked or not. This option
is intended for use in cases when such recognition fails. It takes
-effect only if the archive is open for reading (e.g. with
+effect only if the archive is open for reading (e.g., with
.B \-\-list
or
.B \-\-extract
@@ -385,7 +390,8 @@ supplied via the following environment v
.RS
.TP
.B TAR_FILETYPE
-Type of the file. It is a single letter with the following meaning:
+Type of the file.
+It is a single letter with the following meaning:
.sp
.nf
.ta 8n 20n
@@ -415,10 +421,11 @@ Name of the file owner.
Name of the file owner group.
.TP
.B TAR_ATIME
-Time of last access. It is a decimal number, representing seconds
-since the Epoch. If the archive provides times with nanosecond
-precision, the nanoseconds are appended to the timestamp after a
-decimal point.
+Time of last access.
+It is a decimal number,
+representing seconds since the Epoch.
+If the archive provides times with nanosecond precision,
+the nanoseconds are appended to the timestamp after a decimal point.
.TP
.B TAR_MTIME
Time of last modification.
@@ -447,7 +454,7 @@ GNU \fBtar\fR version number.
The name of the archive \fBtar\fR is processing.
.TP
.B TAR_BLOCKING_FACTOR
-Current blocking factor, i.e. number of 512-byte blocks in a record.
+Current blocking factor, i.e., number of 512-byte blocks in a record.
.TP
.B TAR_VOLUME
Ordinal number of the volume \fBtar\fR is processing (set if
@@ -597,7 +604,7 @@ Disable POSIX ACLs support.
.B \-\-selinux
Enable SELinux context support.
.TP
-.B \-\-no-selinux
+.B \-\-no\-selinux
Disable SELinux context support.
.TP
.B \-\-xattrs
@@ -608,7 +615,7 @@ Disable extended attributes support.
.TP
.BI \-\-xattrs\-exclude= PATTERN
Specify the exclude pattern for xattr keys. \fIPATTERN\fR is a globbing
-pattern, e.g. \fB\-\-xattrs\-exclude='user.*'\fR to include only
+pattern, e.g., \fB\-\-xattrs\-exclude='user.*'\fR to include only
attributes from the user namespace.
.TP
.BI \-\-xattrs\-include= PATTERN
@@ -631,7 +638,7 @@ name or IP address, and the part after i
pathname, e.g.:
.EX
---file=remotehost:/dev/sr0
+\-\-file=remotehost:/dev/sr0
.EE
An optional username can be prefixed to the hostname, placing a \fB@\fR
@@ -644,7 +651,7 @@ command. Nowadays it is common to use
instead. You can do so by giving the following command line option:
.EX
---rsh-command=/usr/bin/ssh
+\-\-rsh-command=/usr/bin/ssh
.EE
The remote machine should have the
@@ -657,7 +664,8 @@ option.
\fB\-\-force\-local\fR
Archive file is local even if it has a colon.
.TP
-\fB\-F\fR, \fB\-\-info\-script\fR=\fICOMMAND\fR,
\fB\-\-new\-volume\-script\fR=\fICOMMAND\fR
+\fB\-F\fR, \fB\-\-info\-script\fR=\fICOMMAND\fR, \
+\fB\-\-new\-volume\-script\fR=\fICOMMAND\fR
Run \fICOMMAND\fR at the end of each tape (implies \fB\-M\fR). The
command can include arguments. When started, it will inherit \fBtar\fR's
environment plus the following variables:
@@ -670,7 +678,7 @@ GNU \fBtar\fR version number.
The name of the archive \fBtar\fR is processing.
.TP
.B TAR_BLOCKING_FACTOR
-Current blocking factor, i.e. number of 512-byte blocks in a record.
+Current blocking factor, i.e., number of 512-byte blocks in a record.
.TP
.B TAR_VOLUME
Ordinal number of the volume \fBtar\fR is processing (set if
@@ -747,8 +755,8 @@ reading archives created with the \fB\-A
.TP
\fB\-\-record\-size\fR=\fINUMBER\fR
Set record size. \fINUMBER\fR is the number of bytes per record. It
-must be multiple of \fB512\fR. It can can be suffixed with a \fBsize
-suffix\fR, e.g. \fB\-\-record-size=10K\fR, for 10 Kilobytes. See the
+must be multiple of \fB512\fR. It can be suffixed with a \fBsize
+suffix\fR, e.g., \fB\-\-record\-size=10K\fR, for 10 kibibytes. See the
subsection
.BR "Size suffixes" ,
for a list of valid suffixes.
@@ -777,7 +785,8 @@ Old V7 tar format.
\fB\-\-old\-archive\fR, \fB\-\-portability\fR
Same as \fB\-\-format=v7\fR.
.TP
-\fB\-\-pax\-option\fR=\fIkeyword\fR[[:]=\fIvalue\fR][,\fIkeyword\fR[[:]=\fIvalue\fR]]...
+\fB\-\-pax\-option\fR=\fIkeyword\fR[[:]=\fIvalue\fR][,\
+\fIkeyword\fR[[:]=\fIvalue\fR]]...
Control pax keywords when creating \fBPAX\fR archives (\fB\-H
pax\fR). This option is equivalent to the \fB\-o\fR option of the
.BR pax (1)
@@ -854,9 +863,7 @@ Make numbered backups if numbered backup
.TP
.BR never ", " simple
Always make simple backups
-.RS
-.RE
-
+.LP
If \fICONTROL\fR is not given, the value is taken from the
.B VERSION_CONTROL
environment variable. If it is not set, \fBexisting\fR is assumed.
@@ -864,7 +871,7 @@ environment variable. If it is not set,
.TP
\fB\-C\fR, \fB\-\-directory\fR=\fIDIR\fR
Change to \fIDIR\fR before performing any operations. This option is
-order-sensitive, i.e. it affects all options that follow.
+order-sensitive, i.e., it affects all options that follow.
.TP
\fB\-\-exclude\fR=\fIPATTERN\fR
Exclude files matching \fIPATTERN\fR, a
@@ -981,7 +988,7 @@ unless overridden by environment variabl
Get names to extract or create from \fIFILE\fR.
Unless specified otherwise, the \fIFILE\fR must contain a list of
-names separated by ASCII \fBLF\fR (i.e. one name per line). The
+names separated by ASCII \fBLF\fR (i.e., one name per line). The
names read are handled the same way as command line arguments. They
undergo quote removal and word splitting, and any string that starts
with a \fB\-\fR is handled as \fBtar\fR command line option.
@@ -1004,7 +1011,7 @@ Treat each line obtained from a file lis
starts with a dash. File lists are supplied with the
\fB\-\-files\-from\fR (\fB\-T\fR) option. The default behavior is to
handle names supplied in file lists as if they were typed in the
-command line, i.e. any names starting with a dash are treated as
+command line, i.e., any names starting with a dash are treated as
\fBtar\fR options. The \fB\-\-verbatim\-files\-from\fR option
disables this behavior.
@@ -1138,49 +1145,49 @@ Enable all warning messages. This is th
.B none
Disable all warning messages.
.TP
-.B filename-with-nuls
+.B filename\-with\-nuls
"%s: file name read contains nul character"
.TP
-.B alone-zero-block
+.B alone\-zero\-block
"A lone zero block at %s"
.HP
-Keywords applicable for \fBtar --create\fR:
+Keywords applicable for \fBtar \-\-create\fR:
.TP
.B cachedir
"%s: contains a cache directory tag %s; %s"
.TP
-.B file-shrank
+.B file\-shrank
"%s: File shrank by %s bytes; padding with zeros"
.TP
.B xdev
"%s: file is on a different filesystem; not dumped"
.TP
-.B file-ignored
+.B file\-ignored
"%s: Unknown file type; file ignored"
.br
"%s: socket ignored"
.br
"%s: door ignored"
.TP
-.B file-unchanged
+.B file\-unchanged
"%s: file is unchanged; not dumped"
.TP
-.B ignore-archive
+.B ignore\-archive
"%s: archive cannot contain itself; not dumped"
.TP
-.B file-removed
+.B file\-removed
"%s: File removed before we read it"
.TP
-.B file-changed
+.B file\-changed
"%s: file changed as we read it"
.TP
-.B failed-read
+.B failed\-read
Suppresses warnings about unreadable files or directories. This
keyword applies only if used together with the
.B \-\-ignore\-failed\-read
option.
.HP
-Keywords applicable for \fBtar --extract\fR:
+Keywords applicable for \fBtar \-\-extract\fR:
.TP
.B existing\-file
"%s: skipping existing file"
@@ -1190,29 +1197,29 @@ Keywords applicable for \fBtar --extract
.br
"%s: time stamp %s is %s s in the future"
.TP
-.B contiguous-cast
+.B contiguous\-cast
"Extracting contiguous files as regular files"
.TP
-.B symlink-cast
+.B symlink\-cast
"Attempting extraction of symbolic links as hard links"
.TP
-.B unknown-cast
+.B unknown\-cast
"%s: Unknown file type '%c', extracted as normal file"
.TP
-.B ignore-newer
+.B ignore\-newer
"Current %s is newer or same age"
.TP
-.B unknown-keyword
+.B unknown\-keyword
"Ignoring unknown extended header keyword '%s'"
.TP
-.B decompress-program
+.B decompress\-program
Controls verbose description of failures occurring when trying to run
alternative decompressor programs. This warning is disabled by
default (unless \fB\-\-verbose\fR is used). A common example of what
you can get when using this warning is:
.EX
-$ tar --warning=decompress-program -x -f archive.Z
+$ tar \-\-warning=decompress\-program \-x \-f archive.Z
tar (child): cannot run compress: No such file or directory
tar (child): trying gzip
.EE
@@ -1221,23 +1228,23 @@ This means that \fBtar\fR first tried to
\fBarchive.Z\fR using \fBcompress\fR, and, when that
failed, switched to \fBgzip\fR.
.TP
-.B record-size
+.B record\-size
"Record size = %lu blocks"
.HP
Keywords controlling incremental extraction:
.TP
-.B rename-directory
+.B rename\-directory
"%s: Directory has been renamed from %s"
.br
"%s: Directory has been renamed"
.TP
-.B new-directory
+.B new\-directory
"%s: Directory is new"
.TP
.B xdev
"%s: directory is on a different device: not purging"
.TP
-.B bad-dumpdir
+.B bad\-dumpdir
"Malformed dumpdir: 'X' never used"
.RE
.TP
@@ -1249,21 +1256,20 @@ Ask for confirmation for every action.
When creating, same as \fB\-\-old\-archive\fR. When extracting, same
as \fB\-\-no\-same\-owner\fR.
.SS Size suffixes
-.sp
.nf
.ta 8n 18n 42n
.ul
Suffix Units Byte Equivalent
- b Blocks \fISIZE\fR x 512
- B Kilobytes \fISIZE\fR x 1024
- c Bytes \fISIZE\fR
- G Gigabytes \fISIZE\fR x 1024^3
- K Kilobytes \fISIZE\fR x 1024
- k Kilobytes \fISIZE\fR x 1024
- M Megabytes \fISIZE\fR x 1024^2
- P Petabytes \fISIZE\fR x 1024^5
- T Terabytes \fISIZE\fR x 1024^4
- w Words \fISIZE\fR x 2
+ b blocks \fISIZE\fR x 512
+ B kibibytes \fISIZE\fR x 1024
+ c bytes \fISIZE\fR
+ G gibibytes \fISIZE\fR x 1024^3
+ K kibibytes \fISIZE\fR x 1024
+ k kibibytes \fISIZE\fR x 1024
+ M mebibytes \fISIZE\fR x 1024^2
+ P pebibytes \fISIZE\fR x 1024^5
+ T tebibytes \fISIZE\fR x 1024^4
+ w words \fISIZE\fR x 2
.fi
.PP
.SH "RETURN VALUE"
@@ -1275,9 +1281,11 @@ Successful termination.
.TP
.B 1
.I Some files differ.
-If \fBtar\fR was invoked with the \fB\-\-compare\fR (\fB\-\-diff\fR, \fB\-d\fR)
+If \fBtar\fR was invoked with the \fB\-\-compare\fR (\fB\-\-diff\fR,
+\fB\-d\fR)
command line option, this means that some files in the archive differ
-from their disk counterparts. If \fBtar\fR was given one of the
\fB\-\-create\fR,
+from their disk counterparts.
+If \fBtar\fR was given one of the \fB\-\-create\fR,
\fB\-\-append\fR or \fB\-\-update\fR options, this exit code means
that some files were changed while being archived and so the resulting
archive does not contain the exact copy of the file set.
@@ -1291,7 +1299,7 @@ If a subprocess that had been invoked by
exited with a nonzero exit code,
.B tar
itself exits with that code as well. This can happen, for example, if
-a compression option (e.g. \fB\-z\fR) was used and the external
+a compression option (e.g.\& \fB\-z\fR) was used and the external
compressor program failed. Another example is
.B rmt
failure during backup to a remote device.
