+@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.
+
+It is more efficient to do a full dump only occasionally. To back up
+files between full dumps, you can a incremental dump. A @dfn{level
+one} dump archives all the files that have changed since the last full
+dump.
+
+A typical dump strategy would be to perform a full dump once a week,
+and a level one dump once a day. This means some versions of files
+will in fact be archived more than once, but this dump strategy makes
+it possible to restore a file system to within one day of accuracy by
+only extracting two archives---the last weekly (full) dump and the
+last daily (level one) dump. The only information lost would be in
+files changed or created since the last daily backup. (Doing dumps
+more than once a day is usually not worth the trouble).
+
+GNU @code{tar} comes with scripts you can use to do full and level-one
+dumps. Using scripts (shell programs) to perform backups and
+restoration is a convenient and reliable alternative to typing out
+file name lists and @code{tar} commands by hand.
+
+Before you use these scripts, you need to edit the file
+@file{backup-specs}, which specifies parameters used by the backup
+scripts and by the restore script. @FIXME{There is no such restore
+script!}. @FIXME-xref{Script Syntax}. Once the backup parameters
+are set, you can perform backups or restoration by running the
+appropriate script.
+
+The name of the restore script is @code{restore}. @FIXME{There is
+no such restore script!}. The names of the level one and full backup
+scripts are, respectively, @code{level-1} and @code{level-0}.
+The @code{level-0} script also exists under the name @code{weekly}, and
+the @code{level-1} under the name @code{daily}---these additional names
+can be changed according to your backup schedule. @FIXME-xref{Scripted
+Restoration}, for more information on running the restoration script.
+@FIXME-xref{Scripted Backups}, for more information on running the
+backup scripts.
+
+@emph{Please Note:} The backup scripts and the restoration scripts are
+designed to be used together. While it is possible to restore files by
+hand from an archive which was created using a backup script, and to create
+an archive by hand which could then be extracted using the restore script,
+it is easier to use the scripts. @FIXME{There is no such restore script!}.
+@value{xref-incremental}, and @value{xref-listed-incremental},
+before making such an attempt.
+
+@FIXME{shorten node names}
+
+@node Backup Parameters, Scripted Backups, Backup Levels, Backups
+@section Setting Parameters for Backups and Restoration
+@UNREVISED
+
+The file @file{backup-specs} specifies backup parameters for the
+backup and restoration scripts provided with @code{tar}. You must
+edit @file{backup-specs} to fit your system configuration and schedule
+before using these scripts.
+
+@FIXME{This about backup scripts needs to be written: BS is a shell
+script .... thus ... @file{backup-specs} is in shell script syntax.}
+
+@FIXME-xref{Script Syntax}, for an explanation of this syntax.
+
+@FIXME{Whats a parameter .... looked at by the backup scripts
+... which will be expecting to find ... now syntax ... value is linked
+to lame ... @file{backup-specs} specifies the following parameters:}
+
+@table @samp
+@item ADMINISTRATOR
+The user name of the backup administrator.
+
+@item BACKUP_HOUR
+The hour at which the backups are done. This can be a number from 0
+to 23, or the string @samp{now}.
+
+@item TAPE_FILE
+The device @code{tar} writes the archive to. This device should be
+attached to the host on which the dump scripts are run.
+
+@FIXME{examples for all ...}
+
+@item TAPE_STATUS
+The command to use to obtain the status of the archive device,
+including error count. On some tape drives there may not be such a
+command; in that case, simply use `TAPE_STATUS=false'.
+
+@item BLOCKING
+The blocking factor @code{tar} will use when writing the dump archive.
+@value{xref-blocking-factor}.
+
+@item BACKUP_DIRS
+A list of file systems to be dumped. You can include any directory
+name in the list---subdirectories on that file system will be
+included, regardless of how they may look to other networked machines.
+Subdirectories on other file systems will be ignored.
+
+The host name specifies which host to run @code{tar} on, and should
+normally be the host that actually contains the file system. However,
+the host machine must have GNU @code{tar} installed, and must be able
+to access the directory containing the backup scripts and their
+support files using the same file name that is used on the machine
+where the scripts are run (ie. what @code{pwd} will print when in that
+directory on that machine). If the host that contains the file system
+does not have this capability, you can specify another host as long as
+it can access the file system through NFS.
+
+@item BACKUP_FILES
+A list of individual files to be dumped. These should be accessible
+from the machine on which the backup script is run.
+
+@FIXME{Same file name, be specific. Through NFS ...}
+
+@end table
+
+@menu
+* backup-specs example:: An Example Text of @file{Backup-specs}
+* Script Syntax:: Syntax for @file{Backup-specs}
+@end menu
+
+@node backup-specs example, Script Syntax, Backup Parameters, Backup Parameters
+@subsection An Example Text of @file{Backup-specs}
+@UNREVISED
+
+The following is the text of @file{backup-specs} as it appears at FSF:
+
+@example
+# site-specific parameters for file system backup.
+
+ADMINISTRATOR=friedman
+BACKUP_HOUR=1
+TAPE_FILE=/dev/nrsmt0
+TAPE_STATUS="mts -t $TAPE_FILE"
+BLOCKING=124
+BACKUP_DIRS="
+ albert:/fs/fsf
+ apple-gunkies:/gd
+ albert:/fs/gd2
+ albert:/fs/gp
+ geech:/usr/jla
+ churchy:/usr/roland
+ albert:/
+ albert:/usr
+ apple-gunkies:/
+ apple-gunkies:/usr
+ gnu:/hack
+ gnu:/u
+ apple-gunkies:/com/mailer/gnu
+ apple-gunkies:/com/archive/gnu"
+
+BACKUP_FILES="/com/mailer/aliases /com/mailer/league*[a-z]"
+
+@end example
+
+@node Script Syntax, , backup-specs example, Backup Parameters
+@subsection Syntax for @file{Backup-specs}
+@UNREVISED
+
+@file{backup-specs} is in shell script syntax. The following
+conventions should be considered when editing the script:
+@FIXME{"conventions?"}
+
+A quoted string is considered to be contiguous, even if it is on more
+than one line. Therefore, you cannot include commented-out lines
+within a multi-line quoted string. BACKUP_FILES and BACKUP_DIRS are
+the two most likely parameters to be multi-line.
+
+A quoted string typically cannot contain wildcards. In
+@file{backup-specs}, however, the parameters BACKUP_DIRS and
+BACKUP_FILES can contain wildcards.
+
+@node Scripted Backups, Scripted Restoration, Backup Parameters, Backups
+@section Using the Backup Scripts
+@UNREVISED
+
+The syntax for running a backup script is:
+
+@example
+@file{script-name} [@var{time-to-be-run}]
+@end example
+
+where @var{time-to-be-run} can be a specific system time, or can be
+@kbd{now}. If you do not specify a time, the script runs at the time
+specified in @file{backup-specs} (@FIXME-pxref{Script Syntax}).
+
+You should start a script with a tape or disk mounted. Once you
+start a script, it prompts you for new tapes or disks as it
+needs them. Media volumes don't have to correspond to archive
+files---a multi-volume archive can be started in the middle of a
+tape that already contains the end of another multi-volume archive.
+The @code{restore} script prompts for media by its archive volume,
+so to avoid an error message you should keep track of which tape
+(or disk) contains which volume of the archive. @FIXME{There is
+no such restore script!}. @FIXME-xref{Scripted Restoration}.
+@FIXME{Have file names changed?}
+
+The backup scripts write two files on the file system. The first is a
+record file in @file{/etc/tar-backup/}, which is used by the scripts
+to store and retrieve information about which files were dumped. This
+file is not meant to be read by humans, and should not be deleted by
+them. @FIXME-xref{incremental and listed-incremental}, for a more
+detailed explanation of this file.
+
+The second file is a log file containing the names of the file systems
+and files dumped, what time the backup was made, and any error
+messages that were generated, as well as how much space was left in
+the media volume after the last volume of the archive was written.
+You should check this log file after every backup. The file name is
+@file{log-@var{mmm-ddd-yyyy}-level-1} or
+@file{log-@var{mmm-ddd-yyyy}-full}.
+
+The script also prints the name of each system being dumped to the
+standard output.
+
+@node Scripted Restoration, , Scripted Backups, Backups
+@section Using the Restore Script
+@UNREVISED
+
+@ifset PUBLISH
+
+The @code{tar} distribution does not provide restoring scripts.
+
+@end ifset
+
+@ifclear PUBLISH
+
+@quotation
+@strong{Warning:} The GNU @code{tar} distribution does @emph{not}
+provide any such @code{restore} script yet. This section is only
+listed here for documentation maintenance purposes. In any case,
+all contents is subject to change as things develop.
+@end quotation
+
+@FIXME{A section on non-scripted restore may be a good idea.}
+
+To restore files that were archived using a scripted backup, use the
+@code{restore} script. The syntax for the script is:
+
+where ***** are the file systems to restore from, and
+***** is a regular expression which specifies which files to
+restore. If you specify --all, the script restores all the files
+in the file system.
+
+You should start the restore script with the media containing the
+first volume of the archive mounted. The script will prompt for other
+volumes as they are needed. If the archive is on tape, you don't need
+to rewind the tape to to its beginning---if the tape head is
+positioned past the beginning of the archive, the script will rewind
+the tape as needed. @FIXME-xref{Media}, for a discussion of tape
+positioning.
+
+If you specify @samp{--all} as the @var{files} argument, the
+@code{restore} script extracts all the files in the archived file
+system into the active file system.
+
+@quotation
+@strong{Warning:} The script will delete files from the active file
+system if they were not in the file system when the archive was made.
+@end quotation
+
+@value{xref-incremental}, and @value{ref-listed-incremental},
+for an explanation of how the script makes that determination.
+
+@FIXME{this may be an option, not a given}
+
+@end ifclear
+
+@node Choosing, Date input formats, Backups, Top
+@chapter Choosing Files and Names for @code{tar}
+@UNREVISED
+
+@FIXME{Melissa (still) Doesn't Really Like This ``Intro'' Paragraph!!!}
+
+Certain options to @code{tar} enable you to specify a name for your
+archive. Other options let you decide which files to include or exclude
+from the archive, based on when or whether files were modified, whether
+the file names do or don't match specified patterns, or whether files
+are in specified directories.
+
+@menu
+* file:: Choosing the Archive's Name
+* Selecting Archive Members::
+* files:: Reading Names from a File
+* exclude:: Excluding Some Files
+* Wildcards::
+* after:: Operating Only on New Files
+* recurse:: Descending into Directories
+* one:: Crossing Filesystem Boundaries
+@end menu
+
+@node file, Selecting Archive Members, Choosing, Choosing
+@section Choosing and Naming Archive Files
+@cindex Naming an archive
+@cindex Archive Name
+@cindex Directing output
+@cindex Choosing an archive file
+@cindex Where is the archive?
+@UNREVISED
+
+@FIXME{should the title of this section actually be, "naming an
+archive"?}
+
+By default, @code{tar} uses an archive file name that was compiled when
+it was built on the system; usually this name refers to some physical
+tape drive on the machine. However, the person who installed @code{tar}
+on the system may not set the default to a meaningful value as far as
+most users are concerned. As a result, you will usually want to tell
+@code{tar} where to find (or create) the archive. The @value{op-file}
+option allows you to either specify or name a file to use as the archive
+instead of the default archive file location.
+
+@table @kbd
+@item --file=@var{archive-name}
+@itemx -f @var{archive-name}
+Name the archive to create or operate on. Use in conjunction with
+any operation.
+@end table
+
+For example, in this @code{tar} command,
+
+@example
+$ @kbd{tar -cvf collection.tar blues folk jazz}
+@end example
+
+@noindent
+@file{collection.tar} is the name of the archive. It must directly
+follow the @samp{-f} option, since whatever directly follows @samp{-f}
+@emph{will} end up naming the archive. If you neglect to specify an
+archive name, you may end up overwriting a file in the working directory
+with the archive you create since @code{tar} will use this file's name
+for the archive name.
+
+An archive can be saved as a file in the file system, sent through a
+pipe or over a network, or written to an I/O device such as a tape,
+floppy disk, or CD write drive.
+
+@cindex Writing new archives
+@cindex Archive creation
+If you do not name the archive, @code{tar} uses the value of the
+environment variable @code{TAPE} as the file name for the archive. If
+that is not available, @code{tar} uses a default, compiled-in archive
+name, usually that for tape unit zero (ie. @file{/dev/tu00}).
+@code{tar} always needs an archive name.
+
+If you use @file{-} as an @var{archive-name}, @code{tar} reads the
+archive from standard input (when listing or extracting files), or
+writes it to standard output (when creating an archive). If you use
+@file{-} as an @var{archive-name} when modifying an archive,
+@code{tar} reads the original archive from its standard input and
+writes the entire new archive to its standard output.
+
+@FIXME{might want a different example here; this is already used in
+"notable tar usages".}
+
+@example
+$ @kbd{cd sourcedir; tar -cf - . | (cd targetdir; tar -xf -)}
+@end example
+
+@FIXME{help!}
+
+@cindex Standard input and output
+@cindex tar to standard input and output
+To specify an archive file on a device attached to a remote machine,
+use the following:
+
+@example
+@kbd{--file=@var{hostname}:/@var{dev}/@var{file name}}
+@end example
+
+@noindent
+@code{tar} will complete the remote connection, if possible, and
+prompt you for a username and password. If you use
+@samp{--file=@@@var{hostname}:/@var{dev}/@var{file name}}, @code{tar}
+will complete the remote connection, if possible, using your username
+as the username on the remote machine.
+
+If the archive file name includes a colon (@samp{:}), then it is assumed
+to be a file on another machine. If the archive file is
+@samp{@var{user}@@@var{host}:@var{file}}, then @var{file} is used on the
+host @var{host}. The remote host is accessed using the @code{rsh}
+program, with a username of @var{user}. If the username is omitted
+(along with the @samp{@@} sign), then your user name will be used.
+(This is the normal @code{rsh} behavior.) It is necessary for the
+remote machine, in addition to permitting your @code{rsh} access, to
+have the @file{/usr/ucb/rmt} program installed. If you need to use a
+file whose name includes a colon, then the remote tape drive behavior
+can be inhibited by using the @value{op-force-local} option.
+
+@FIXME{i know we went over this yesterday, but bob (and now i do again,
+too) thinks it's out of the middle of nowhere. it doesn't seem to tie
+into what came before it well enough <<i moved it now, is it better
+here?>>. bob also comments that if Amanda isn't free software, we
+shouldn't mention it..}
+
+When the archive is being created to @file{/dev/null}, GNU @code{tar}
+tries to minimize input and output operations. The Amanda backup
+system, when used with GNU @code{tar}, has an initial sizing pass which
+uses this feature.
+
+@node Selecting Archive Members, files, file, Choosing
+@section Selecting Archive Members
+@cindex Specifying files to act on
+@cindex Specifying archive members
+
+@dfn{File Name arguments} specify which files in the file system
+@code{tar} operates on, when creating or adding to an archive, or which
+archive members @code{tar} operates on, when reading or deleting from
+an archive. @xref{Operations}.
+
+To specify file names, you can include them as the last arguments on
+the command line, as follows:
+@smallexample
+@kbd{tar} @var{operation} [@var{option1} @var{option2} @dots{}] [@var{file name-1} @var{file name-2} @dots{}]
+@end smallexample
+
+If you specify a directory name as a file name argument, all the files
+in that directory are operated on by @code{tar}.
+
+If you do not specify files when @code{tar} is invoked with
+@value{op-create}, @code{tar} operates on all the non-directory files in
+the working directory. If you specify either @value{op-list} or
+@value{op-extract}, @code{tar} operates on all the archive members in the
+archive. If you specify any operation other than one of these three,
+@code{tar} does nothing.
+
+By default, @code{tar} takes file names from the command line. However,
+there are other ways to specify file or member names, or to modify the
+manner in which @code{tar} selects the files or members upon which to
+operate; @FIXME{add xref here}. In general, these methods work both for
+specifying the names of files and archive members.
+
+@node files, exclude, Selecting Archive Members, Choosing
+@section Reading Names from a File
+@UNREVISED
+
+@cindex Reading file names from a file
+@cindex Lists of file names
+@cindex File Name arguments, alternatives
+Instead of giving the names of files or archive members on the command
+line, you can put the names into a file, and then use the
+@value{op-files-from} option to @code{tar}. Give the name of the file
+which contains the list of files to include as the argument to
+@samp{--files-from}. In the list, the file names should be separated by
+newlines. You will frequently use this option when you have generated
+the list of files to archive with the @code{find} utility.
+
+@table @kbd
+@item --files-from=@var{file name}
+@itemx -T @var{file name}
+Get names to extract or create from file @var{file name}.
+@end table
+
+If you give a single dash as a file name for @samp{--files-from}, (i.e.,
+you specify either @samp{--files-from=-} or @samp{-T -}), then the file
+names are read from standard input.
+
+Unless you are running @code{tar} with @samp{--create}, you can not use
+both @samp{--files-from=-} and @samp{--file=-} (@samp{-f -}) in the same
+command.
+
+@FIXME{add bob's example, from his message on 2-10-97}
+
+The following example shows how to use @code{find} to generate a list of
+files smaller than 400K in length and put that list into a file
+called @file{small-files}. You can then use the @samp{-T} option to
+@code{tar} to specify the files from that file, @file{small-files}, to
+create the archive @file{little.tgz}. (The @samp{-z} option to
+@code{tar} compresses the archive with @code{gzip}; @pxref{gzip} for
+more information.)
+
+@example
+$ @kbd{find . -size -400 -print > small-files}
+$ @kbd{tar -c -v -z -T small-files -f little.tgz}
+@end example
+
+@noindent
+@FIXME{say more here to conclude the example/section?}
+
+@menu
+* nul::
+@end menu
+
+@node nul, , files, files
+@ifinfo
+@unnumberedsubsec @kbd{NUL} Terminated File Names
+@end ifinfo
+
+@cindex File names, terminated by @kbd{NUL}
+@cindex @kbd{NUL} terminated file names
+The @value{op-null} option causes @value{op-files-from} to read file
+names terminated by a @code{NUL} instead of a newline, so files whose
+names contain newlines can be archived using @samp{--files-from}.
+
+@table @kbd
+@item --null
+Only consider @kbd{NUL} terminated file names, instead of files that
+terminate in a newline.
+@end table
+
+The @samp{--null} option is just like the one in GNU @code{xargs} and
+@code{cpio}, and is useful with the @samp{-print0} predicate of GNU
+@code{find}. In @code{tar}, @samp{--null} also causes
+@value{op-directory} options to be treated as file names to archive, in
+case there are any files out there called @file{-C}.
+
+This example shows how to use @code{find} to generate a list of files
+larger than 800K in length and put that list into a file called
+@file{long-files}. The @samp{-print0} option to @code{find} just just
+like @samp{-print}, except that it separates files with a @kbd{NUL}
+rather than with a newline. You can then run @code{tar} with both the
+@samp{--null} and @samp{-T} options to specify that @code{tar} get the
+files from that file, @file{long-files}, to create the archive
+@file{big.tgz}. The @samp{--null} option to @code{tar} will cause
+@code{tar} to recognize the @kbd{NUL} separator between files.
+
+@example
+$ @kbd{find . -size +800 -print0 > long-files}
+$ @kbd{tar -c -v --null --files-from=long-files --file=big.tar}
+@end example
+
+@FIXME{say anything else here to conclude the section?}
+
+@node exclude, Wildcards, files, Choosing
+@section Excluding Some Files
+@cindex File names, excluding files by
+@cindex Excluding files by name and pattern
+@cindex Excluding files by file system
+@UNREVISED
+
+To avoid operating on files whose names match a particular pattern,
+use the @value{op-exclude} or @value{op-exclude-from} options.
+
+@table @kbd
+@item --exclude=@var{pattern}
+Causes @code{tar} to ignore files that match the @var{pattern}.
+@end table
+
+@findex exclude
+The @value{op-exclude} option will prevent any file or member which
+matches the shell wildcards (@var{pattern}) from being operated on
+(@var{pattern} can be a single file name or a more complex expression).
+For example, if you want to create an archive with all the contents of
+@file{/tmp} except the file @file{/tmp/foo}, you can use the command
+@samp{tar --create --file=arch.tar --exclude=foo}. You may give
+multiple @samp{--exclude} options.
+
+@table @kbd
+@item --exclude-from=@var{file}
+@itemx -X @var{file}
+Causes @code{tar} to ignore files that match the patterns listed in
+@var{file}.
+@end table
+
+@findex exclude-from
+Use the @samp{--exclude-from=@var{file-of-patterns}} option to read a
+list of shell wildcards, one per line, from @var{file}; @code{tar} will
+ignore files matching those regular expressions. Thus if @code{tar} is
+called as @w{@samp{tar -c -X foo .}} and the file @file{foo} contains a
+single line @file{*.o}, no files whose names end in @file{.o} will be
+added to the archive.
+
+@FIXME{do the exclude options files need to have stuff separated by
+newlines the same as the files-from option does?}
+
+@menu
+* problems with exclude::
+@end menu
+
+@node problems with exclude, , exclude, exclude
+@unnumberedsubsec Problems with Using the @code{exclude} Options
+
+@FIXME{put in for the editor's/editors' amusement, but should be taken
+out in the final draft, just in case! : }
+
+@ignore
+subtitled: getting screwed using exclewed
+@end ignore
+
+Some users find @samp{exclude} options confusing. Here are some common
+pitfalls:
+
+@itemize @bullet
+@item
+The main operating mode of @code{tar} will always act on file names
+listed on the command line, no matter whether or not there is an
+exclusion which would otherwise affect them. In the example above, if
+you create an archive and exclude files that end with @samp{*.o}, but
+explicitly name the file @samp{catc.o} after all the options have been
+listed, @samp{catc.o} @emph{will} be included in the archive.
+
+@item
+You can sometimes confuse the meanings of @value{op-exclude} and
+@value{op-exclude-from}. Be careful: use @value{op-exclude} when files
+to be excluded are given as a pattern on the command line. Use
+@samp{--exclude-from=@var{file-of-patterns}} to introduce the name of a
+file which contains a list of patterns, one per line; each of these
+patterns can exclude zero, one, or many files.
+
+@item
+When you use @value{op-exclude}, be sure to quote the @var{pattern}
+parameter, so GNU @code{tar} sees wildcard characters like @samp{*}.
+If you do not do this, the shell might expand the @samp{*} itself
+using files at hand, so @code{tar} might receive a list of files
+instead of one pattern, or none at all, making the command somewhat
+illegal. This might not correspond to what you want.
+
+For example, write:
+
+@example
+$ @kbd{tar -c -f @var{archive.tar} -X '*/tmp/*' @var{directory}}
+@end example
+
+@noindent
+rather than:
+
+@example
+$ @kbd{tar -c -f @var{archive.tar} -X */tmp/* @var{directory}}
+@end example
+
+@item
+You must use use shell syntax, or globbing, rather than @code{regexp}
+syntax, when using exclude options in @code{tar}. If you try to use
+@code{regexp} syntax to describe files to be excluded, your command
+might fail.
+
+@item
+In earlier versions of @code{tar}, what is now the
+@samp{--exclude-from=@var{file-of-patterns}} option was called
+@samp{--exclude-@var{pattern}} instead. Now,
+@samp{--exclude=@var{pattern}} applies to patterns listed on the command
+line and @samp{--exclude-from=@var{file-of-patterns}} applies to
+patterns listed in a file.
+
+@end itemize
+
+@node Wildcards, after, exclude, Choosing
+@section Wildcards Patterns and Matching
+
+@dfn{Globbing} is the operation by which @dfn{wildcard} characters,
+@samp{*} or @samp{?} for example, are replaced and expanded into all
+existing files matching the given pattern. However, @code{tar} often
+uses wildcard patterns for matching (or globbing) archive members instead
+of actual files in the filesystem. Wildcard patterns are also used for
+verifying volume labels of @code{tar} archives. This section has the
+purpose of explaining wildcard syntax for @code{tar}.
+
+@FIXME{the next few paragraphs need work.}
+
+A @var{pattern} should be written according to shell syntax, using wildcard
+characters to effect globbing. Most characters in the pattern stand
+for themselves in the matched string, and case is significant: @samp{a}
+will match only @samp{a}, and not @samp{A}. The character @samp{?} in the
+pattern matches any single character in the matched string. The character
+@samp{*} in the pattern matches zero, one, or more single characters in
+the matched string. The character @samp{\} says to take the following
+character of the pattern @emph{literally}; it is useful when one needs to
+match the @samp{?}, @samp{*}, @samp{[} or @samp{\} characters, themselves.
+
+The character @samp{[}, up to the matching @samp{]}, introduces a character
+class. A @dfn{character class} is a list of acceptable characters
+for the next single character of the matched string. For example,
+@samp{[abcde]} would match any of the first five letters of the alphabet.
+Note that within a character class, all of the ``special characters''
+listed above other than @samp{\} lose their special meaning; for example,
+@samp{[-\\[*?]]} would match any of the characters, @samp{-}, @samp{\},
+@samp{[}, @samp{*}, @samp{?}, or @samp{]}. (Due to parsing constraints,
+the characters @samp{-} and @samp{]} must either come @emph{first} or
+@emph{last} in a character class.)
+
+@cindex Excluding characters from a character class
+@cindex Character class, excluding characters from
+If the first character of the class after the opening @samp{[}
+is @samp{!} or @samp{^}, then the meaning of the class is reversed.
+Rather than listing character to match, it lists those characters which
+are @emph{forbidden} as the next single character of the matched string.
+
+Other characters of the class stand for themselves. The special
+construction @samp{[@var{a}-@var{e}]}, using an hyphen between two
+letters, is meant to represent all characters between @var{a} and
+@var{e}, inclusive.
+
+@FIXME{need to add a sentence or so here to make this clear for those
+who don't have dan around.}
+
+Periods (@samp{.}) or forward slashes (@samp{/}) are not considered
+special for wildcard matches. However, if a pattern completely matches
+a directory prefix of a matched string, then it matches the full matched
+string: excluding a directory also excludes all the files beneath it.
+
+There are some discussions floating in the air and asking for modifications
+in the way GNU @code{tar} accomplishes wildcard matches. We perceive
+any change of semantics in this area as a delicate thing to impose on
+GNU @code{tar} users. On the other hand, the GNU project should be
+progressive enough to correct any ill design: compatibility at all price
+is not always a good attitude. In conclusion, it is @emph{possible}
+that slight amendments be later brought to the previous description.
+Your opinions on the matter are welcome.
+
+@node after, recurse, Wildcards, Choosing
+@section Operating Only on New Files
+@cindex Excluding file by age
+@cindex Modification time, excluding files by
+@cindex Age, excluding files by
+@UNREVISED
+
+The @value{op-after-date} option causes @code{tar} to only work on files
+whose modification or inode-changed times are newer than the @var{date}
+given. If you use this option when creating or appending to an archive,
+the archive will only include new files. If you use @samp{--after-date}
+when extracting an archive, @code{tar} will only extract files newer
+than the @var{date} you specify.
+
+If you only want @code{tar} to make the date comparison based on
+modification of the actual contents of the file (rather than inode
+changes), then use the @value{op-newer-mtime} option.
+
+You may use these options with any operation. Note that these options
+differ from the @value{op-update} operation in that they allow you to
+specify a particular date against which @code{tar} can compare when
+deciding whether or not to archive the files.
+
+@table @kbd
+@item --after-date=@var{date}
+@itemx --newer=@var{date}
+@itemx -N @var{date}
+Only store files newer than @var{date}.
+
+Acts on files only if their modification or inode-changed times are
+later than @var{date}. Use in conjunction with any operation.
+
+@item --newer-mtime=@var{date}
+Acts like @value{op-after-date}, but only looks at modification times.
+@end table
+
+These options limit @code{tar} to only operating on files which have
+been modified after the date specified. A file is considered to have
+changed if the contents have been modified, or if the owner,
+permissions, and so forth, have been changed. (For more information on
+how to specify a date, see @ref{Date input formats}; remember that the
+entire date argument must be quoted if it contains any spaces.)
+
+Gurus would say that @value{op-after-date} tests both the @code{mtime}
+(time the contents of the file were last modified) and @code{ctime}
+(time the file's status was last changed: owner, permissions, etc)
+fields, while @value{op-newer-mtime} tests only @code{mtime} field.
+
+To be precise, @value{op-after-date} checks @emph{both} @code{mtime} and
+@code{ctime} and processes the file if either one is more recent than
+@var{date}, while @value{op-newer-mtime} only checks @code{mtime} and
+disregards @code{ctime}. Neither uses @code{atime} (the last time the
+contents of the file were looked at).
+
+Date specifiers can have embedded spaces. Because of this, you may need
+to quote date arguments to keep the shell from parsing them as separate
+arguments.
+
+@FIXME{Need example of --newer-mtime with quoted argument.}
+
+@quotation
+@strong{Please Note:} @value{op-after-date} and @value{op-newer-mtime}
+should not be used for incremental backups. Some files (such as those
+in renamed directories) are not selected properly by these options.
+@xref{incremental and listed-incremental}.
+@end quotation
+
+To select files newer than the modification time of a file that already
+exists, you can use the @samp{--reference} (@samp{-r}) option of GNU
+@code{date}, available in GNU shell utilities 1.13 or later. It returns
+the timestamp of that already existing file; this timestamp expands to
+become the referent date which @samp{--newer} uses to determine which
+files to archive. For example, you could say,
+
+@example
+$ @kbd{tar -cf @var{archive.tar} --newer="`date -r @var{file}`" /home}
+@end example
+
+@noindent
+which tells @FIXME{need to fill this in!}.
+
+@node recurse, one, after, Choosing
+@section Descending into Directories
+@cindex Avoiding recursion in directories
+@cindex Descending directories, avoiding
+@cindex Directories, avoiding recursion
+@cindex Recursion in directories, avoiding
+@UNREVISED
+
+@FIXME{arrggh! this is still somewhat confusing to me. :-< }
+
+@FIXME{show dan bob's comments, from 2-10-97}
+
+Usually, @code{tar} will recursively explore all directories (either
+those given on the command line or through the @value{op-files-from}
+option) for the various files they contain. However, you may not always
+want @code{tar} to act this way.
+
+The @value{op-no-recursion} option inhibits @code{tar}'s recursive descent
+into specified directories. If you specify @samp{--no-recursion}, you can
+use the @code{find} utility for hunting through levels of directories to
+construct a list of file names which you could then pass to @code{tar}.
+@code{find} allows you to be more selective when choosing which files to
+archive; see @ref{files} for more information on using @code{find} with
+@code{tar}, or look.
+
+@table @kbd
+@item --no-recursion
+Prevents @code{tar} from recursively descending directories.
+@end table
+
+When you use @samp{--no-recursion}, GNU @code{tar} grabs directory entries
+themselves, but does not descend on them recursively. Many people use
+@code{find} for locating files they want to back up, and since
+@code{tar} @emph{usually} recursively descends on directories, they have
+to use the @samp{@w{! -d}} option to @code{find} @FIXME{needs more
+explanation or a cite to another info file} as they usually do not want
+all the files in a directory. They then use the @value{op-file-from}
+option to archive the files located via @code{find}.
+
+The problem when restoring files archived in this manner is that the
+directories themselves are not in the archive; so the
+@value{op-same-permissions} option does not affect them---while users
+might really like it to. Specifying @value{op-no-recursion} is a way to
+tell @code{tar} to grab only the directory entries given to it, adding
+no new files on its own.
+
+@FIXME{example here}
+
+@node one, , recurse, Choosing
+@section Crossing Filesystem Boundaries
+@cindex File system boundaries, not crossing
+@UNREVISED
+
+@code{tar} will normally automatically cross file system boundaries in
+order to archive files which are part of a directory tree. You can
+change this behavior by running @code{tar} and specifying
+@value{op-one-file-system}. This option only affects files that are
+archived because they are in a directory that is being archived;
+@code{tar} will still archive files explicitly named on the command line
+or through @value{op-files-from}, regardless of where they reside.
+
+@table @kbd
+@item --one-file-system
+@itemx -l
+Prevents @code{tar} from crossing file system boundaries when
+archiving. Use in conjunction with any write operation.
+@end table
+
+The @samp{--one-file-system} option causes @code{tar} to modify its
+normal behavior in archiving the contents of directories. If a file in
+a directory is not on the same filesystem as the directory itself, then
+@code{tar} will not archive that file. If the file is a directory
+itself, @code{tar} will not archive anything beneath it; in other words,
+@code{tar} will not cross mount points.
+
+It is reported that using this option, the mount point is is archived,
+but nothing under it.
+
+This option is useful for making full or incremental archival backups of
+a file system. If this option is used in conjunction with
+@value{op-verbose}, files that are excluded are mentioned by name on the
+standard error.
+
+@menu
+* directory:: Changing Directory
+* absolute:: Absolute File Names
+@end menu
+
+@node directory, absolute, one, one
+@subsection Changing the Working Directory
+
+@FIXME{need to read over this node now for continuity; i've switched
+things around some.}
+
+@cindex Changing directory mid-stream
+@cindex Directory, changing mid-stream
+@cindex Working directory, specifying
+@UNREVISED
+
+To change the working directory in the middle of a list of file names,
+either on the command line or in a file specified using
+@value{op-files-from}, use @value{op-directory}. This will change the
+working directory to the directory @var{directory} after that point in
+the list.
+
+@table @kbd
+@item --directory=@var{directory}
+@itemx -C @var{directory}
+Changes the working directory in the middle of a command line.
+@end table
+
+For example,
+
+@example
+$ @kbd{tar -c -f jams.tar grape prune -C food cherry}