[PATCH] Improve some wordings in the manuals, and improve an error message

[Benno Schulenberg]

* doc/tar.1: Add some missing articles, correct some formatting,
  and expand the opaque descriptions of two options.
* doc/tar.texi: Correct two cross references, correct the paragraph
  about the manpage, and unbreak a URL.
* src/names.c: Correct and shorten an error message: "non-optional"
  means "mandatory", but "non-option" is what was meant.  And the
  phrase "in archive create or update mode" was both unneeded and
  incomplete.
---
 doc/tar.1    | 63 ++++++++++++++++++++++++++--------------------------
 doc/tar.texi | 30 ++++++++++++-------------
 src/names.c  |  2 +-
 3 files changed, 47 insertions(+), 48 deletions(-)

diff --git a/doc/tar.1 b/doc/tar.1
index 23ae7ac2..27bacb58 100644
--- a/doc/tar.1
+++ b/doc/tar.1
@@ -72,7 +72,7 @@ You can also view the manual using the info mode in
 or find it in various formats online at
 .PP
 .RS +4
-.B http://www.gnu.org/software/tar/manual
+.B https://www.gnu.org/software/tar/manual
 .RE
 .PP
 If any discrepancies occur between this manpage and the
@@ -95,8 +95,8 @@ In
 the first argument is a cluster of option letters and all subsequent
 arguments supply arguments to those options that require them.  The
 arguments are read in the same order as the option letters.  Any
-command line words that remain after all options has been processed
-are treated as non-optional arguments: file or archive member names.
+command line words that remain after all options have been processed
+are treated as non-option arguments: file or archive member names.
 .PP
 For example, the \fBc\fR option requires creating the archive, the
 \fBv\fR option requests the verbose operation, and the \fBf\fR option
@@ -105,7 +105,7 @@ The following command, written in the traditional style, 
instructs tar
 to store all files from the directory
 .B /etc
 into the archive file
-.B etc.tar
+.BR etc.tar ,
 verbosely listing the files being archived:
 .PP
 .EX
@@ -115,15 +115,15 @@ tar cfv etc.tar /etc
 In
 .BR "UNIX " or " short-option style" ,
 each option letter is prefixed with a single dash, as in other command
-line utilities.  If an option takes argument, the argument follows it,
+line utilities.  If an option takes an argument, the argument follows it,
 either as a separate command line word, or immediately following the
 option.  However, if the option takes an \fBoptional\fR argument, the
 argument must follow the option letter without any intervening
 whitespace, as in \fB\-g/tmp/snar.db\fR.
 .PP
 Any number of options not taking arguments can be
-clustered together after a single dash, e.g. \fB\-vkp\fR.  Options
-that take arguments (whether mandatory or optional), can appear at
+clustered together after a single dash, e.g. \fB\-vkp\fR.  An option
+that takes an argument (whether mandatory or optional) can appear at
 the end of such a cluster, e.g. \fB\-vkpf a.tar\fR.
 .PP
 The example command above written in the
@@ -164,7 +164,7 @@ with old options is not encouraged.
 .SS Operation mode
 The options listed in the table below tell GNU \fBtar\fR what
 operation it is to perform.  Exactly one of them must be given.
-Meaning of non-optional arguments depends on the operation mode
+The meaning of non-option arguments depends on the operation mode
 requested.
 .TP
 \fB\-A\fR, \fB\-\-catenate\fR, \fB\-\-concatenate\fR
@@ -218,7 +218,7 @@ There is no short option equivalent for this option.
 .TP
 \fB\-u\fR, \fB\-\-update\fR
 Append files which are newer than the corresponding copy in the
-archive.  Arguments have the same meaning as with \fB\-c\fR and
+archive.  Arguments have the same meaning as with the \fB\-c\fR and
 \fB\-r\fR options.  Notice, that newer files don't replace their
 old archive copies, but instead are appended to the end of archive.
 The resulting archive can thus contain several members of the
@@ -249,16 +249,15 @@ Check device numbers when creating incremental archives 
(default).
 .TP
 \fB\-g\fR, \fB\-\-listed\-incremental\fR=\fIFILE\fR
 Handle new GNU-format incremental backups.  \fIFILE\fR is the name of
