Fix descriptions of -C and -T options.

This fixes discrepancies reported in https://savannah.gnu.org/bugs/?68253
and https://savannah.gnu.org/bugs/?68408.

* doc/tar.texi: Emphasize that the -C option does not affect filename
arguments to another options, such as -f, -T or the like.  Improve
the description of -T.
* doc/tar.1: Fix descriptions of -C and -T.

doc/tar.1

@@ -12,7 +12,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 "November 13, 2025" "TAR" "GNU TAR Manual"
+.TH TAR 1 "June 11, 2026" "TAR" "GNU TAR Manual"
 .SH NAME
 tar \- an archiving utility
 .SH SYNOPSIS
@@ -856,7 +856,14 @@ environment variable.  If it is not set, \fBexisting\fR is assumed.
 .TP
 \fB\-C\fR, \fB\-\-directory\fR=\fIDIR\fR
 Change to \fIDIR\fR before performing any operations.  This option is
-order-sensitive, i.e., it affects all options that follow.
+position-sensitive, i.e., it affects all command-line arguments that
+follow it, so that any relative file names appearing after it are
+taken to be relative to \fIDIR\fR.  It does not, however, affect
+arguments to \fIcommand-line options\fR that follow it, such as
+.IR \-f ,
+.IR \-T ,
+or
+.IR \-N .
 .TP
 \fB\-\-exclude\fR=\fIPATTERN\fR
 Exclude files matching \fIPATTERN\fR, a
@@ -979,22 +986,33 @@ 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.
-
+.IP
 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.
-
+.IP
 If this behavior is undesirable, it can be turned off using the
 \fB\-\-verbatim\-files\-from\fR option.
-
+.IP
 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.
+.IP
+Beside the file names, \fIFILE\fR can contain a subset of \fBtar\fR
+command line options, in particular
+.I \-C
+and
+.IR \-T .
+See the
+.BR "GNU tar Manual" ,
+section 6.3
+.BR "Reading Names from a File" ,
+for a detailed list of these.
 .TP
 \fB\-\-unquote\fR
 Unquote file or member names (default).

doc/tar.texi

@@ -2446,6 +2446,11 @@ exist in the archive. @xref{update}.
 @subsection @command{tar} Options
 
 @table @option
+@opsummary{add-file}
+@item --add-file=@var{file}
+This option has the same effect as adding @var{file} to the command
+line.  It is useful if @var{file} begins with a @samp{-} and can be
+confused with a command-line option (@pxref{add-file}).
 
 @opsummary{absolute-names}
 @item --absolute-names
@@ -2670,8 +2675,17 @@ access files outside the working directory.  @xref{dereference}.
 @itemx -C @var{dir}
 
 When this option is specified, @command{tar} will change its working directory
-to @var{dir} before performing any operations.  When this option is used
-during archive creation, it is order sensitive.  @xref{directory}.
+to @var{dir} before performing file archival or extraction
+operations.  This option is @dfn{position-sensitive}, i.e. it
+affects the arguments that follow it.  In particular, any relative file names
+supplied in the command line after it (or read from a file given with
+the @option{-T} option appearing after it) are assumed to be relative to
+@var{dir}.  It does not, however, affect file name arguments to other
+@emph{options}, such as @option{-f}, @option{-T}, or the like.
+
+@xref{directory}, for a detailed discussion of @option{-C} and its
+effect, and @ref{Position-Sensitive Options}, for a discussion of
+position-sensitive options.
 
 @opsummary{exclude}
 @item --exclude=@var{pattern}
@@ -7893,8 +7907,9 @@ with @samp{-} character, it is considered a @command{tar} option and is
 processed accordingly@footnote{Versions of @GNUTAR{} up to 1.15.1
 recognized only @option{-C} option in file lists, and only if the
 option and its argument occupied two consecutive lines.}.  Only a
-subset of @GNUTAR{} options is allowed for use in file lists.  For
-a list of such options, @ref{Position-Sensitive Options}.
+subset of @GNUTAR{} options is allowed for use in file lists: the
+options described in @ref{Position-Sensitive Options}, and the
+@option{--add-file} option, discussed below.
 
 For example, the common use of this feature is to change to another
 directory by specifying @option{-C} option:
