Update docs

* doc/Makefile.am: Add recipes.texi
* doc/recipes.texi: New file.
* doc/tar.texi: New appendix "Recipes"

3 files changed, 143 insertions, 64 deletions

diff --git a/doc/Makefile.am b/doc/Makefile.am
index 98ff3ffa..cb69b743 100644
--- a/doc/Makefile.am
+++ b/doc/Makefile.am
@@ -28,6 +28,7 @@ tar_TEXINFOS = \
  header.texi\
  intern.texi\
  parse-datetime.texi\
+ recipes.texi\
  rendition.texi\
  snapshot.texi\
  sparse.texi\
diff --git a/doc/recipes.texi b/doc/recipes.texi
new file mode 100644
index 00000000..da259da3
--- /dev/null
+++ b/doc/recipes.texi
@@ -0,0 +1,134 @@
+@c This is part of the GNU tar manual.
+@c Copyright (C) 2017 Free Software Foundation, Inc.
+@c This file is distributed under GFDL 1.3 or any later version
+@c published by the Free Software Foundation.
+
+This appendix provides several recipes for performing common tasks
+using @GNUTAR{}.
+
+@menu
+* copy directory hierarchy::
+* intermediate directories::
+@end menu
+
+@node copy directory hierarchy
+@appendixsec Copying directory hierarchies
+
+This is a traditional way to copy a directory hierarchy preserving
+the dates, modes, owners and link-structure of all the files therein.
+It was used back when the @command{cp} command lacked the @option{-a}
+option:
+
+@smallexample
+$ @kbd{(cd sourcedir; tar -cf - .) | (cd targetdir; tar -xf -)}
+@end smallexample
+
+@noindent
+You can avoid subshells by using @option{-C} option:
+
+@smallexample
+$ @kbd{tar -C sourcedir -cf - . | tar -C targetdir -xf -}
+@end smallexample
+
+@noindent
+The same command using long option forms:
+
+@smallexample
+@group
+$ @kbd{(cd sourcedir; tar --create --file=- . ) \
+       | (cd targetdir; tar --extract --file=-)}
+@end group
+@end smallexample
+
+@noindent
+or
+
+@smallexample
+@group
+$ @kbd{tar --directory sourcedir --create --file=- . \
+       | tar --directory targetdir --extract --file=-}
+@end group
+@end smallexample
+
+@node intermediate directories
+@appendixsec Restoring Intermediate Directories
+
+A common concern is how to extract permissions and ownerships of
+intermediate directories when extracting only selected members from
+the archive.  To illustrate this, consider the following archive:
+
+@example
+@group
+# tar tvf A.tar
+drwxr-xr-x root/root         0 2017-11-16 14:39 foo/
+dr-xr-x--- gray/user         0 2017-11-16 14:39 foo/bar/
+-rw-r--r-- gray/user        10 2017-11-16 14:40 foo/bar/file
+@end group
+@end example
+
+Suppose you extract only the file @file{foo/bar/file}, while being
+@samp{root}:
+
+@example
+# @kbd{tar xvf A.tar foo/bar/file}
+foo/bar/file
+@end example
+
+Now, let's inspect the content of the created directories:
+
+@example
+@group
+# find foo -ls
+427257    0 drwxr-xr-x   3 root     root    16 Nov 17 16:10 foo
+427258    0 drwxr-xr-x   2 root     root    17 Nov 17 16:10 foo/bar
+427259    0 -rw-r--r--   1 gray     user    10 Nov  6 14:40 foo/bar/file
+@end group
+@end example
+
+The requested file is restored, including its ownership and
+permissions. The intermediate directories, however, are created with
+the default permissions, current timestamp and owned by the current
+user. This is because by the time @command{tar} has reached the requested file,
+it had already skipped the entries for its parent directories, so it
+has no iformation about their ownership and modes.
+
+To restore meta information about the intermediate directories,
+you'll need to specify them explicitly in the command line and use the
+@option{--no-recursive} option (@pxref{recurse}) to avoid extracting
+their content.
+
+To automate this process, @cite{Neal P. Murphy} proposed the following
+shell script@footnote{The original version of the script can be
+seen at @uref{http://lists.gnu.org/archive/html/bug-tar/2016-11/msg00024.html}}:
+
+@example
+@group
+#! /bin/sh
+(while read path
+ do
+   path=`dirname $path`
+   while [ -n "$path" -a "$path" != "." ]
+   do
+     echo $path
+     path=`dirname $path`
+   done
+ done < $2 | sort | uniq) |
+ tar -x --no-recursion -v -f $1 -T - -T $2
+@end group
+@end example
+
+The script takes two arguments: the name of the archive file, and the
+name of the file list file.
+
+To complete our example, the file list will contain single line:
+
+@example
+foo/bar/file
+@end example
+
+Supposing its name is @file{file.list} and the script is named
+@file{restore.sh}, you can invoke it as follows: 
+
+@example
+# @kbd{sh restore.sh A.tar file.list}
+@end example
diff --git a/doc/tar.texi b/doc/tar.texi
index 5d2d057a..ec657f53 100644
--- a/doc/tar.texi
+++ b/doc/tar.texi
@@ -36,7 +36,7 @@ This manual is for @acronym{GNU} @command{tar} (version
 @value{VERSION}, @value{UPDATED}), which creates and extracts files
 from archives.
 
-Copyright @copyright{} 1992, 1994--1997, 1999--2001, 2003--2016 Free
+Copyright @copyright{} 1992, 1994--1997, 1999--2001, 2003--2017 Free
 Software Foundation, Inc.
 
 @quotation
@@ -111,6 +111,7 @@ document.  The rest of the menu lists all the lower level nodes.
 Appendices
 
 * Changes::
+* Recipes:: Frequently used tar recipes
 * Configuring Help Summary::
 * Fixing Snapshot Files::
 * Tar Internals::
@@ -204,7 +205,6 @@ All @command{tar} Options
 * create options::
 * extract options::
 * backup::
-* Applications::
 * looking ahead::
 
 Advanced @GNUTAR{} Operations
@@ -4777,7 +4777,6 @@ expanded by the shell when invoking @command{tar}.
 * create options::
 * extract options::
 * backup::
-* Applications::
 * looking ahead::
 @end menu
 
@@ -6501,65 +6500,6 @@ set, the default is @samp{~}, just as in Emacs.
 
 @end table
 
-@node Applications
-@section Notable @command{tar} Usages
-@UNREVISED
-
-@FIXME{Using Unix file linking capability to recreate directory
-structures---linking files into one subdirectory and then
-@command{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 @command{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 @command{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}:
-
-@smallexample
-$ @kbd{(cd sourcedir; tar -cf - .) | (cd targetdir; tar -xf -)}
-@end smallexample
-
-@noindent
-You can avoid subshells by using @option{-C} option:
-
-@smallexample
-$ @kbd{tar -C sourcedir -cf - . | tar -C targetdir -xf -}
-@end smallexample
-
-@noindent
-The command also works using long option forms:
-
-@smallexample
-@group
-$ @kbd{(cd sourcedir; tar --create --file=- . ) \
-       | (cd targetdir; tar --extract --file=-)}
-@end group
-@end smallexample
-
-@noindent
-or
-
-@smallexample
-@group
-$ @kbd{tar --directory sourcedir --create --file=- . \
-       | tar --directory targetdir --extract --file=-}
-@end group
-@end smallexample
-
-@noindent
-This is one of the easiest methods to transfer a @command{tar} archive.
-
 @node looking ahead
 @section Looking Ahead: The Rest of this Manual
 
@@ -12932,8 +12872,8 @@ understand their security implications.
 @appendix Changes
 
 This appendix lists some important user-visible changes between
-version @GNUTAR{} @value{VERSION} and previous versions. An up-to-date
-version of this document is available at
+various versions of @GNUTAR{}. An up-to-date version of this document
+is available at
 @uref{http://www.gnu.org/@/software/@/tar/manual/changes.html,the
 @GNUTAR{} documentation page}.
 
@@ -13019,6 +12959,10 @@ These options are deprecated.  Please use @option{--format=v7} instead.
 This option is deprecated.  Please use @option{--format=posix} instead.
 @end table
 
+@node Recipes
+@appendix Recipes
+@include recipes.texi
+
 @node Configuring Help Summary
 @appendix Configuring Help Summary