-a \fBsnapshot file\fR, where tar stores additional information which
+a \fBsnapshot file\fR, where \fBtar\fR stores additional information which
 is used to decide which files changed since the previous incremental
 dump and, consequently, must be dumped again.  If \fIFILE\fR does not
 exist when creating an archive, it will be created and all files will
 be added to the resulting archive (the \fBlevel 0\fR dump).  To create
-incremental archives of non-zero level \fBN\fR, create a copy of the
-snapshot file created during the level \fBN-1\fR, and use it as
-\fIFILE\fR.
+incremental archives of non-zero level \fBN\fR, you need a copy of the
+snapshot file created for level \fBN-1\fR, and use it as \fIFILE\fR.
 
-When listing or extracting, the actual contents of \fIFILE\fR is not
+When listing or extracting, the actual content of \fIFILE\fR is not
 inspected, it is needed only due to syntactical requirements.  It is
 therefore common practice to use \fB/dev/null\fR in its place.
 .TP
@@ -275,7 +274,7 @@ Handle old GNU-format incremental backups.
 Do not exit with nonzero on unreadable files.
 .TP
 \fB\-\-level\fR=\fINUMBER\fR
-Set dump level for created listed-incremental archive.  Currently only
+Set dump level for a created listed-incremental archive.  Currently only
 \fB\-\-level=0\fR is meaningful: it instructs \fBtar\fR to truncate
 the snapshot file before dumping, thereby forcing a level 0 dump.
 .TP
@@ -307,7 +306,7 @@ either on the command line or via the \fB\-T\fR option.  
The default
 Disable the use of some potentially harmful options.
 .TP
 \fB\-\-sparse\-version\fR=\fIMAJOR\fR[.\fIMINOR\fR]
-Set version of the sparse format to use (implies \fB\-\-sparse\fR).
+Set which version of the sparse format to use.
 This option implies
 .BR \-\-sparse .
 Valid argument values are
@@ -315,7 +314,7 @@ Valid argument values are
 .BR 0.1 ", and"
 .BR 1.0 .
 For a detailed discussion of sparse formats, refer to the \fBGNU Tar
-Manual\fR, appendix \fBD\fR, "\fBSparse Formats\fR".  Using \fBinfo\fR
+Manual\fR, appendix \fBD\fR, "\fBSparse Formats\fR".  Using the \fBinfo\fR
 reader, it can be accessed running the following command:
 .BR "info tar 'Sparse Formats'" .
 .TP
@@ -370,7 +369,6 @@ Verify the archive after writing it.
 .SS Output stream selection
 .TP
 \fB\-\-ignore\-command\-error\fR
-.TP
 Ignore subprocess exit codes.
 .TP
 \fB\-\-no\-ignore\-command\-error\fR
@@ -473,7 +471,7 @@ executing.
 \fB\-\-atime\-preserve\fR[=\fIMETHOD\fR]
 Preserve access times on dumped files, either by restoring the times
 after reading (\fIMETHOD\fR=\fBreplace\fR, this is the default) or by
-not setting the times in the first place (\fIMETHOD\fR=\fBsystem\fR)
+not setting the times in the first place (\fIMETHOD\fR=\fBsystem\fR).
 .TP
 \fB\-\-delay\-directory\-restore\fR
 Delay setting modification times and permissions of extracted
@@ -561,14 +559,16 @@ As a result, each input file owned by \fIOLDUSR\fR will be
 stored in archive with owner name \fINEWUSR\fR and UID \fINEWUID\fR.
 .TP
 \fB\-p\fR, \fB\-\-preserve\-permissions\fR, \fB\-\-same\-permissions\fR
-extract information about file permissions (default for superuser)
+Set permissions of extracted files to those recorded in the archive
+(default for superuser).
 .TP
 \fB\-\-same\-owner\fR
 Try extracting files with the same ownership as exists in the archive
 (default for superuser).
 .TP
 \fB\-s\fR, \fB\-\-preserve\-order\fR, \fB\-\-same\-order\fR
-Sort names to extract to match archive
+Tell \fBtar\fR that the list of file names to process is sorted in the
+same order as the files in the archive.
 .TP
 \fB\-\-sort=\fIORDER\fR
 When creating an archive, sort directory entries according to
@@ -742,7 +742,7 @@ end-of-file marker.
 .TP
 \fB\-i\fR, \fB\-\-ignore\-zeros\fR
 Ignore zeroed blocks in archive.  Normally two consecutive 512-blocks
