mdoc(7) police: formatting fixes.

svn path=/head/; revision=70347

gnu/usr.bin/tar/tar.1

@@ -11,27 +11,27 @@
 .Dt TAR 1
 .Sh NAME
 .Nm tar
-.Nd
+.Nd "tape archiver; manipulate ""tar"" archive files"
-tape archiver; manipulate "tar" archive files
 .Sh SYNOPSIS
 .Nm
 .Op [-] Ns Ar bundled-options Ar Args
 .Op Ar gnu-style-flags
-.Oo
+.Op Ar filenames | Fl C Ar directory-name
-.Ar filenames | Fl C Ar directory-name
+.Ar ...
-.Oc ...
 .Sh DESCRIPTION
 .Nm Tar
 is short for 
-.Dq tape archiver,
+.Dq tape archiver ,
 so named for historical reasons; the
 .Nm
 program creates, adds files to, or extracts files from an archive file
 in
-.Dq tar
+.Nm
 format, called a
 .Ar tarfile .
-A tarfile is often a magnetic tape, but can be a floppy diskette or any
+A
+.Ar tarfile
+is often a magnetic tape, but can be a floppy diskette or any
 regular disk file.
 .Pp
 The first argument word of the
@@ -46,13 +46,25 @@ it must contain exactly one function letter from the set
 .Cm t ,
 .Cm u ,
 .Cm x ,
-for append, create, difference, replace, table of contents, update, and
+for
-extract (further described below).  The command word can also contain other
+.Em append ,
-function modifiers described below, some of which will take arguments from
+.Em create ,
-the command line in the order they are specified in the command word (review
+.Em difference ,
-the EXAMPLES section).  Functions and function modifiers can also be specified
+.Em replace ,
+.Em table of contents ,
+.Em update ,
+and
+.Em extract
+(further described below).
+The command word can also contain other function modifiers described below,
+some of which will take arguments from the command line in the order they
+are specified in the command word (review the
+.Sx EXAMPLES
+section).
+Functions and function modifiers can also be specified
 with the GNU argument convention (preceded by two dashes, one function or
-modifier per word.  Command-line arguments that specify files to
+modifier per word.
+Command-line arguments that specify files to
 add to, extract from, or list from an archive may be given as shell
 pattern matching strings.
 .Sh FUNCTIONS
@@ -62,13 +74,16 @@ Exactly one of the following functions must be specified.
 .It Fl A
 .It Fl -catenate
 .It Fl "-concatenate"
-Append the contents of named file, which must itself be a tar archive,
+Append the contents of named file, which must itself be a
+.Nm
+archive,
 to the end of the archive (erasing the old end-of-archive block).
 This has the effect of adding the files contained in the named file to
 the first archive, rather than adding the second archive as an element
 of the first.
-.Em Note:
+.Em Note :
-This option requires a rewritable tarfile,
+This option requires a rewritable
+.Ar tarfile ,
 and therefore does not work on quarter-inch cartridge tapes.
 .It Fl c
 .It Fl -create
@@ -80,26 +95,32 @@ to it.
 Find differences between files in the archive and corresponding files in
 the file system.
 .It Fl -delete
-Delete named files from the archive (Does not work on quarter-inch tapes).
+Delete named files from the archive.
+(Does not work on quarter-inch tapes).
 .It Fl r
 .It Fl -append
-Append files to the end of an archive (Does not work on quarter-inch tapes).
+Append files to the end of an archive.
+(Does not work on quarter-inch tapes).
 .It Fl t
 .It Fl -list
-List the contents of an archive; if filename arguments are given, only those
+List the contents of an archive; if
+.Ar filename
+arguments are given, only those
 files are listed, otherwise the entire table of contents is listed.
 .It Fl u
 .It Fl -update
 Append the named files if the on-disk version has a modification date
-more recent than their copy in the archive (if any).  Does not work on
+more recent than their copy in the archive (if any).
-quarter-inch tapes.
+Does not work on quarter-inch tapes.
 .It Fl x
 .It Fl -extract
 .It Fl -get
-Extract files from an archive.  The owner, modification time, and file
+Extract files from an archive.
-permissions are restored, if possible.  If no
+The owner, modification time, and file permissions are restored, if possible.
+If no
 .Ar file
-arguments are given, extract all the files in the archive.  If a
+arguments are given, extract all the files in the archive.
+If a
 .Ar filename
 argument matches the name of a directory on the tape, that directory and
 its contents are extracted (as well as all directories under that directory).
@@ -112,7 +133,8 @@ command above), the last one extracted will overwrite all earlier versions.
 The other options to
 .Nm
 may be combined arbitrarily; single-letter options may be bundled in with
