Update docs.

* doc/tar.1: Document --verbatim-files-from option.

1 files changed, 54 insertions, 3 deletions

diff --git a/doc/tar.1 b/doc/tar.1
index 4f19cffd..0c1e8bd6 100644
--- a/doc/tar.1
+++ b/doc/tar.1
@@ -13,7 +13,7 @@
 .\"
 .\" You should have received a copy of the GNU General Public License
 .\" along with this program.  If not, see <http://www.gnu.org/licenses/>.
-.TH TAR 1 "August 16, 2014" "TAR" "GNU TAR Manual"
+.TH TAR 1 "August 24, 2015" "TAR" "GNU TAR Manual"
 .SH NAME
 tar \- an archiving utility
 .SH SYNOPSIS
@@ -844,9 +844,27 @@ Avoid descending automatically in directories.
 \fB\-\-no\-unquote\fR
 Do not unquote input file or member names.
 .TP
+\fB\-\-no\-verbatim\-files\-from\fR
+Treat each line read from a file list as if it were supplied in the
+command line.  I.e., leading and trailing whitespace is removed and,
+if the resulting string begins with a dash, it is treated as \fBtar\fR
+command line option.
+
+This is the default behavior.  The \fB\-\-no\-verbatim\-files\-from\fR
+option is provided as a way to restore it after
+\fB\-\-verbatim\-files\-from\fR option.
+
+This option is positional: it affects all \fB\-\-files\-from\fR
+options that occur after it in, until \fB\-\-verbatim\-files\-from\fR
+option or end of line, whichever occurs first.
+
+It is implied by the \fB\-\-no\-null\fR option.
+.TP
 \fB\-\-null\fR
-Instruct subsequent \fB\-T\fR options to read null-terminated names,
-disable handling of the \fB\-C\fR option read from the file.
+Instruct subsequent \fB\-T\fR options to read null-terminated names
+verbatim (disables special handling of names that start with a dash).
+
+See also \fB\-\-verbatim\-files\-from\fR.
 .TP
 \fB\-N\fR, \fB\-\-newer\fR=\fIDATE\fR, \fB\-\-after\-date\fR=\fIDATE\fR
 Only store files newer than DATE.  If \fIDATE\fR starts with \fB/\fR
@@ -868,10 +886,43 @@ unless overridden by environment variable \fBSIMPLE_BACKUP_SUFFIX\fR.
 .TP
 \fB\-T\fR, \fB\-\-files\-from\fR=\fIFILE\fR
 Get names to extract or create from \fIFILE\fR.
+
+Unless specified otherwise, the \fIFILE\fR must contain a list of
+names separated by ASCII \fBLF\fR (i.e. one name per line).  The
+names read are handled the same way as command line arguments.  They
+undergo quote removal and word splitting, and any string that starts
+with a \fB\-\fR is handled as \fBtar\fR command line option.
+
+If this behavior is undesirable, it can be turned off using the
+\fB\-\-verbatim\-files\-from\fR option.
+
+The \fB\-\-null\fR option instructs \fBtar\fR that the names in
+\fIFILE\fR are separated by ASCII \fBNUL\fR character, instead of
+\fBLF\fR.  It is useful if the list is generated by
+.BR find (1)
+.B \-print0
+predicate.
 .TP
 \fB\-\-unquote\fR
 Unquote file or member names (default).
 .TP
+\fB\-\-verbatim\-files\-from\fR
+Treat each line obtained from a file list as a file name, even if it
+starts with a dash.  File lists are supplied with the
+\fB\-\-files\-from\fR (\fB\-T\fR) option.  The default behavior is to
+handle names supplied in file lists as if they were typed in the
+command line, i.e. any names starting with a dash are treated as
+\fBtar\fR options.  The \fB\-\-verbatim\-files\-from\fR option
+disables this behavior.
+
+This option affects all \fB\-\-files\-from\fR options that occur after
+it in the command line.  Its effect is reverted by the
+\fB\-\-no\-verbatim\-files\-from} option.
+
+This option is implied by the \fB\-\-null\fR option.
+
+See also \fB\-\-add\-file\fR.
+.TP
 \fB\-X\fR, \fB\-\-exclude\-from\fR=\fIFILE\fR
 Exclude files matching patterns listed in FILE.
 .SS  File name transformations