-filled with zeroes mean EOF and tar stops reading after encountering
+filled with zeroes mean EOF and \fBtar\fR stops reading after encountering
 them.  This option instructs it to read further and is useful when
 reading archives created with the \fB\-A\fR option.
 .TP
@@ -1011,7 +1011,7 @@ 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.
+\fB\-\-no\-verbatim\-files\-from\fR option.
 
 This option is implied by the \fB\-\-null\fR option.
 
@@ -1061,7 +1061,8 @@ Display progress messages every \fIN\fRth record (default 
10).
 Run \fIACTION\fR on each checkpoint.
 .TP
 \fB\-\-clamp\-mtime\fR
-Only set time when the file is more recent than what was given with \-\-mtime.
+Only set time when the file is more recent than what was given with
+\fB\-\-mtime\fR.
 .TP
 \fB\-\-full\-time\fR
 Print file time to its full resolution.
@@ -1120,14 +1121,14 @@ Verbosely list files processed.  Each instance of this 
option on the
 command line increases the verbosity level by one.  The maximum
 verbosity level is 3.  For a detailed discussion of how various
 verbosity levels affect tar's output, please refer to \fBGNU Tar
-Manual\fR, subsection 2.5.1 "\fBThe \-\-verbose Option\fR".
+Manual\fR, subsection 2.5.2 "\fBThe '\-\-verbose' Option\fR".
 .TP
 \fB\-\-warning\fR=\fIKEYWORD\fR
 Enable or disable warning messages identified by \fIKEYWORD\fR.  The
 messages are suppressed if \fIKEYWORD\fR is prefixed with \fBno\-\fR
 and enabled otherwise.
 
-Multiple \fB\-\-warning\fR messages accumulate.
+Multiple \fB\-\-warning\fR options accumulate.
 
 Keywords controlling general \fBtar\fR operation:
 .RS
@@ -1267,7 +1268,7 @@ as \fB\-\-no\-same\-owner\fR.
 .fi
 .PP
 .SH "RETURN VALUE"
-Tar exit code indicates whether it was able to successfully perform
+Tar's exit code indicates whether it was able to successfully perform
 the requested operation, and if not, what kind of error occurred.
 .TP
 .B 0
@@ -1275,9 +1276,9 @@ Successful termination.
 .TP
 .B 1
 .I Some files differ.
-If tar was invoked with the \fB\-\-compare\fR (\fB\-\-diff\fR, \fB\-d\fR)
+If \fBtar\fR was invoked with the \fB\-\-compare\fR (\fB\-\-diff\fR, \fB\-d\fR)
 command line option, this means that some files in the archive differ
-from their disk counterparts.  If tar was given one of the \fB\-\-create\fR,
+from their disk counterparts.  If \fBtar\fR was given one of the 
\fB\-\-create\fR,
 \fB\-\-append\fR or \fB\-\-update\fR options, this exit code means
 that some files were changed while being archived and so the resulting
 archive does not contain the exact copy of the file set.
@@ -1316,11 +1317,11 @@ Online copies of \fBGNU tar\fR documentation in various 
formats can be
 found at:
 .PP
 .in +4
-.B http://www.gnu.org/software/tar/manual
+.B https://www.gnu.org/software/tar/manual
 .SH "BUG REPORTS"
 Report bugs to <bug\-tar@gnu.org>.
 .SH COPYRIGHT
