+Specifies the length of tapes that @code{tar} is writing as being
+@w{@var{num} x 1024} bytes long. @FIXME-xref{}.
+
+@item --to-stdout
+@itemx -O
+
+During extraction, @code{tar} will extract files to stdout rather than to the
+file system. @xref{Writing}.
+
+@item --totals
+
+Displays the total number of bytes written after creating an archive.
+@FIXME-xref{}.
+
+@item --touch
+@itemx -m
+
+Sets the modification time of extracted files to the extraction time,
+rather than the modification time stored in the archive.
+@xref{Writing}.
+
+@item --uncompress
+
+(See @samp{--compress}; @FIXME-pxref{}.)
+
+@item --ungzip
+
+(See @samp{--gzip}; @FIXME-pxref{}.)
+
+@item --unlink-first
+@itemx -U
+
+Directs @code{tar} to remove the corresponding file from the file system
+before extracting it from the archive. @xref{Writing}.
+
+@item --use-compress-program=@var{prog}
+
+Instructs @code{tar} to access the archive through @var{prog}, which is
+presumed to be a compression program of some sort. @FIXME-xref{}.
+
+@item --verbose
+@itemx -v
+
+Specifies that @code{tar} should be more verbose about the operations its
+performing. This option can be specified multiple times for some
+operations to increase the amount of information displayed. @FIXME-xref{}.
+
+@item --verify
+@itemx -W
+
+Verifies that the archive was correctly written when creating an
+archive. @FIXME-xref{}.
+
+@item --version
+
+@code{tar} will print an informational message about what version it is and a
+copyright message, some credits, and then exit. @FIXME-xref{}.
+
+@item --volno-file=@var{file}
+
+Used in conjunction with @samp{--multi-volume}. @code{tar} will keep track
+of which volume of a multi-volume archive its working in @var{file}.
+@FIXME-xref{}.
+@end table
+
+@node Short Option Summary, , Option Summary, All Options
+@subsection Short Options Cross Reference
+
+Here is an alphabetized list of all of the short option forms, matching
+them with the equivalent long option.
+
+@table @kbd
+
+@item -A
+
+@samp{--concatenate}
+
+@item -B
+
+@samp{--read-full-records}
+
+@item -C
+
+@samp{--directory}
+
+@item -F
+
+@samp{--info-script}
+
+@item -G
+
+@samp{--incremental}
+
+@item -K
+
+@samp{--starting-file}
+
+@item -L
+
+@samp{--tape-length}
+
+@item -M
+
+@samp{--multi-volume}
+
+@item -N
+
+@samp{--newer}
+
+@item -O
+
+@samp{--to-stdout}
+
+@item -P
+
+@samp{--absolute-names}
+
+@item -R
+
+@samp{--block-number}
+
+@item -S
+
+@samp{--sparse}
+
+@item -T
+
+@samp{--files-from}
+
+@item -U
+
+@samp{--unlink-first}
+
+@item -V
+
+@samp{--label}
+
+@item -W
+
+@samp{--verify}
+
+@item -X
+
+@samp{--exclude-from}
+
+@item -Z
+
+@samp{--compress}
+
+@item -b
+
+@samp{--blocking-factor}
+
+@item -c
+
+@samp{--create}
+
+@item -d
+
+@samp{--compare}
+
+@item -f
+
+@samp{--file}
+
+@item -g
+
+@samp{--listed-incremental}
+
+@item -h
+
+@samp{--dereference}
+
+@item -i
+
+@samp{--ignore-zeros}
+
+@item -k
+
+@samp{--keep-old-files}
+
+@item -l
+
+@samp{--one-file-system}
+
+@item -m
+
+@samp{--touch}
+
+@item -o
+
+@samp{--portability}
+
+@item -p
+
+@samp{--preserve-permissions}
+
+@item -r
+
+@samp{--append}
+
+@item -s
+
+@samp{--same-order}
+
+@item -t
+
+@samp{--list}
+
+@item -u
+
+@samp{--update}
+
+@item -v
+
+@samp{--verbose}
+
+@item -w
+
+@samp{--interactive}
+
+@item -x
+
+@samp{--extract}
+
+@item -z
+
+@samp{--gzip}
+
+@end table
+
+@node help, verbose, All Options, tar invocation
+@section GNU @code{tar} documentation
+
+Being careful, the first thing is really checking that you are using GNU
+@code{tar}, indeed. The @value{op-version} option will generate a message
+giving confirmation that you are using GNU @code{tar}, with the precise
+version of GNU @code{tar} you are using. @code{tar} identifies itself
+and prints the version number to the standard output, then immediately
+exits successfully, without doing anything else, ignoring all other
+options. For example, @w{@samp{tar --version}} might return:
+
+@example
+tar (GNU tar) @value{VERSION}
+@end example
+
+@noindent
+The first occurrence of @samp{tar} in the result above is the program
+name in the package (for example, @code{rmt} is another program), while
+the second occurrence of @samp{tar} is the name of the package itself,
+containing possibly many programs. The package is currently named
+@samp{tar}, after the name of the main program it contains@footnote{There
+are plans to merge the @code{cpio} and @code{tar} packages into a single one
+which would be called @code{paxutils}. So, who knows if, one of this days,
+the @value{op-version} would not yield @w{@samp{tar (GNU paxutils) 3.2}}}.
+
+Another thing you might want to do is checking the spelling or meaning
+of some particular @code{tar} option, without resorting to this manual,
+for once you have carefully read it. GNU @code{tar} has a short help
+feature, triggerable through the @value{op-help} option. By using this
+option, @code{tar} will print a usage message listing all available
+options on standard output, then exit successfully, without doing
+anything else and ignoring all other options. Even if this is only a
+brief summary, it may be several screens long. So, if you are not
+using some kind of scrollable window, you might prefer to use something
+like:
+
+@example
+$ @kbd{tar --help | less}
+@end example
+
+@noindent
+presuming, here, that you like using @code{less} for a pager. Other
+popular pagers are @code{more} and @code{pg}. If you know about some
+@var{keyword} which interests you and do not want to read all the
+@value{op-help} output, another common idiom is doing:
+
+@example
+tar --help | grep @var{keyword}
+@end example
+
+@noindent
+for getting only the pertinent lines.
+
+The perceptive reader would have noticed some contradiction in the
+previous paragraphs. It is written that both @value{op-version} and
+@value{op-help} print something, and have all other options ignored. In
+fact, they cannot ignore each other, and one of them has to win. We do
+not specify which is stronger, here; experiment if you really wonder!
+
+The short help output is quite succint, and you might have to get back
+to the full documentation for precise points. If you are reading this
+paragraph, you already have the @code{tar} manual in some form. This
+manual is available in printed form, as a kind of small book. It may
+printed out of the GNU @code{tar} distribution, provided you have @TeX{}
+already installed somewhere, and a laser printer around. Just configure
+the distribution, execute the command @w{@samp{make dvi}}, then print
+@file{doc/tar.dvi} the usual way (contact your local guru to know how).
+If GNU @code{tar} has been conveniently installed at your place, this
+manual is also available in interactive, hypertextual form as an Info
+file. Just call @w{@samp{info tar}} or, if you do not have the
+@code{info} program handy, use the Info reader provided within GNU
+Emacs, calling @samp{tar} from the main Info menu.
+
+There is currently no @code{man} page for GNU @code{tar}. If you observe
+such a @code{man} page on the system you are running, either it does not
+long to GNU @code{tar}, or it has not been produced by GNU. Currently,
+GNU @code{tar} documentation is provided in Texinfo format only, if we
+except, of course, the short result of @kbd{tar --help}.
+
+@node verbose, interactive, help, tar invocation
+@section Checking @code{tar} progress
+
+@cindex Progress information
+@cindex Status information
+@cindex Information on progress and status of operations
+@cindex Verbose operation
+@cindex Block number where error occured
+@cindex Error message, block number of
+@cindex Version of the @code{tar} program
+
+@cindex Getting more information during the operation
+@cindex Information during operation
+@cindex Feedback from @code{tar}
+
+Typically, @code{tar} performs most operations without reporting any
+information to the user except error messages. When using @code{tar}
+with many options, particularly ones with complicated or
+difficult-to-predict behavior, it is possible to make serious mistakes.
+@code{tar} provides several options that make observing @code{tar}
+easier. These options cause @code{tar} to print information as it
+progresses in its job, and you might want to use them just for being
+more careful about what is going on, or merely for entertaining
+yourself. If you have encountered a problem when operating on an
+archive, however, you may need more information than just an error
+message in order to solve the problem. The following options can be
+helpful diagnostic tools.
+
+Normally, the @value{op-list} command to list an archive prints just
+the file names (one per line) and the other commands are silent.
+When used with most operations, the @value{op-verbose} option causes
+@code{tar} to print the name of each file or archive member as it
+is processed. This and the other options which make @code{tar} print
+status information can be useful in monitoring @code{tar}.
+
+With @value{op-create} or @value{op-extract}, @value{op-verbose} used once
+just prints the names of the files or members as they are processed.
+Using it twice causes @code{tar} to print a longer listing (reminiscent
+of @samp{ls -l}) for each member. Since @value{op-list} already prints
+the names of the members, @value{op-verbose} used once with @value{op-list}
+causes @code{tar} to print an @samp{ls -l} type listing of the files
+in the archive. The following examples both extract members with
+long list output:
+
+@example
+$ @kbd{tar --extract --file=archive.tar --verbose --verbose}
+$ @kbd{tar xvv archive.tar}
+@end example
+
+Verbose output appears on the standard output except when an archive is
+being written to the standard output, as with @samp{tar --create
+--file=- --verbose} (@samp{tar cfv -}, or even @samp{tar cv}---if the
+installer let standard output be the default archive). In that case
+@code{tar} writes verbose output to the standard error stream.
+
+The @value{op-totals} option---which is only meaningful when used with
+@value{op-create}---causes @code{tar} to print the total
+amount written to the archive, after it has been fully created.
+
+The @value{op-checkpoint} option prints an occasional message
+as @code{tar} reads or writes the archive. In fact, it print
+directory names while reading the archive. It is designed for
+those who don't need the more detailed (and voluminous) output of
+@value{op-block-number}, but do want visual confirmation that @code{tar}
+is actually making forward progress.
+
+@FIXME{There is some confusion here. It seems that -R once wrote a
+message at @samp{every} record read or written.}
+
+The @value{op-show-omitted-dirs} option, when reading an archive---with
+@value{op-list} or @value{op-extract}, for example---causes a message
+to be printed for each directory in the archive which is skipped.
+This happens regardless of the reason for skipping: the directory might
+not have been named on the command line (implicitly or explicitly),
+it might be excluded by the use of the @value{op-exclude} option, or
+some other reason.
+
+If @value{op-block-number} is used, @code{tar} prints, along with every
+message it would normally produce, the block number within the archive
+where the message was triggered. Also, supplementary messages are
+triggered when reading blocks full of NULs, or when hitting end of file on
+the archive. As of now, if the archive if properly terminated with a NUL
+block, the reading of the file may stop before end of file is met, so the
+position of end of file will not usually show when @value{op-block-number}
+is used. Note that GNU @code{tar} drains the archive before exiting when
+reading the archive from a pipe.
+
+This option is especially useful when reading damaged archives, since
+it helps pinpoint the damaged sections. It can also be used with
+@value{op-list} when listing a file-system backup tape, allowing you to
+choose among several backup tapes when retrieving a file later, in
+favor of the tape where the file appears earliest (closest to the
+front of the tape). @FIXME-xref{when the node name is set and the
+backup section written}.
+
+@node interactive, , verbose, tar invocation
+@section Asking for Confirmation During Operations
+@cindex Interactive operation
+
+Typically, @code{tar} carries out a command without stopping for
+further instructions. In some situations however, you may want to
+exclude some files and archive members from the operation (for instance
+if disk or storage space is tight). You can do this by excluding
+certain files automatically (@pxref{Choosing}), or by performing
+an operation interactively, using the @value{op-interactive} option.
+@code{tar} also accepts @samp{--confirmation} for this option.
+
+When the @value{op-interactive} option is specified, before
+reading, writing, or deleting files, @code{tar} first prints a message
+for each such file, telling what operation it intends to take, then asks
+for confirmation on the terminal. The actions which require
+confirmation include adding a file to the archive, extracting a file
+from the archive, deleting a file from the archive, and deleting a file
+from disk. To confirm the action, you must type a line of input
+beginning with @samp{y}. If your input line begins with anything other
+than @samp{y}, @code{tar} skips that file.
+
+If @code{tar} is reading the archive from the standard input,
+@code{tar} opens the file @file{/dev/tty} to support the interactive
+communications.
+
+Verbose output is normally sent to standard output, separate from
+other error messages. However, if the archive is produced directly
+on standard output, then verbose output is mixed with errors on
+@code{stderr}. Producing the archive on standard output may be used
+as a way to avoid using disk space, when the archive is soon to be
+consumed by another process reading it, say. Some people felt the need
+of producing an archive on stdout, still willing to segregate between
+verbose output and error output. A possible approach would be using a
+named pipe to receive the archive, and having the consumer process to
+read from that named pipe. This has the advantage of letting standard
+output free to receive verbose output, all separate from errors.
+
+@node operations, Backups, tar invocation, Top
+@chapter GNU @code{tar} Operations
+
+@menu
+* Basic tar::
+* Advanced tar::
+* extract options::
+* backup::
+* Applications::
+* looking ahead::
+@end menu
+
+@node Basic tar, Advanced tar, operations, operations
+@section Basic GNU @code{tar} Operations
+
+The basic @code{tar} operations, @value{op-create}, @value{op-list} and
+@value{op-extract}, are currently presented and described in the tutorial
+chapter of this manual. This section provides some complementary notes
+for these operations.
+
+@table @asis
+@item @value{op-create}
+
+Creating an empty archive would have some kind of elegance. One can
+initialize an empty archive and later use @value{op-append} for adding
+all members. Some applications would not welcome making an exception
+in the way of adding the first archive member. On the other hand,
+many people reported that it is dangerously too easy for @code{tar}
+to destroy a magnetic tape with an empty archive@footnote{This is well
+described in @cite{Unix-haters Handbook}, by Simson Garfinkel, Daniel
+Weise & Steven Strassmann, IDG Books, ISBN 1-56884-203-1.}. The two most
+common errors are:
+
+@enumerate
+@item
+Mistakingly using @code{create} instead of @code{extract}, when the
+intent was to extract the full contents of an archive. This error
+is likely: keys @kbd{c} and @kbd{x} are right next ot each other on
+the QWERTY keyboard. Instead of being unpacked, the archive then
+gets wholly destroyed. When users speak about @dfn{exploding} an
+archive, they usually mean something else :-).
+
+@item
+Forgetting the argument to @code{file}, when the intent was to create
+an archive with a single file in it. This error is likely because a
+tired user can easily add the @kbd{f} key to the cluster of option
+letters, by the mere force of habit, without realizing the full
+consequence of doing so. The usual consequence is that the single
+file, which was meant to be saved, is rather destroyed.
+@end enumerate
+
+So, recognizing the likelihood and the catastrophical nature of these
+errors, GNU @code{tar} now takes some distance from elegance, and
+cowardly refuses to create an archive when @value{op-create} option is
+given, there are no arguments besides options, and @value{op-files-from}
+option is @emph{not} used. To get around the cautiousness of GNU
+@code{tar} and nevertheless create an archive with nothing in it,
+one may still use, as the value for the @value{op-files-from} option,
+a file with no names in it, as shown in the following commands:
+
+@example
+@kbd{tar --create --file=empty-archive.tar --files-from=/dev/null}
+@kbd{tar cfT empty-archive.tar /dev/null}
+@end example
+
+@item @value{op-extract}
+
+A socket is stored, within a GNU @code{tar} archive, as a pipe.
+
+@item @value{op-list}
+
+GNU @code{tar} now shows dates as @samp{1996-11-09}, while it used to
+show them as @samp{Nov 11 1996}. (One can revert to the old behavior by
+defining @code{USE_OLD_CTIME} in @file{src/list.c} before reinstalling.)
+But preferrably, people you should get used to ISO 8601 dates. Local
+American dates should be made available again with full date localisation
+support, once ready. In the meantime, programs not being localisable
+for dates should prefer international dates, that's really the way to go.
+
+Look up @url{http://www.ft.uni-erlangen.de/~mskuhn/iso-time.html} if you
+are curious, it contains a detailed explanation of the ISO 8601 standard.
+
+@end table
+
+@node Advanced tar, extract options, Basic tar, operations
+@section Advanced GNU @code{tar} Operations
+
+Now that you have learned the basics of using GNU @code{tar}, you may
+want to learn about further ways in which @code{tar} can help you.
+
+This chapter presents five, more advanced operations which you probably
+won't use on a daily basis, but which serve more specialized functions.
+We also explain the different styles of options and why you might want
+to use one or another, or a combination of them in your @code{tar}
+commands. Additionally, this chapter includes options which allow you to
+define the output from @code{tar} more carefully, and provide help and
+error correction in special circumstances.
+
+@FIXME{check this after the chapter is actually revised to make sure
+it still introduces the info in the chapter correctly : ).}
+
+@menu
+* Operations::
+* current state::
+* append::
+* update::
+* concatenate::
+* delete::
+* compare::
+@end menu
+
+@node Operations, current state, Advanced tar, Advanced tar
+@subsection The Five Advanced @code{tar} Operations
+@UNREVISED
+
+In the last chapter, you learned about the first three operations to
+@code{tar}. This chapter presents the remaining five operations to
+@code{tar}: @samp{--append}, @samp{--update}, @samp{--concatenate},
+@samp{--delete}, and @samp{--compare}.
+
+You are not likely to use these operations as frequently as those
+covered in the last chapter; however, since they perform specialized
+functions, they are quite useful when you do need to use them. We
+will give examples using the same directory and files that you created
+in the last chapter. As you may recall, the directory is called
+@file{practice}, the files are @samp{jazz}, @samp{blues}, @samp{folk},
+@samp{rock}, and the two archive files you created are
+@samp{collection.tar} and @samp{music.tar}.
+
+We will also use the archive files @samp{afiles.tar} and
+@samp{bfiles.tar}. @samp{afiles.tar} contains the members @samp{apple},
+@samp{angst}, and @samp{aspic}. @samp{bfiles.tar} contains the members
+@samp{./birds}, @samp{baboon}, and @samp{./box}.
+
+Unless we state otherwise, all practicing you do and examples you follow
+in this chapter will take place in the @file{practice} directory that
+you created in the previous chapter; see @ref{prepare for examples}.
+(Below in this section, we will remind you of the state of the examples
+where the last chapter left them.)
+
+The five operations that we will cover in this chapter are:
+
+@table @kbd
+@item --append
+@itemx -r
+Add new entries to an archive that already exists.
+@item --update
+@itemx -r
+Add more recent copies of archive members to the end of an archive, if
+they exist.
+@item --concatenate
+@itemx --catenate
+@itemx -A
+Add one or more pre-existing archives to the end of another archive.
+@item --delete
+Delete items from an archive (does not work on tapes).
+@item --compare
+@itemx --diff
+@itemx -d
+Compare archive members to their counterparts in the file system.
+@end table
+
+@node current state, append, Operations, Advanced tar
+@ifinfo
+@subsection The Current State of the Practice Files
+@end ifinfo
+
+Currently, the listing of the directory using @code{ls} is as follows:
+
+@example
+
+@end example
+
+@noindent
+The archive file @samp{collection.tar} looks like this:
+
+@example
+$ @kbd{tar -tvf collection.tar}
+
+@end example
+
+@noindent
+The archive file @samp{music.tar} looks like this:
+
+@example
+$ @kbd{tar -tvf music.tar}
+
+@end example
+
+@FIXME{need to fill in the above!!!}
+
+@node append, update, current state, Advanced tar
+@subsection How to Add Files to Existing Archives: @code{--append}
+@UNREVISED
+
+If you want to add files to an existing archive, you don't need to
+create a new archive; you can use @value{op-append}. The archive must
+already exist in order to use @samp{--append}. (A related operation
+is the @samp{--update} operation; you can use this to add newer
+versions of archive members to an existing archive. To learn how to
+do this with @samp{--update}, @pxref{update}.)
+
+@FIXME{Explain in second paragraph whether you can get to the previous
+version -- explain whole situation somewhat more clearly.}
+
+If you use @value{op-append} to add a file that has the same name as an
+archive member to an archive containing that archive member, then the
+old member is not deleted. What does happen, however, is somewhat
+complex. @code{tar} @emph{allows} you to have infinite numbers of files
+with the same name. Some operations treat these same-named members no
+differently than any other set of archive members: for example, if you
+view an archive with @value{op-list}, you will see all of those members
+listed, with their modification times, owners, etc.
+
+Other operations don't deal with these members as perfectly as you might
+prefer; if you were to use @value{op-extract} to extract the archive,
+only the most recently added copy of a member with the same name as four
+other members would end up in the working directory. This is because
+@samp{--extract} extracts an archive in the order the members appeared
+in the archive; the most recently archived members will be extracted
+last. Additionally, an extracted member will @emph{overwrite} a file of
+the same name which existed in the directory already, and @code{tar}
+will not prompt you about this. Thus, only the most recently archived
+member will end up being extracted, as it will overwrite the one
+extracted before it, and so on.
+
+@FIXME{ hag -- you might want to incorporate some of the above into the
+MMwtSN node; not sure. i didn't know how to make it simpler...}
+
+There are a few ways to get around this. @FIXME-xref{Multiple Members
+with the Same Name}.
+
+@cindex Members, replacing with other members
+@cindex Replacing members with other members
+If you want to replace an archive member, use @value{op-delete} to
+delete the member you want to remove from the archive, , and then use
+@samp{--append} to add the member you want to be in the archive. Note
+that you can not change the order of the archive; the most recently
+added member will still appear last. In this sense, you cannot truely
+``replace'' one member with another. (Replacing one member with another
+will not work on certain types of media, such as tapes; see @ref{delete}
+and @ref{Media}, for more information.)
+
+@menu
+* appending files:: Appending Files to an Archive
+* multiple::
+@end menu
+
+@node appending files, multiple, append, append
+@subsubsection Appending Files to an Archive
+@UNREVISED
+@cindex Adding files to an Archive
+@cindex Appending files to an Archive
+@cindex Archives, Appending files to
+
+The simplest way to add a file to an already existing archive is the
+@value{op-append} operation, which writes specified files into the
+archive whether or not they are already among the archived files.
+When you use @samp{--append}, you @emph{must} specify file name
+arguments, as there is no default. If you specify a file that already
+exists in the archive, another copy of the file will be added to the
+end of the archive. As with other operations, the member names of the
+newly added files will be exactly the same as their names given on the
+command line. The @value{op-verbose} option will print out the names
+of the files as they are written into the archive.
+
+@samp{--append} cannot be performed on some tape drives, unfortunately,
+due to deficiencies in the formats those tape drives use. The archive
+must be a valid @code{tar} archive, or else the results of using this
+operation will be unpredictable. @xref{Media}.
+
+To demonstrate using @samp{--append} to add a file to an archive,
+create a file called @file{rock} in the @file{practice} directory.
+Make sure you are in the @file{practice} directory. Then, run the
+following @code{tar} command to add @file{rock} to
+@file{collection.tar}:
+
+@example
+$ @kbd{tar --append --file=collection.tar rock}
+@end example
+
+@noindent
+If you now use the @value{op-list} operation, you will see that
+@file{rock} has been added to the archive:
+
+@example
+$ @kbd{tar --list --file=collection.tar}
+-rw-rw-rw- me user 28 1996-10-18 16:31 jazz
+-rw-rw-rw- me user 21 1996-09-23 16:44 blues
+-rw-rw-rw- me user 20 1996-09-23 16:44 folk
+-rw-rw-rw- me user 20 1996-09-23 16:44 rock
+@end example
+
+@FIXME{in theory, dan will (soon) try to turn this node into what it's
+title claims it will become...}
+
+@node multiple, , appending files, append
+@subsubsection Multiple Files with the Same Name
+
+You can use @value{op-append} to add copies of files which have been
+updated since the archive was created. (However, we do not recommend
+doing this since there is another @code{tar} option called
+@samp{--update}; @pxref{update} for more information. We describe this
+use of @samp{--append} here for the sake of completeness.) @FIXME{is
+this really a good idea, to give this whole description for something
+which i believe is basically a Stupid way of doing something? certain
+aspects of it show ways in which tar is more broken than i'd personally
+like to admit to, specifically the last sentence. On the other hand, i
+don't think it's a good idea to be saying that re explicitly don't
+recommend using something, but i can't see any better way to deal with
+the situation.} When you extract the archive, the older version will be
+effectively lost. This works because files are extracted from an
+archive in the order in which they were archived. Thus, when the
+archive is extracted, a file archived later in time will overwrite a
+file of the same name which was archived earlier, even though the older
+version of the file will remain in the archive unless you delete all
+versions of the file.
+
+Supposing you change the file @file{blues} and then append the changed
+version to @file{collection.tar}. As you saw above, the original
+@file{blues} is in the archive @file{collection.tar}. If you change the
+file and append the new version of the file to the archive, there will
+be two copies in the archive. When you extract the archive, the older
+version of the file will be extracted first, and then overwritten by the
+newer version when it is extracted.
+
+You can append the new, changed copy of the file @file{blues} to the
+archive in this way:
+
+@example
+$ @kbd{tar --append --verbose --file=collection.tar blues}
+blues
+@end example
+
+@noindent
+Because you specified the @samp{--verbose} option, @code{tar} has
+printed the name of the file being appended as it was acted on. Now
+list the contents of the archive:
+
+@example
+$ @kbd{tar --list --verbose --file=collection.tar}
+-rw-rw-rw- me user 28 1996-10-18 16:31 jazz
+-rw-rw-rw- me user 21 1996-09-23 16:44 blues
+-rw-rw-rw- me user 20 1996-09-23 16:44 folk
+-rw-rw-rw- me user 20 1996-09-23 16:44 rock
+-rw-rw-rw- me user 58 1996-10-24 18:30 blues
+@end example
+
+@noindent
+The newest version of @file{blues} is now at the end of the archive
+(note the different creation dates and file sizes). If you extract
+the archive, the older version of the file @file{blues} will be
+overwritten by the newer version. You can confirm this by extracting
+the archive and running @samp{ls} on the directory. @xref{Writing}
+for more information. (@emph{Please note:} This is the case unless
+you employ the @value{op-backup} option; @FIXME-ref{Multiple Members
+with the Same Name}.)
+
+@node update, concatenate, append, Advanced tar
+@subsection Updating an Archive
+@UNREVISED
+@cindex Updating an archive
+
+In the previous section, you learned how to use @value{op-append} to add
+a file to an existing archive. A related operation is
+@value{op-update}. The @samp{--update} operation updates a @code{tar}
+archive by comparing the date of the specified archive members against
+the date of the file with the same name. If the file has been modified
+more recently than the archive member, then the newer version of the
+file is added to the archive (as with @value{op-append}).
+
+Unfortunately, you cannot use @samp{--update} with magnetic tape drives.
+The operation will fail.
+
+@FIXME{other examples of media on which --update will fail? need to ask
+charles and/or mib/thomas/dave shevett..}
+
+Both @samp{--update} and @samp{--append} work by adding to the end
+of the archive. When you extract a file from the archive, only the
+version stored last will wind up in the file system, unless you use
+the @value{op-backup} option (@FIXME-ref{Multiple Members with the
+Same Name}).
+
+@menu
+* how to update::
+@end menu
+
+@node how to update, , update, update
+@subsubsection How to Update an Archive Using @code{--update}
+
+You must use file name arguments with the @value{op-update} operation.
+If you don't specify any files, @code{tar} won't act on any files and
+won't tell you that it didn't do anything (which may end up confusing
+you).
+
+@FIXME{note: the above parenthetical added because in fact, this
+behavior just confused the author. :-) }
+
+To see the @samp{--update} option at work, create a new file,
+@file{classical}, in your practice directory, and some extra text to the
+file @file{blues}, using any text editor. Then invoke @code{tar} with
+the @samp{update} operation and the @value{op-verbose} option specified,
+using the names of all the files in the practice directory as file name
+arguments:
+
+@example
+$ @kbd{tar --update -v -f collection.tar blues folk rock classical}
+blues
+classical
+$
+@end example
+
+@noindent
+Because we have specified verbose mode, @code{tar} prints out the names
+of the files it is working on, which in this case are the names of the
+files that needed to be updated. If you run @samp{tar --list} and look
+at the archive, you will see @file{blues} and @file{classical} at its
+end. There will be a total of two versions of the member @samp{blues};
+the one at the end will be newer and larger, since you added text before
+updating it.
+
+(The reason @code{tar} does not overwrite the older file when updating
+it is because writing to the middle of a section of tape is a difficult
+process. Tapes are not designed to go backward. @xref{Media} for more
+information about tapes.
+
+@value{op-update} is not suitable for performing backups for two
+reasons: it does not change directory content entries, and it lengthens
+the archive every time it is used. The GNU @code{tar} options intended
+specifically for backups are more efficient. If you need to run
+backups, please consult @ref{Backups}.
+
+@node concatenate, delete, update, Advanced tar
+@subsection Combining Archives with @code{--concatenate}
+
+@cindex Adding archives to an archive
+@cindex Concatenating Archives
+Sometimes it may be convenient to add a second archive onto the end of
+an archive rather than adding individual files to the archive. To add
+one or more archives to the end of another archive, you should use the
+@value{op-concatenate} operation.
+
+To use @samp{--concatenate}, name the archives to be concatenated on the
+command line. (Nothing happens if you don't list any.) The members,
+and their member names, will be copied verbatim from those archives. If
+this causes multiple members to have the same name, it does not delete
+any members; all the members with the same name coexist. For
+information on how this affects reading the archive, @FIXME-ref{Multiple
+Members with the Same Name}.
+
+To demonstrate how @samp{--concatenate} works, create two small archives
+called @file{bluesrock.tar} and @file{folkjazz.tar}, using the relevant
+files from @file{practice}:
+
+@example
+$ @kbd{tar -cvf bluesrock.tar blues rock}
+blues
+classical
+$ @kbd{tar -cvf folkjazz.tar folk jazz}
+folk
+jazz
+@end example
+
+@noindent
+If you like, You can run @samp{tar --list} to make sure the archives
+contain what they are supposed to:
+
+@example
+$ @kbd{tar -tvf bluesrock.tar}
+-rw-rw-rw- melissa user 105 1997-01-21 19:42 blues
+-rw-rw-rw- melissa user 33 1997-01-20 15:34 rock
+$ @kbd{tar -tvf folkjazz.tar}
+-rw-rw-rw- melissa user 20 1996-09-23 16:44 folk
+-rw-rw-rw- melissa user 65 1997-01-30 14:15 jazz
+@end example
+
+We can concatenate these two archives with @code{tar}:
+
+@example
+$ @kbd{cd ..}
+$ @kbd{tar --concatenate --file=bluesrock.tar jazzfolk.tar}
+@end example
+
+If you now list the contents of the @file{bluesclass.tar}, you will see
+that now it also contains the archive members of @file{jazzfolk.tar}:
+
+@example
+$ @kbd{tar --list --file=bluesrock.tar}
+blues
+rock
+jazz
+folk
+@end example
+
+When you use @samp{--concatenate}, the source and target archives must
+already exist and must have been created using compatable format
+parameters (@FIXME-pxref{Matching Format Parameters}). The new,
+concatenated archive will be called by the same name as the first
+archive listed on the command line. @FIXME{is there a way to specify a
+new name?}
+
+Like @value{op-append}, this operation cannot be performed on some
+tape drives, due to deficiencies in the formats those tape drives use.
+
+@cindex @code{concatenate} vs @code{cat}
+@cindex @code{cat} vs @code{concatenate}
+It may seem more intuitive to you to want or try to use @code{cat} to
+concatenate two archives instead of using the @samp{--concatenate}
+operation; after all, @code{cat} is the utility for combining files.
+
+However, @code{tar} archives incorporate an end-of-file marker which
+must be removed if the concatenated archives are to be read properly as
+one archive. @samp{--concatenate} removes the end-of-archive marker
+from the target archive before each new archive is appended. If you use
+@code{cat} to combine the archives, the result will not be a valid
+@code{tar} format archive. If you need to retrieve files from an
+archive that was added to using the @code{cat} utility, use the
+@value{op-ignore-zeros} option. @xref{Ignore Zeros} for further
+information on dealing with archives improperly combined using the
+@code{cat} shell utility.
+
+@FIXME{this shouldn't go here. where should it go?} You must specify
+the source archives using @value{op-file} (@value{pxref-file}). If you
+do not specify the target archive, @code{tar} uses the value of the
+environment variable @code{TAPE}, or, if this has not been set, the
+default archive name.
+
+@node delete, compare, concatenate, Advanced tar
+@subsection Removing Archive Members Using @samp{--delete}
+@UNREVISED
+@cindex Deleting files from an archive
+@cindex Removing files from an archive
+
+You can remove members from an archive by using the @value{op-delete}
+option. Specify the name of the archive with @value{op-file} and then
+specify the names of the members to be deleted; if you list no member
+names, nothing will be deleted. The @value{op-verbose} option will
+cause @code{tar} to print the names of the members as they are deleted.
+As with @value{op-extract}, you must give the exact member names when
+using @samp{tar --delete}. @samp{--delete} will remove all versions of
+the named file from the archive. The @samp{--delete} operation can run
+very slowly.
+
+Unlike other operations, @samp{--delete} has no short form.
+
+@cindex Tapes, using @code{--delete} and
+@cindex Deleting from tape archives
+This operation will rewrite the archive. You can only use
+@samp{--delete} on an archive if the archive device allows you to
+write to any point on the media, such as a disk; because of this, it
+does not work on magnetic tapes. Do not try to delete an archive member
+from a magnetic tape; the action will not succeed, and you will be
+likely to scramble the archive and damage your tape. There is no safe
+way (except by completely re-writing the archive) to delete files from
+most kinds of magnetic tape. @xref{Media}.
+
+To delete all versions of the file @file{blues} from the archive
+@file{collection.tar} in the @file{practice} directory, make sure you
+are in that directory, and then,
+
+@example
+$ @kbd{tar --list --file=collection.tar}
+blues
+folk
+jazz
+rock
+practice/blues
+practice/folk
+practice/jazz
+practice/rock
+practice/blues
+$ @kbd{tar --delete --file=collection.tar blues}
+$ @kbd{tar --list --file=collection.tar}
+folk
+jazz
+rock
+$
+@end example
+
+@FIXME{I changed the order of these nodes around and haven't had a chance
+to fix the above example's results, yet. I have to play with this and
+follow it and see what it actually does!}
+
+The @value{op-delete} option has been reported to work properly when
+@code{tar} acts as a filter from @code{stdin} to @code{stdout}.
+
+@node compare, , delete, Advanced tar
+@subsection Comparing Archive Members with the File System
+@cindex Verifying the currency of an archive
+@UNREVISED
+
+The @samp{--compare} (@samp{-d}), or @samp{--diff} operation compares
+specified archive members against files with the same names, and then
+reports differences in file size, mode, owner, modification date and
+contents. You should @emph{only} specify archive member names, not file
+names. If you do not name any members, then @code{tar} will compare the
+entire archive. If a file is represented in the archive but does not
+exist in the file system, @code{tar} reports a difference.
+
+You have to specify the record size of the archive when modifying an
+archive with a non-default record size.
+
+@code{tar} ignores files in the file system that do not have
+corresponding members in the archive.
+
+The following example compares the archive members @file{rock},
+@file{blues} and @file{funk} in the archive @file{bluesrock.tar} with
+files of the same name in the file system. (Note that there is no file,
+@file{funk}; @code{tar} will report an error message.)
+
+@example
+$ @kbd{tar --compare --file=bluesrock.tar rock blues funk}
+rock
+blues
+tar: funk not found in archive
+@end example
+
+@noindent
+@FIXME{what does this actually depend on? i'm making a guess,
+here.}Depending on the system where you are running @code{tar} and the
+version you are running, @code{tar} may have a different error message,
+such as:
+
+@example
+funk: does not exist
+@end example
+
+@FIXME-xref{somewhere, for more information about format parameters.
+Melissa says: such as "format variations"? But why? Clearly I don't
+get it yet; I'll deal when I get to that section.}
+
+The spirit behind the @value{op-compare} option is to check whether the
+archive represents the current state of files on disk, more than validating
+the integrity of the archive media. For this later goal, @xref{verify}.
+
+@node extract options, backup, Advanced tar, operations
+@section Options Used by @code{--extract}
+@UNREVISED
+
+@FIXME{i need to get dan to go over these options with me and see if
+there's a better way of organizing them.}
+
+The previous chapter showed how to use @value{op-extract} to extract
+an archive into the filesystem. Various options cause @code{tar} to
+extract more information than just file contents, such as the owner,
+the permissions, the modification date, and so forth. This section
+presents options to be used with @samp{--extract} when certain special
+considerations arise. You may review the information presented in
+@ref{extract} for more basic information about the
+@samp{--extract} operation.
+
+@menu
+* Reading:: Options to Help Read Archives
+* Writing:: Changing How @code{tar} Writes Files
+* Scarce:: Coping with Scarce Resources
+@end menu
+
+@node Reading, Writing, extract options, extract options
+@subsection Options to Help Read Archives
+@cindex Options when reading archives
+@cindex Reading incomplete records
+@cindex Records, incomplete
+@cindex End-of-archive entries, ignoring
+@cindex Ignoring end-of-archive entries
+@cindex Large lists of file names on small machines
+@cindex Small memory
+@cindex Running out of space
+@UNREVISED
+
+Normally, @code{tar} will request data in full record increments from
+an archive storage device. If the device cannot return a full record,
+@code{tar} will report an error. However, some devices do not always
+return full records, or do not require the last record of an archive to
+be padded out to the next record boundary. To keep reading until you
+obtain a full record, or to accept an incomplete record if it contains
+an end-of-archive marker, specify the @value{op-read-full-records} option
+in conjunction with the @value{op-extract} or @value{op-list} operations.
+@value{xref-read-full-records}.
+
+The @value{op-read-full-records} option is turned on by default when
+@code{tar} reads an archive from standard input, or from a remote
+machine. This is because on BSD Unix systems, attempting to read a
+pipe returns however much happens to be in the pipe, even if it is
+less than was requested. If this option were not enabled, @code{tar}
+would fail as soon as it read an incomplete record from the pipe.
+
+If you're not sure of the blocking factor of an archive, you can
+read the archive by specifying @value{op-read-full-records} and
+@value{op-blocking-factor}, using a blocking factor larger than what the
+archive uses. This lets you avoid having to determine the blocking factor
+of an archive. @value{xref-blocking-factor}.
+
+@menu
+* read full records::
+* Ignore Zeros::
+* Ignore Failed Read::
+@end menu
+
+@node read full records, Ignore Zeros, Reading, Reading
+@unnumberedsubsubsec Reading Full Records
+
+@FIXME{need sentence or so of intro here}
+
+@table @kbd
+@item --read-full-records
+@item -B
+Use in conjunction with @value{op-extract} to read an archive which
+contains incomplete records, or one which has a blocking factor less
+than the one specified.
+@end table
+
+@node Ignore Zeros, Ignore Failed Read, read full records, Reading
+@unnumberedsubsubsec Ignoring Blocks of Zeros
+
+Normally, @code{tar} stops reading when it encounters a block of zeros
+between file entries (which usually indicates the end of the archive).
+@value{op-ignore-zeros} allows @code{tar} to completely read an archive
+which contains a block of zeros before the end (i.e.@: a damaged
+archive, or one which was created by @code{cat}-ing several archives
+together).
+
+The @value{op-ignore-zeros} option is turned off by default because many
+versions of @code{tar} write garbage after the end-of-archive entry,
+since that part of the media is never supposed to be read. GNU
+@code{tar} does not write after the end of an archive, but seeks to
+maintain compatablity among archiving utilities.
+
+@table @kbd
+@item --ignore-zeros
+@itemx -i
+To ignore blocks of zeros (ie.@: end-of-archive entries) which may be
+encountered while reading an archive. Use in conjunction with
+@value{op-extract} or @value{op-list}.
+@end table
+
+@node Ignore Failed Read, , Ignore Zeros, Reading
+@unnumberedsubsubsec Ignore Fail Read
+
+@FIXME{Is this in the right place? It doesn't exist anywhere else in
+the book (except the appendix), and has no further explanation. For that
+matter, what does it mean?!}
+
+@table @kbd
+@item --ignore-failed-read
+Do not exit with nonzero on unreadable files or directories.
+@end table
+
+@node Writing, Scarce, Reading, extract options
+@subsection Changing How @code{tar} Writes Files
+@cindex Overwriting old files, prevention
+@cindex Protecting old files
+@cindex Modification times of extracted files
+@cindex Permissions of extracted files
+@cindex Modes of extracted files
+@cindex Writing extracted files to standard output
+@cindex Standard output, writing extracted files to
+@UNREVISED
+
+@FIXME{need to mention the brand new option, --backup}
+
+@menu
+* Prevention Overwriting::
+* Keep Old Files::
+* Unlink First::
+* Recursive Unlink::
+* Modification Times::
+* Setting Access Permissions::
+* Writing to Standard Output::
+* remove files::
+@end menu
+
+@node Prevention Overwriting, Keep Old Files, Writing, Writing
+@unnumberedsubsubsec Options to Prevent Overwriting Files
+
+Normally, @code{tar} writes extracted files into the file system without
+regard to the files already on the system; i.e., files with the same
+names as archive members are overwritten when the archive is extracted.
+If the name of a corresponding file name is a symbolic link, the file
+pointed to by the symbolic link will be overwritten instead of the
+symbolic link itself (if this is possible). Moreover, special devices,
+empty directories and even symbolic links are automatically removed if
+they are found to be on the way of the proper extraction.
+
+To prevent @code{tar} from extracting an archive member from an archive
+if doing so will overwrite a file in the file system, use
+@value{op-keep-old-files} in conjunction with @samp{--extract}. When
+this option is specified, @code{tar} will report an error stating the
+name of the files in conflict instead of overwriting the file with the
+corresponding extracted archive member.
+
+@FIXME{these two P's have problems. i don't understand what they're
+trying to talk about well enough to fix them; i may have just made them
+worse (in particular the first of the two). waiting to talk with hag.}
+
+The @value{op-unlink-first} option removes existing files, symbolic links,
+empty directories, devices, etc., @emph{prior} to extracting over them.
+In particular, using this option will prevent replacing an already existing
+symbolic link by the name of an extracted file, since the link itself
+is removed prior to the extraction, rather than the file it points to.
+On some systems, the backing store for the executable @emph{is} the
+original program text. You could use the @value{op-unlink-first} option
+to prevent segmentation violations or other woes when extracting arbitrary
+executables over currently running copies. Note that if something goes
+wrong with the extraction and you @emph{did} use this option, you might
+end up with no file at all. Without this option, if something goes wrong
+with the extraction, the existing file is not overwritten and preserved.
+
+@FIXME{huh?} If you specify the @value{op-recursive-unlink} option,
+@code{tar} removes @emph{anything} that keeps you from extracting a file
+as far as current permissions will allow it. This could include removal
+of the contents of a full directory hierarchy. For example, someone
+using this feature may be very surprised at the results when extracting
+a directory entry from the archive. This option can be dangerous; be
+very aware of what you are doing if you choose to use it.
+
+@menu
+* Keep Old Files::
+* Unlink First::
+* Recursive Unlink::
+@end menu
+
+@node Keep Old Files, Unlink First, Prevention Overwriting, Writing
+@unnumberedsubsubsec Keep Old Files
+
+@table @kbd
+@item --keep-old-files
+@itemx -k
+Do not overwrite existing files from archive. The
+@value{op-keep-old-files} option prevents @code{tar} from over-writing
+existing files with files with the same name from the archive.
+The @value{op-keep-old-files} option is meaningless with @value{op-list}.
+Prevents @code{tar} from overwriting files in the file system during
+extraction.
+@end table
+
+@node Unlink First, Recursive Unlink, Keep Old Files, Writing
+@unnumberedsubsubsec Unlink First
+
+@table @kbd
+@item --unlink-first
+@itemx -U
+Try removing files before extracting over them, instead of trying to
+overwrite them.
+@end table
+
+@node Recursive Unlink, Modification Times, Unlink First, Writing
+@unnumberedsubsubsec Recursive Unlink
+
+@table @kbd
+@item --recursive-unlink
+When this option is specified, try removing files and directory hierarchies
+before extracting over them. @emph{This is a dangerous option!}
+@end table
+
+Some people argue that GNU @code{tar} should not hesitate to overwrite
+files with other files when extracting. When extracting a @code{tar}
+archive, they expect to see a faithful copy of the state of the filesystem
+when the archive was created. It is debatable that this would always
+be a proper behaviour. For example, suppose one has an archive in
+which @file{usr/local} is a link to @file{usr/local2}. Since then,
+maybe the site removed the link and renamed the whole hierarchy from
+@file{/usr/local2} to @file{/usr/local}. Such things happen all the time.
+I guess it would not be welcome at all that GNU @code{tar} removes the
+whole hierarchy just to make room for the link to be reinstated (unless it
+@emph{also} simultaneously restores the full @file{/usr/local2}, of course!
+GNU @code{tar} is indeed able to remove a whole hierarchy to reestablish a
+symbolic link, for example, but @emph{only if} @value{op-recursive-unlink}
+is specified to allow this behaviour. In any case, single files are
+silently removed.
+
+@node Modification Times, Setting Access Permissions, Recursive Unlink, Writing
+@unnumberedsubsubsec Setting Modification Times
+
+Normally, @code{tar} sets the modification times of extracted files to
+the modification times recorded for the files in the archive, but
+limits the permissions of extracted files by the current @code{umask}
+setting.
+
+To set the modification times of extracted files to the time when
+the files were extracted, use the @value{op-touch} option in
+conjunction with @value{op-extract}.
+
+@table @kbd
+@item --touch
+@itemx -m
+Sets the modification time of extracted archive members to the time
+they were extracted, not the time recorded for them in the archive.
+Use in conjunction with @value{op-extract}.
+@end table
+
+@node Setting Access Permissions, Writing to Standard Output, Modification Times, Writing
+@unnumberedsubsubsec Setting Access Permissions
+
+To set the modes (access permissions) of extracted files to those
+recorded for those files in the archive, use @samp{--same-persmissions}
+in conjunction with the @value{op-extract} operation. @FIXME{Should be
+aliased to ignore-umask.}
+
+@table @kbd
+@item --preserve-permission
+@itemx --same-permission
+@itemx --ignore-umask
+@itemx -p
+Set modes of extracted archive members to those recorded in the
+archive, instead of current umask settings. Use in conjunction with
+@value{op-extract}.
+@end table
+
+@FIXME{Following paragraph needs to be rewritten: why doesnt' this cat
+files together, why is this useful. is it really useful with
+more than one file?}
+
+@node Writing to Standard Output, remove files, Setting Access Permissions, Writing
+@unnumberedsubsubsec Writing to Standard Output
+
+To write the extracted files to the standard output, instead of
+creating the files on the file system, use @value{op-to-stdout} in
+conjunction with @value{op-extract}. This option is useful if you are
+extracting files to send them through a pipe, and do not need to
+preserve them in the file system. If you extract multiple members,
+they appear on standard output concatenated, in the order they are
+found in the archive.
+
+@table @kbd
+@item --to-stdout
+@itemx -O
+Writes files to the standard output. Used in conjunction with
+@value{op-extract}. Extract files to standard output. When this option
+is used, instead of creating the files specified, @code{tar} writes
+the contents of the files extracted to its standard output. This may
+be useful if you are only extracting the files in order to send them
+through a pipe. This option is meaningless with @value{op-list}.
+@end table
+
+@FIXME{Why would you want to do such a thing, how are files separated on
+the standard output? is this useful with more that one file? Are
+pipes the real reason?}
+
+@node remove files, , Writing to Standard Output, Writing
+@unnumberedsubsubsec Removing Files
+
+@FIXME{the various macros in the front of the manual think that this
+option goes in this section. i have no idea; i only know it's nowhere
+else in the book...}
+
+@table @kbd
+@item --remove-files
+Remove files after adding them to the archive.
+@end table
+
+@node Scarce, , Writing, extract options
+@subsection Coping with Scarce Resources
+@cindex Middle of the archive, starting in the
+@cindex Running out of space during extraction
+@cindex Disk space, running out of
+@cindex Space on the disk, recovering from lack of
+@UNREVISED
+
+@menu
+* Starting File::
+* Same Order::
+@end menu
+
+@node Starting File, Same Order, Scarce, Scarce
+@unnumberedsubsubsec Starting File
+
+@table @kbd
+@item --starting-file=@var{name}
+@itemx -K @var{name}
+Starts an operation in the middle of an archive. Use in conjunction
+with @value{op-extract} or @value{op-list}.
+@end table
+
+If a previous attempt to extract files failed due to lack of disk
+space, you can use @value{op-starting-file} to start extracting only
+after member @var{name} of the archive. This assumes, of course, that
+there is now free space, or that you are now extracting into a
+different file system. (You could also choose to suspend @code{tar},
+remove unnecessary files from the file system, and then restart the
+same @code{tar} operation. In this case, @value{op-starting-file} is
+not necessary. @value{xref-incremental}, @value{xref-interactive},
+and @value{ref-exclude}.)
+
+@node Same Order, , Starting File, Scarce
+@unnumberedsubsubsec Same Order
+
+@table @kbd
+@item --same-order
+@itemx --preserve-order
+@itemx -s
+To process large lists of file names on machines with small amounts of
+memory. Use in conjunction with @value{op-compare},
+@value{op-list}
+or @value{op-extract}.
+@end table
+
+@FIXME{we don't need/want --preserve to exist any more (from melissa:
+ie, don't want that *version* of the option to exist, or don't want
+the option to exist in either version?}
+
+@FIXME{i think this explanation is lacking.}
+
+The @value{op-same-order} option tells @code{tar} that the list of file
+names to be listed or extracted is sorted in the same order as the
+files in the archive. This allows a large list of names to be used,
+even on a small machine that would not otherwise be able to hold all
+the names in memory at the same time. Such a sorted list can easily be
+created by running @samp{tar -t} on the archive and editing its output.
+
+This option is probably never needed on modern computer systems.
+
+@node backup, Applications, extract options, operations
+@section Backup options
+
+@cindex backup options
+
+GNU @code{tar} offers options for making backups of files before writing
+new versions. These options control the details of these backups.
+They may apply to the archive itself before it is created or rewritten,
+as well as individual extracted members. Other GNU programs (@code{cp},
+@code{install}, @code{ln}, and @code{mv}, for example) offer similar
+options.
+
+Backup options may prove unexpectedly useful when extracting archives
+containing many members having identical name, or when extracting archives
+on systems having file name limitations, making different members appear
+has having similar names through the side-effect of name truncation.
+(This is true only if we have a good scheme for truncated backup names,
+which I'm not sure at all: I suspect work is needed in this area.)
+When any existing file is backed up before being overwritten by extraction,
+then clashing files are automatically be renamed to be unique, and the
+true name is kept for only the last file of a series of clashing files.
+By using verbose mode, users may track exactly what happens.
+
+At the detail level, some decisions are still experimental, and may
+change in the future, we are waiting comments from our users. So, please
+do not learn to depend blindly on the details of the backup features.
+For example, currently, directories themselves are never renamed through
+using these options, so, extracting a file over a directory still has
+good chances to fail. Also, backup options apply to created archives,
+not only to extracted members. For created archives, backups will not
+be attempted when the archive is a block or character device, or when it
+refers to a remote file.
+
+For the sake of simplicity and efficiency, backups are made by renaming old
+files prior to creation or extraction, and not by copying. The original
+name is restored if the file creation fails. If a failure occurs after a
+partial extraction of a file, both the backup and the partially extracted
+file are kept.
+
+@table @samp
+
+@item --backup
+@opindex --backup
+@cindex backups, making
+Make backups of files that are about to be overwritten or removed.
+Without this option, the original versions are destroyed.
+
+@item --suffix=@var{suffix}
+@opindex --suffix
+@cindex backup suffix
+@vindex SIMPLE_BACKUP_SUFFIX
+Append @var{suffix} to each backup file made with @samp{-b}. If this
+option is not specified, the value of the @code{SIMPLE_BACKUP_SUFFIX}
+environment variable is used. And if @code{SIMPLE_BACKUP_SUFFIX} is not
+set, the default is @samp{~}, just as in Emacs.
+
+@item --version-control=@var{method}
+@opindex --version-control
+@vindex VERSION_CONTROL
+@cindex backup files, type made
+Use @var{method} to determine the type of backups made with @value{op-backup}.
+If this option is not specified, the value of the @code{VERSION_CONTROL}
+environment variable is used. And if @code{VERSION_CONTROL} is not set,
+the default backup type is @samp{existing}.
+
+@vindex version-control @r{Emacs variable}
+This option corresponds to the Emacs variable @samp{version-control};
+the same values for @var{method} are accepted as in Emacs. This options
+also more descriptive name. The valid @var{method}s (unique
+abbreviations are accepted):
+
+@table @samp
+@item t
+@itemx numbered
+@opindex numbered @r{backup method}
+Always make numbered backups.
+
+@item nil
+@itemx existing
+@opindex existing @r{backup method}
+Make numbered backups of files that already have them, simple backups
+of the others.
+
+@item never
+@itemx simple
+@opindex simple @r{backup method}
+Always make simple backups.
+
+@end table
+
+@end table
+
+Some people express the desire to @emph{always} use the @var{op-backup}
+option, by defining some kind of alias or script. This is not as easy
+as one may thing, due to the fact old style options should appear first
+and consume arguments a bit inpredictably for an alias or script. But,
+if you are ready to give up using old style options, you may resort to
+using something like (a Bourne shell function here):
+
+@example
+tar () @{ /usr/local/bin/tar --backup $*; @}
+@end example
+
+@node Applications, looking ahead, backup, operations
+@section Notable @code{tar} Usages
+@UNREVISED
+
+@FIXME{Using Unix file linking capability to recreate directory
+structures---linking files into one subdirectory and then
+@code{tar}ring that directory.}
+
+@FIXME{Nice hairy example using absolute-names, newer, etc.}
+
+@findex uuencode
+You can easily use archive files to transport a group of files from
+one system to another: put all relevant files into an archive on one
+computer system, transfer the archive to another system, and extract
+the contents there. The basic transfer medium might be magnetic tape,
+Internet FTP, or even electronic mail (though you must encode the
+archive with @code{uuencode} in order to transport it properly by
+mail). Both machines do not have to use the same operating system, as
+long as they both support the @code{tar} program.
+
+For example, here is how you might copy a directory's contents from
+one disk to another, while preserving the dates, modes, owners and
+link-structure of all the files therein. In this case, the transfer
+medium is a @dfn{pipe}, which is one a Unix redirection mechanism:
+
+@smallexample
+$ @kbd{cd sourcedir; tar -cf - . | (cd targetdir; tar -xf -)}
+@end smallexample
+
+@noindent
+The command also works using short option forms:
+
+@FIXME{The following using standard input/output correct??}
+@smallexample
+$ @w{@kbd{cd sourcedir; tar --create --file=- . | (cd targetdir; tar --extract --file=-)}}
+@end smallexample
+
+@noindent
+This is one of the easiest methods to transfer a @code{tar} archive.
+
+@node looking ahead, , Applications, operations
+@section Looking Ahead: The Rest of this Manual
+
+You have now seen how to use all eight of the operations available to
+@code{tar}, and a number of the possible options. The next chapter
+explains how to choose and change file and archive names, how to use
+files to store names of other files which you can then call as
+arguments to @code{tar} (this can help you save time if you expect to
+archive the same list of files a number of times), and how to
+@FIXME{in case it's not obvious, i'm making this up in some sense
+based on my imited memory of what the next chapter *really* does. i
+just wanted to flesh out this final section a little bit so i'd
+remember to sitck it in here. :-)}
+
+If there are too many files to conveniently list on the command line,
+you can list the names in a file, and @code{tar} will read that file.
+@value{xref-files-from}.
+
+There are various ways of causing @code{tar} to skip over some files,
+and not archive them. @xref{Choosing}.
+
+@node Backups, Choosing, operations, Top
+@chapter Performing Backups and Restoring Files
+@UNREVISED
+
+GNU @code{tar} is distributed along with the scripts which the Free
+Software Foundation uses for performing backups. There is no corresponding
+scripts available yet for doing restoration of files. Even if there is
+a good chance those scripts may be satisfying to you, they are not the
+only scripts or methods available for doing backups and restore. You may
+well create your own, or use more sophisticated packages dedicated to
+that purpose.
+
+Some users are enthusiastic about @code{Amanda} (The Advanced Maryland
+Automatic Network Disk Archiver), a backup system developed by James
+da Silva @file{jds@@cs.umd.edu} and available on many Unix systems.
+This is free software, and it is available at these places:
+
+@example
+http://www.cs.umd.edu/projects/amanda/amanda.html
+ftp://ftp.cs.umd.edu/pub/amanda
+@end example
+
+@ifclear PUBLISH
+
+Here is a possible plan for a future documentation about the backuping
+scripts which are provided within the GNU @code{tar} distribution.
+
+@example
+.* dumps
+. + what are dumps
+
+. + different levels of dumps
+. - full dump = dump everything
+. - level 1, level 2 dumps etc, -
+ A level n dump dumps everything changed since the last level
+ n-1 dump (?)
+
+. + how to use scripts for dumps (ie, the concept)
+. - scripts to run after editing backup specs (details)
+
+. + Backup Specs, what is it.
+. - how to customize
+. - actual text of script [/sp/dump/backup-specs]
+
+. + Problems
+. - rsh doesn't work
+. - rtape isn't installed
+. - (others?)
+
+. + the --incremental option of tar
+
+. + tapes
+. - write protection
+. - types of media
+. : different sizes and types, useful for different things
+. - files and tape marks
+ one tape mark between files, two at end.
+. - positioning the tape
+ MT writes two at end of write,
+ backspaces over one when writing again.
+@end example
+
+@end ifclear
+
+This chapter documents both the provided FSF scripts and @code{tar}
+options which are more specific to usage as a backup tool.
+
+To @dfn{back up} a file system means to create archives that contain
+all the files in that file system. Those archives can then be used to
+restore any or all of those files (for instance if a disk crashes or a
+file is accidently deleted). File system @dfn{backups} are also
+called @dfn{dumps}.
+
+@menu
+* Full Dumps:: Using @code{tar} to Perform Full Dumps
+* Inc Dumps:: Using @code{tar} to Perform Incremental Dumps
+* incremental and listed-incremental:: The Incremental Options
+* Backup Levels:: Levels of Backups
+* Backup Parameters:: Setting Parameters for Backups and Restoration
+* Scripted Backups:: Using the Backup Scripts
+* Scripted Restoration:: Using the Restore Script
+@end menu
+
+@node Full Dumps, Inc Dumps, Backups, Backups
+@section Using @code{tar} to Perform Full Dumps
+@UNREVISED
+
+@cindex full dumps
+@cindex dumps, full
+
+@cindex corrupted archives
+Full dumps should only be made when no other people or programs
+are modifying files in the filesystem. If files are modified while
+@code{tar} is making the backup, they may not be stored properly in
+the archive, in which case you won't be able to restore them if you
+have to. (Files not being modified are written with no trouble, and do
+not corrupt the entire archive.)
+
+You will want to use the @value{op-label} option to give the archive a
+volume label, so you can tell what this archive is even if the label
+falls off the tape, or anything like that.
+
+Unless the filesystem you are dumping is guaranteed to fit on
+one volume, you will need to use the @value{op-multi-volume} option.
+Make sure you have enough tapes on hand to complete the backup.
+
+If you want to dump each filesystem separately you will need to use
+the @value{op-one-file-system} option to prevent @code{tar} from crossing
+filesystem boundaries when storing (sub)directories.
+
+The @value{op-incremental} option is not needed, since this is a complete
+copy of everything in the filesystem, and a full restore from this
+backup would only be done onto a completely empty disk.
+
+Unless you are in a hurry, and trust the @code{tar} program (and your
+tapes), it is a good idea to use the @value{op-verify} option, to make
+sure your files really made it onto the dump properly. This will
+also detect cases where the file was modified while (or just after)
+it was being archived. Not all media (notably cartridge tapes) are
+capable of being verified, unfortunately.
+
+@value{op-listed-incremental} take a file name argument always. If the
+file doesn't exist, run a level zero dump, creating the file. If the
+file exists, uses that file to see what has changed.
+
+@value{op-incremental} @FIXME{look it up}
+
+@value{op-incremental} handle old GNU-format incremental backup.
+
+This option should only be used when creating an incremental backup of
+a filesystem. When the @value{op-incremental} option is used, @code{tar}
+writes, at the beginning of the archive, an entry for each of the
+directories that will be operated on. The entry for a directory
+includes a list of all the files in the directory at the time the
+dump was done, and a flag for each file indicating whether the file
+is going to be put in the archive. This information is used when
+doing a complete incremental restore.
+
+Note that this option causes @code{tar} to create a non-standard
+archive that may not be readable by non-GNU versions of the @code{tar}
+program.
+
+The @value{op-incremental} option means the archive is an incremental
+backup. Its meaning depends on the command that it modifies.
+
+If the @value{op-incremental} option is used with @value{op-list}, @code{tar}
+will list, for each directory in the archive, the list of files in
+that directory at the time the archive was created. This information
+is put out in a format that is not easy for humans to read, but which
+is unambiguous for a program: each file name is preceded by either a
+@samp{Y} if the file is present in the archive, an @samp{N} if the
+file is not included in the archive, or a @samp{D} if the file is
+a directory (and is included in the archive). Each file name is
+terminated by a null character. The last file is followed by an
+additional null and a newline to indicate the end of the data.
+
+If the @value{op-incremental} option is used with @value{op-extract}, then
+when the entry for a directory is found, all files that currently
+exist in that directory but are not listed in the archive @emph{are
+deleted from the directory}.
+
+This behavior is convenient when you are restoring a damaged file
+system from a succession of incremental backups: it restores the
+entire state of the file system to that which obtained when the backup
+was made. If you don't use @value{op-incremental}, the file system will
+probably fill up with files that shouldn't exist any more.
+
+@value{op-listed-incremental} handle new GNU-format incremental backup.
+This option handles new GNU-format incremental backup. It has much the
+same effect as @value{op-incremental}, but also the time when the dump
+is done and the list of directories dumped is written to the given
+@var{file}. When restoring, only files newer than the saved time are
+restored, and the direcotyr list is used to speed up operations.
+
+@value{op-listed-incremental} acts like @value{op-incremental}, but when
+used in conjunction with @value{op-create} will also cause @code{tar} to
+use the file @var{file}, which contains information about the state
+of the filesystem at the time of the last backup, to decide which
+files to include in the archive being created. That file will then
+be updated by @code{tar}. If the file @var{file} does not exist when
+this option is specified, @code{tar} will create it, and include all
+appropriate files in the archive.
+
+The file, which is archive independent, contains the date it was last
+modified and a list of devices, inode numbers and directory names.
+@code{tar} will archive files with newer mod dates or inode change
+times, and directories with an unchanged inode number and device but
+a changed directory name. The file is updated after the files to
+be archived are determined, but before the new archive is actually
+created.
+
+GNU @code{tar} actually writes the file twice: once before the data
+and written, and once after.
+
+@node Inc Dumps, incremental and listed-incremental, Full Dumps, Backups
+@section Using @code{tar} to Perform Incremental Dumps
+@UNREVISED
+
+@cindex incremental dumps
+@cindex dumps, incremental
+
+Performing incremental dumps is similar to performing full dumps,
+although a few more options will usually be needed.
+
+You will need to use the @samp{-N @var{date}} option to tell @code{tar}
+to only store files that have been modified since @var{date}.
+@var{date} should be the date and time of the last full/incremental
+dump.
+
+A standard scheme is to do a @emph{monthly} (full) dump once a month,
+a @emph{weekly} dump once a week of everything since the last monthly
+and a @emph{daily} every day of everything since the last (weekly or
+monthly) dump.
+
+Here is a copy of the script used to dump the filesystems of the
+machines here at the Free Software Foundation. This script is run via
+@code{cron} late at night when people are least likely to be using the
+machines. This script dumps several filesystems from several machines
+at once (via NFS). The operator is responsible for ensuring that all
+the machines will be up at the time the dump happens. If a machine is
+not running, its files will not be dumped, and the next day's
+incremental dump will @emph{not} store files that would have gone onto
+that dump.
+
+@example
+#!/bin/csh
+# Dump thingie
+set now = `date`
+set then = `cat date.nfs.dump`
+/u/hack/bin/tar -c -G -v\
+ -f /dev/rtu20\
+ -b 126\
+ -N "$then"\
+ -V "Dump from $then to $now"\
+ /alpha-bits/gp\
+ /gnu/hack\
+ /hobbes/u\
+ /spiff/u\
+ /sugar-bombs/u
+echo $now > date.nfs.dump
+mt -f /dev/rtu20 rew
+@end example
+
+Output from this script is stored in a file, for the operator to
+read later.
+
+This script uses the file @file{date.nfs.dump} to store the date/time
+of the last dump.
+
+Since this is a streaming tape drive, no attempt to verify the archive
+is done. This is also why the high blocking factor (126) is used.
+The tape drive must also be rewound by the @code{mt} command after
+the dump is made.
+
+@node incremental and listed-incremental, Backup Levels, Inc Dumps, Backups
+@section The Incremental Options
+@UNREVISED
+
+@value{op-incremental} is used in conjunction with @value{op-create},
+@value{op-extract} or @value{op-list} when backing up and restoring file
+systems. An archive cannot be extracted or listed with the
+@value{op-incremental} option specified unless it was created with the
+option specified. This option should only be used by a script, not by
+the user, and is usually disregarded in favor of
+@value{op-listed-incremental}, which is described below.
+
+@value{op-incremental} in conjunction with @value{op-create} causes
+@code{tar} to write, at the beginning of the archive, an entry for
+each of the directories that will be archived. The entry for a
+directory includes a list of all the files in the directory at the
+time the archive was created and a flag for each file indicating
+whether or not the file is going to be put in the archive.
+
+Note that this option causes @code{tar} to create a non-standard
+archive that may not be readable by non-GNU versions of the @code{tar}
+program.
+
+@value{op-incremental} in conjunction with @value{op-extract} causes
+@code{tar} to read the lists of directory contents previously stored
+in the archive, @emph{delete} files in the file system that did not
+exist in their directories when the archive was created, and then
+extract the files in the archive.
+
+This behavior is convenient when restoring a damaged file system from
+a succession of incremental backups: it restores the entire state of
+the file system to that which obtained when the backup was made. If
+@value{op-incremental} isn't specified, the file system will probably
+fill up with files that shouldn't exist any more.
+
+@value{op-incremental} in conjunction with @value{op-list}, causes
+@code{tar} to print, for each directory in the archive, the list of
+files in that directory at the time the archive was created. This
+information is put out in a format that is not easy for humans to
+read, but which is unambiguous for a program: each file name is
+preceded by either a @samp{Y} if the file is present in the archive,
+an @samp{N} if the file is not included in the archive, or a @samp{D}
+if the file is a directory (and is included in the archive). Each
+file name is terminated by a null character. The last file is followed
+by an additional null and a newline to indicate the end of the data.
+
+@value{op-listed-incremental} acts like @value{op-incremental}, but when
+used in conjunction with @value{op-create} will also cause @code{tar}
+to use the file @var{snapshot-file}, which contains information about
+the state of the file system at the time of the last backup, to decide
+which files to include in the archive being created. That file will
+then be updated by @code{tar}. If the file @var{file} does not exist
+when this option is specified, @code{tar} will create it, and include
+all appropriate files in the archive.
+
+The file @var{file}, which is archive independent, contains the date
+it was last modified and a list of devices, inode numbers and
+directory names. @code{tar} will archive files with newer mod dates
+or inode change times, and directories with an unchanged inode number
+and device but a changed directory name. The file is updated after
+the files to be archived are determined, but before the new archive is
+actually created.
+
+Despite it should be obvious that a device has a non-volatile value, NFS
+devices have non-dependable values when an automounter gets in the picture.
+This led to a great deal of spurious redumping in incremental dumps,
+so it is somewhat useless to compare two NFS devices numbers over time.
+So @code{tar} now considers all NFS devices as being equal when it comes
+to comparing directories; this is fairly gross, but there does not seem
+to be a better way to go.
+
+@FIXME{this section needs to be written}
+
+@node Backup Levels, Backup Parameters, incremental and listed-incremental, Backups
+@section Levels of Backups
+@UNREVISED
+
+An archive containing all the files in the file system is called a
+@dfn{full backup} or @dfn{full dump}. You could insure your data by
+creating a full dump every day. This strategy, however, would waste a
+substantial amount of archive media and user time, as unchanged files
+are daily re-archived.