-the command word.  Verbose options which take arguments will be
+the command word.
+Verbose options which take arguments will be
 followed by the argument; single-letter options will consume
 successive command line arguments (see the
 .Sx EXAMPLES
@@ -133,7 +155,9 @@ Sets the block size for reading or writing to
 * 512-byte blocks.
 .It Fl B
 .It Fl -read-full-blocks
-Re-assemble short reads into full blocks (for reading 4.2BSD pipes).
+Re-assemble short reads into full blocks (for reading
+.Bx 4.2
+pipes).
 .It Fl C Ar directory
 .It Fl -directory Ar directory
 Change to
@@ -141,11 +165,17 @@ Change to
 before processing the remaining arguments.
 .It Fl -checkpoint
 Print number of buffer reads/writes while reading/writing the archive.
-.It Fl f Ar [hostname:]file
+.It Fl f Xo
-.It Fl -file  Ar [hostname:]file
+.Oo Ar hostname : Oc Ns Ar file
+.Xc
+.It Fl -file Xo
+.Oo Ar hostname : Oc Ns Ar file
+.Xc
 Read or write the specified
 .Ar file
-(default is /dev/rsa0).  If a
+(default is
+.Pa /dev/rsa0 ) .
+If a
 .Ar hostname
 is specified,
 .Nm
@@ -153,10 +183,12 @@ will use
 .Xr rmt 8
 to read or write the specified
 .Ar file
-on a remote machine. "-" may be used is a filename, for reading
+on a remote machine.
+.Dq Ar -
+may be used as a filename, for reading
 or writing to/from stdin/stdout.
 .It Fl -force-local
-Archive file is local even if it has a colon
+Archive file is local even if it has a colon.
 .It Fl F Ar file
 .It Fl -info-script Ar file
 .It Fl -new-volume-script Ar file
@@ -235,10 +267,12 @@ Extract files to standard output.
 Extract all protection information.
 .It Fl -preserve
 Has the effect of
-.Fl p s.
+.Fl p s .
 .It Fl P
 .It Fl -absolute-paths
-Don't strip leading `/' from file names.
+Don't strip leading
+.Ql /
+from file names.
 .It Fl R
 .It Fl -record-number
 Show record number within archive with each message.
@@ -252,7 +286,9 @@ List of names to extract is sorted to match archive.
 Show directories which were omitted while processing the archive.
 .It Fl S
 .It Fl -sparse
-Handle "sparse" files efficiently.
+Handle
+.Dq sparse
+files efficiently.
 .It Fl T Ar file
 .It Fl I Ar file
 .It Fl -files-from Ar file
@@ -263,10 +299,10 @@ one per line.
 Modifies behavior of
 .Fl T
 to expect null-terminated names; disables
-.Fl C.
+.Fl C .
 .It Fl -totals
 Prints total bytes written with
-.Fl -create.
+.Fl -create .
 .It Fl U
 .It Fl -unlink
 .It Fl -unlink-first
@@ -278,7 +314,7 @@ Lists files written to archive with
 or extracted with
 .Fl -extract;
 lists file protection information along with file names with
-.Fl -list.
+.Fl -list .
 .It Fl V Ar volume-name
 .It Fl -label Ar volume-name
 Create archive with the given
@@ -317,11 +353,15 @@ Filter the archive through
 .Ar program
 (which must accept
 .Fl d
-to mean ``decompress'').
+to mean
+.Dq decompress ) .
 .It Fl -block-compress
 Block the output of compression program for tapes or floppies
 (otherwise writes will be of odd length, which device drivers may reject).
-.It Fl [0-7][lmh]
+.It Fl Xo
+.Op Cm 0 Ns - Ns Cm 7 Ns
+.Op Cm lmh
+.Xc
 Specify tape drive and density.
 .El
 .Sh ENVIRONMENT