-Copyright \(co 2013-2019 Free Software Foundation, Inc.
+Copyright \(co 2023 Free Software Foundation, Inc.
 .br
 .na
 License GPLv3+: GNU GPL version 3 or later <http://gnu.org/licenses/gpl.html>
diff --git a/doc/tar.texi b/doc/tar.texi
index 4e74fa1d..bbbc3bee 100644
--- a/doc/tar.texi
+++ b/doc/tar.texi
@@ -675,7 +675,7 @@ For version 1.12, Daniel Hagerty contributed a great deal 
of technical
 consulting.  In particular, he is the primary author of @ref{Backups}.
 
 In July, 2003 @GNUTAR{} was put on CVS at savannah.gnu.org
-(see @url{http://savannah.gnu.org/projects/tar}), and
+(see @url{https://savannah.gnu.org/projects/tar}), and
 active development and maintenance work has started
 again.  Currently @GNUTAR{} is being maintained by Paul Eggert, Sergey
 Poznyakoff and Jeff Bailey.
@@ -3337,7 +3337,7 @@ Same as @option{--format=posix}.
 @opsummary{preserve-order}
 @item --preserve-order
 
-(See @option{--same-order}; @pxref{Reading}.)
+(See @option{--same-order}; @pxref{Same Order}.)
 
 @opsummary{preserve-permissions}
 @opsummary{same-permissions}
@@ -3427,7 +3427,7 @@ devices.  @xref{Device}.
 This option is an optimization for @command{tar} when running on machines with
 small amounts of memory.  It informs @command{tar} that the list of file
 arguments has already been sorted to match the order of files in the
-archive.  @xref{Reading}.
+archive.  @xref{Same Order}.
 
 @opsummary{same-owner}
 @item --same-owner
@@ -4043,16 +4043,16 @@ 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 @command{cpio} and
 @command{tar} packages into a single one which would be called
-@code{paxutils}.  So, who knows if, one of this days, the
-@option{--version} would not output @w{@samp{tar (@acronym{GNU}
+@code{paxutils}.  So, who knows, one of these days
+@option{--version} might output @w{@samp{tar (@acronym{GNU}
 paxutils) 3.2}}.}.
 
 @cindex Obtaining help
 @cindex Listing all @command{tar} options
 @xopindex{help, introduction}
-Another thing you might want to do is checking the spelling or meaning
+Another thing you might want to do is check the spelling or meaning
 of some particular @command{tar} option, without resorting to this
-manual, for once you have carefully read it.  @GNUTAR{}
+manual, once you have carefully read it.  @GNUTAR{}
 has a short help feature, triggerable through the
 @option{--help} option.  By using this option, @command{tar} will
 print a usage message listing all available options on standard
@@ -4092,7 +4092,7 @@ The short help output is quite succinct, and you might 
have to get
 back to the full documentation for precise points.  If you are reading
 this paragraph, you already have the @command{tar} manual in some
 form.  This manual is available in a variety of forms from
-@url{http://www.gnu.org/software/tar/manual}.  It may be printed out of the 
@GNUTAR{}
+@url{https://www.gnu.org/software/tar/manual}.  It may be printed out of the 
@GNUTAR{}
 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
@@ -4103,12 +4103,10 @@ file.  Just call @w{@samp{info tar}} or, if you do not 
have the
 @command{info} program handy, use the Info reader provided within
 @acronym{GNU} Emacs, calling @samp{tar} from the main Info menu.
 
-There is currently no @code{man} page for @GNUTAR{}.
-If you observe such a @code{man} page on the system you are running,
-either it does not belong to @GNUTAR{}, or it has not
-been produced by @acronym{GNU}.  Some package maintainers convert
-@kbd{tar --help} output to a man page, using @command{help2man}.  In
-any case, please bear in mind that the authoritative source of
+Since 2014, @GNUTAR{} also has a @code{man} page.
+It briefly explains all the options and operations.
+This might be preferable when you don't need any background.
+But bear in mind that the authoritative source of
 information about @GNUTAR{} is this Texinfo documentation.
 
 @node defaults
@@ -7092,8 +7090,8 @@ mainly variable assignments.  However, any valid shell 
construct
 is allowed in this file.  Particularly, you may wish to define
 functions within that script (e.g., see @code{RESTORE_BEGIN} below).
 For more information about shell script syntax, please refer to
-@url{http://www.opengroup.org/onlinepubs/009695399/utilities/xcu_chap02.html#ta
-g_02, the definition of the Shell Command Language}.  See also
+@url{https://pubs.opengroup.org/onlinepubs/009695399/utilities/xcu_chap02.html,
+the definition of the Shell Command Language}.  See also
 @ref{Top,,Bash Features,bashref,Bash Reference Manual}.
 
 The shell variables controlling behavior of @code{backup} and
diff --git a/src/names.c b/src/names.c
index 14541a31..300d69eb 100644
--- a/src/names.c
+++ b/src/names.c
@@ -744,7 +744,7 @@ unconsumed_option_report (void)
     {
       struct name_elt *elt;
 
-      ERROR ((0, 0, _("The following options were used after any non-optional 
arguments in archive create or update mode.  These options are positional and 
affect only arguments that follow them.  Please, rearrange them properly.")));
+      ERROR ((0, 0, _("The following options were used after non-option 
arguments.  These options are positional and affect only arguments that follow 
them.  Please, rearrange them properly.")));
 
       elt = unconsumed_option_tail;
       while (elt->prev)
-- 
2.40.1