@@ -7954,14 +7969,12 @@ The @option{--verbatim-files-from} affects all @option{-T} options
 that follow it in the command line.  The default behavior can be
 restored using @option{--no-verbatim-files-from} option.
 
+@anchor{add-file}
 @opindex add-file
-To disable option handling for a single file name, use the
-@option{--add-file} option, e.g.: @code{--add-file=--my-file}.
+The option @option{--add-file} is provided to add file names that look
+like command-line options, e.g.: @code{--add-file=--my-file}.
 
-You can use any @GNUTAR{} command line options in the file list file,
-including @option{--files-from} option itself.  This allows for
-including contents of a file list into another file list file.
-Note however, that options that control file list processing, such as
+Notice, that options that control file list processing, such as
 @option{--verbatim-files-from} or @option{--null} won't affect the
 file they appear in.  They will affect next @option{--files-from}
 option, if there is any.
@@ -9424,9 +9437,6 @@ mentioned by name on the standard error.
 @node directory
 @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
@@ -9443,7 +9453,8 @@ after that point in the list.
 Changes the working directory in the middle of a command line.
 @end table
 
-For example,
+All filename arguments appearing after this option will be taken
+relative to @var{directory}.  For example,
 
 @smallexample
 $ @kbd{tar -c -f jams.tar grape prune -C food cherry}
@@ -9496,19 +9507,49 @@ relative to the then working directory, which might not be the same as
 the original working directory of @command{tar}, due to a previous
 @option{--directory} option.
 
-When using @option{--files-from} (@pxref{files}), you can put various
-@command{tar} options (including @option{-C}) in the file list.  Notice,
-however, that in this case the option and its argument may not be
-separated by whitespace.  If you use short option, its argument must
-either follow the option letter immediately, without any intervening
-whitespace, or occupy the next line.  Otherwise, if you use long
-option, separate its argument by an equal sign.
+There is an important exception, though: the @option{-C} option does
+not affect filename arguments to another options that follow it, in
+particular @option{-f}.  This means that the example above can be
+written as
 
+@smallexample
+$ @kbd{tar -c -C /etc -f foo.tar passwd hosts -C /lib libc.a}
+@end smallexample
+
+@noindent
+and it will not change its overall effect: the files
+@file{passwd} and @file{hosts} will be read from the directory
+@file{/etc}, but the archive @file{foo.tar} will be created in the
+directory which was the working directory when the @command{tar}
+command was started.
+
+The command-line options not affected by @option{-C} are:
+
+@itemize @bullet
+@item @option{-g}, @option{--listed-incremental}
+@item @option{--exclude-ignore}
+@item @option{--exclude-ignore-recursive}
+@item @option{--exclude-tag}
+@item @option{--exclude-tag-all}
+@item @option{--exclude-tag-under}
+@item @option{-T}, @option{--files-from}
+@item @option{-X}, @option{--exclude-from}
+@item @option{--mtime}
+@item @option{--owner-map}
+@item @option{-f}, @option{--file}
+@item @option{-F}, @option{--info-script}, @option{--new-volume-script}
+@item @option{--volno-file}
+@item @option{-N}, @option{--newer}
+@item @option{--index-file}
+@end itemize
+
+When using @option{--files-from} (@pxref{files}), you can put certain
+@command{tar} options (including @option{-C}) in the file list as well.
 For instance, the file list for the above example will be:
 
 @smallexample
 @group
--C/etc
+-C /etc
 passwd
 hosts
 --directory=/lib
@@ -9523,6 +9564,9 @@ To use it, you would invoke @command{tar} as follows:
 $ @kbd{tar -c -f foo.tar --files-from list}
 @end smallexample
 
+For a full list of options that can be used in file lists,
+@ref{Position-Sensitive Options}.
+
 The interpretation of options in file lists is disabled by
 @option{--verbatim-files-from} and @option{--null} options.