@@ -332,11 +372,16 @@ can hold a set of default options for
 These options are interpreted first and can be overwritten by explicit command
 line parameters.
 .Sh EXAMPLES
-To create an archive on tape drive /dev/rsa0 with a block size of 20
+To create an archive on tape drive
-blocks, containing files named "bert" and "ernie", you can enter
+.Pa /dev/rsa0
-.Dl tar cfb /dev/rsa0 20 bert ernie
+with a block size of 20 blocks, containing files named
+.Pa bert
+and
+.Pa ernie ,
+you can enter
+.Dl "tar cfb /dev/rsa0 20 bert ernie"
 or
-.Dl tar\ --create\ --file\ /dev/rsa0\ --block-size\ 20\ bert\ ernie
+.Dl "tar --create --file /dev/rsa0 --block-size 20 bert ernie"
 Note that the
 .Fl f
 and
@@ -344,13 +389,16 @@ and
 flags both require arguments, which they take from the command line in
 the order they were listed in the command word.
 .Pp
-Because /dev/rsa0 is the default device, and 20 is the default block
+Because
+.Pa /dev/rsa0
+is the default device, and 20 is the default block
 size, the above example could have simply been
-.Dl tar c bert ernie
+.Dl "tar c bert ernie"
 .Pp
 To extract all the C sources and headers from an archive named
-"backup.tar", type
+.Pa backup.tar ,
-.Dl tar xf backup.tar '*.[ch]'
+type
+.Dl "tar xf backup.tar '*.[ch]'"
 Note that the pattern must be quoted to prevent the shell from
 attempting to expand it according the files in the current working
 directory (the shell does not have access to the list of files in
@@ -361,38 +409,60 @@ To move file hierarchies, use a command line like this:
 tar -cf - -C srcdir . | tar xpf - -C destdir
 .Ed
 .Pp
-To create a compressed archive on diskette, using gzip, use a command-line like
+To create a compressed archive on diskette, using
-.Dl tar --block-compress -z -c -v -f /dev/fd1a -b 36 tar/
+.Xr gzip 1 ,
+use a command-line like
+.Dl "tar --block-compress -z -c -v -f /dev/fd1a -b 36 tar/"
 .Pp
-Note that you cannot mix bundled flags and --style flags; you can use
+Note that you cannot mix bundled flags and
+.Fl -style
+flags; you can use
 single-letter flags in the manner above, rather than having to type
-.Dl tar --block-compress --gzip --verbose --file /dev/fd1a --block-size 20 tar/
+.Dl "tar --block-compress --gzip --verbose --file /dev/fd1a --block-size 20 tar/"
 .Pp
 The above-created diskette can be listed with
-.Dl tar tvfbz /dev/fd1a 36
+.Dl "tar tvfbz /dev/fd1a 36"
 .Pp
-To join two tar archives into a single archive, use
+To join two
-.Dl tar Af archive1.tar archive2.tar
+.Nm
-which will add the files contained in archive2.tar onto the end of
+archives into a single archive, use
-archive1.tar (note that this can't be done by simply typing
+.Dl "tar Af archive1.tar archive2.tar"
-.Dl cat archive2.tar >> archive1.tar
+which will add the files contained in
-because of the end-of-file block at the end of a tar archive).
+.Pa archive2.tar
+onto the end of
+.Pa archive1.tar
+(note that this can't be done by simply typing
+.Dl "cat archive2.tar >> archive1.tar"
+because of the end-of-file block at the end of a
+.Nm
+archive).
 .Pp
-To archive all files from the directory srcdir, which were modified
+To archive all files from the directory
+.Pa srcdir ,
+which were modified
 after Feb. 9th 1997, 13:00 h, use
-.Dl tar\ -c\ -f\ backup.tar\ --newer-mtime\ 'Feb\ 9\ 13:15\ 1997'\ srcdir/
+.Dl "tar -c -f backup.tar --newer-mtime 'Feb 9 13:15 1997' srcdir/"
 .Pp
-Other possible time specifications are '02/09/97 13:15',
+Other possible time specifications are
-\&'1997-02-09 13:15', '13:15 9 Feb 1997', '9 Feb 1997 13:15', 
+.Sq "02/09/97 13:15" ,
-\&'Feb. 9, 1997 1:15pm', '09-Feb', '3 weeks ago' or 'May first Sunday'.
+.Sq "1997-02-09 13:15" ,
-To specify the correct time zone use either e.g. `13:15 CEST' or `13:15+200'.
+.Sq "13:15 9 Feb 1997" ,
-
+.Sq "9 Feb 1997 13:15" , 
+.Sq "Feb. 9, 1997 1:15pm" ,
+.Sq "09-Feb" ,
+.Sq "3 weeks ago"
+or
+.Sq "May first Sunday" .
+To specify the correct time zone use either e.g.\&
+.Sq "13:15 CEST"
+or
+.Sq "13:15+200" .
 .Sh ENVIRONMENT
 The
 .Nm
 program examines the following environment variables.
 .Bl -tag -width "POSIXLY_CORRECT"
-.It POSIXLY_CORRECT
+.It Ev POSIXLY_CORRECT
 Normally,
 .Nm
 will process flag arguments that appear in the file list.
@@ -400,12 +470,17 @@ If set in the environment, this causes
 .Nm
 to consider the first
 non-flag argument to terminate flag processing, as per the POSIX specification.
-.It SHELL
+.It Ev SHELL
 In interactive mode, a permissible response to the prompt is to
-request to spawn a subshell, which will be "/bin/sh" unless the SHELL variable
+request to spawn a subshell, which will be
-is set.
+.Pa /bin/sh
-.It TAPE
+unless the
-Changes tar's default tape drive (which is still overridden by the
+.Ev SHELL
+variable is set.
+.It Ev TAPE
+Changes
+.Nm Ns 's
+default tape drive (which is still overridden by the
 .Fl f
 flag).
 .El
@@ -414,36 +489,48 @@ flag).
 .It Pa /dev/rsa0
 The default tape drive.
 .El
-.\" This next request is for sections 1, 6, 7 & 8 only
-.\"     (command return values (to shell) and fprintf/stderr type diagnostics)
-.\" .Sh DIAGNOSTICS
 .Sh COMPATIBILITY
 The
 .Fl y
-is a FreeBSD localism.
+is a
-The GNU tar maintainer has now choosen
+.Fx
+localism.
+The GNU
+.Nm
+maintainer has now choosen
 .Fl j
-as the offical bzip2 compression option in GNU tar 1.13.18 and later.
+as the offical
+.Xr bzip2 1
+compression option in GNU
+.Nm
+1.13.18 and later.
 The
 .Fl I
-option is for compatibility with Solaris's tar.
+option is for compatibility with Solaris's
+.Nm .
 .Sh SEE ALSO
 .Xr bzip2 1 ,
 .Xr compress 1 ,
 .Xr gzip 1 ,
 .Xr pax 1 ,
 .Xr rmt 8
-.\" .Sh STANDARDS
 .Sh HISTORY
-The tar format has a rich history, dating back to Sixth Edition UNIX.
+The
+.Nm
+format has a rich history, dating back to Sixth Edition
+.Ux .
 The current implementation of
 .Nm
 is the GNU implementation, which
-originated as the public-domain tar written by John Gilmore.
+originated as the public-domain
+.Nm
+written by
+.An John Gilmore .
 .Sh AUTHORS
 .An -nosplit
-A cast of thousands, including [as listed in the ChangeLog file in the
+A cast of thousands, including [as listed in the
-source]
+.Pa ChangeLog
+file in the source]
 .An John Gilmore
 (author of original public domain version),
 .An Jay Fenlason
@@ -463,11 +550,14 @@ release.
 .Sh BUGS
 The
 .Fl C
-feature does not work like historical tar programs, and is probably
+feature does not work like historical
-untrustworthy.
+.Nm
+programs, and is probably untrustworthy.
 .Pp
 The 
 .Fl A 
-command should work to join an arbitrary number of tar archives
+command should work to join an arbitrary number of
+.Nm
+archives
 together, but it does not; attempting to do so leaves the
 end-of-archive blocks in place for the second and subsequent archives.