doc: avoid confusing K argument in the man pages of head and tail

The character 'K' representing numeric user input can be confusing,
especially in the context where it can be suffixed by the multipliers
K, M, G, etc.
Use NUM instead.

* doc/coreutils.texi (head invocation): Replace @var{k} by @var{num}.
Also change @var{count} in the paragraph about the obsolete option
syntax.
(tail invocation): Likewise.  Furthermore, adjust the option order to
alphabetical sorting.
* src/head.c (usage): s/K/NUM/ in as placeholder in the -c and -n
options.  Furthermore, print the actual DEFAULT_NUMBER instead of the
hard-coded 10.
* src/tail.c (usage): s/K/NUM/ in as placeholder in the -c and -n
options.  Add "[+]" to clarify that NUM may optionally be preceded by
this sign.  Remove the redundant explanation of the optional '+' prefix
for NUM, as that is now clear from the option description above.

Suggested by Dan Jacobson in http://bugs.gnu.org/22042

3 files changed, 91 insertions, 93 deletions

diff --git a/doc/coreutils.texi b/doc/coreutils.texi
index 9a27cb109..a13c6e7be 100644
--- a/doc/coreutils.texi
+++ b/doc/coreutils.texi
@@ -2777,22 +2777,22 @@ The program accepts the following options.  Also see @ref{Common options}.
 
 @table @samp
 
-@item -c @var{k}
-@itemx --bytes=@var{k}
+@item -c [-]@var{num}
+@itemx --bytes=[-]@var{num}
 @opindex -c
 @opindex --bytes
-Print the first @var{k} bytes, instead of initial lines.
-However, if @var{k} starts with a @samp{-},
-print all but the last @var{k} bytes of each file.
-@multiplierSuffixes{k}
+Print the first @var{num} bytes, instead of initial lines.
+However, if @var{num} is prefixed with a @samp{-},
+print all but the last @var{num} bytes of each file.
+@multiplierSuffixes{num}
 
-@item -n @var{k}
-@itemx --lines=@var{k}
+@item -n [-]@var{num}
+@itemx --lines=[-]@var{num}
 @opindex -n
 @opindex --lines
-Output the first @var{k} lines.
-However, if @var{k} starts with a @samp{-},
-print all but the last @var{k} lines of each file.
+Output the first @var{num} lines.
+However, if @var{num} is prefixed with a @samp{-},
+print all but the last @var{num} lines of each file.
 Size multiplier suffixes are the same as with the @option{-c} option.
 
 @item -q
@@ -2812,12 +2812,12 @@ Always print file name headers.
 @end table
 
 For compatibility @command{head} also supports an obsolete option syntax
-@option{-@var{count}@var{options}}, which is recognized only if it is
-specified first.  @var{count} is a decimal number optionally followed
+@option{-[@var{num}][bkm][cqv]}, which is recognized only if it is
+specified first.  @var{num} is a decimal number optionally followed
 by a size letter (@samp{b}, @samp{k}, @samp{m}) as in @option{-c}, or
 @samp{l} to mean count by lines, or other option letters (@samp{cqv}).
-Scripts intended for standard hosts should use @option{-c @var{count}}
-or @option{-n @var{count}} instead.  If your script must also run on
+Scripts intended for standard hosts should use @option{-c @var{num}}
+or @option{-n @var{num}} instead.  If your script must also run on
 hosts that support only the obsolete syntax, it is usually simpler to
 avoid @command{head}, e.g., by using @samp{sed 5q} instead of
 @samp{head -5}.
@@ -2870,14 +2870,14 @@ The program accepts the following options.  Also see @ref{Common options}.
 
 @table @samp
 
-@item -c @var{k}
-@itemx --bytes=@var{k}
+@item -c [+]@var{num}
+@itemx --bytes=[+]@var{num}
 @opindex -c
 @opindex --bytes
-Output the last @var{k} bytes, instead of final lines.
-However, if @var{k} starts with a @samp{+}, start printing with the
-@var{k}th byte from the start of each file, instead of from the end.
-@multiplierSuffixes{k}
+Output the last @var{num} bytes, instead of final lines.
+However, if @var{num} is prefixed with a @samp{+}, start printing with
+byte @var{num} from the start of each file, instead of from the end.
+@multiplierSuffixes{num}
 
 @item -f
 @itemx --follow[=@var{how}]
@@ -2944,36 +2944,27 @@ This option is the same as @option{--follow=name --retry}.  That is, tail
 will attempt to reopen a file when it is removed.  Should this fail, tail
 will keep trying until it becomes accessible again.
 
-@item --retry
-@opindex --retry
-Indefinitely try to open the specified file.
-This option is useful mainly when following (and otherwise issues a warning).
-
-When following by file descriptor (i.e., with @option{--follow=descriptor}),
-this option only affects the initial open of the file, as after a successful
-open, @command{tail} will start following the file descriptor.
-
-When following by name (i.e., with @option{--follow=name}), @command{tail}
-infinitely retries to re-open the given files until killed.
-
-Without this option, when @command{tail} encounters a file that doesn't
-exist or is otherwise inaccessible, it reports that fact and
-never checks it again.
+@item --max-unchanged-stats=@var{n}
+@opindex --max-unchanged-stats
+When tailing a file by name, if there have been @var{n} (default
+n=@value{DEFAULT_MAX_N_UNCHANGED_STATS_BETWEEN_OPENS}) consecutive
+iterations for which the file has not changed, then
+@code{open}/@code{fstat} the file to determine if that file name is
+still associated with the same device/inode-number pair as before.
+When following a log file that is rotated, this is approximately the
+number of seconds between when tail prints the last pre-rotation lines
+and when it prints the lines that have accumulated in the new log file.
+This option is meaningful only when polling (i.e., without inotify)
+and when following by name.
 
-@item -s @var{number}
-@itemx --sleep-interval=@var{number}
-@opindex -s
-@opindex --sleep-interval
-Change the number of seconds to wait between iterations (the default is 1.0).
-During one iteration, every specified file is checked to see if it has
-changed size.
-Historical implementations of @command{tail} have required that
-@var{number} be an integer.  However, GNU @command{tail} accepts
-an arbitrary floating point number.  @xref{Floating point}.
-When @command{tail} uses inotify, this polling-related option
-is usually ignored.  However, if you also specify @option{--pid=@var{p}},
-@command{tail} checks whether process @var{p} is alive at least
-every @var{number} seconds.
+@item -n [+]@var{num}
+@itemx --lines=[+]@var{}
+@opindex -n
+@opindex --lines
+Output the last @var{num} lines.
+However, if @var{num} is prefixed with a @samp{+}, start printing with
+line @var{num} from the start of each file, instead of from the end.
+Size multiplier suffixes are the same as with the @option{-c} option.
 
 @item --pid=@var{pid}
 @opindex --pid
@@ -2998,28 +2989,6 @@ terminate until long after the real writer has terminated.
 Note that @option{--pid} cannot be supported on some systems; @command{tail}
 will print a warning if this is the case.
 
-@item --max-unchanged-stats=@var{n}
-@opindex --max-unchanged-stats
-When tailing a file by name, if there have been @var{n} (default
-n=@value{DEFAULT_MAX_N_UNCHANGED_STATS_BETWEEN_OPENS}) consecutive
-iterations for which the file has not changed, then
-@code{open}/@code{fstat} the file to determine if that file name is
-still associated with the same device/inode-number pair as before.
-When following a log file that is rotated, this is approximately the
-number of seconds between when tail prints the last pre-rotation lines
-and when it prints the lines that have accumulated in the new log file.
-This option is meaningful only when polling (i.e., without inotify)
-and when following by name.
-
-@item -n @var{k}
-@itemx --lines=@var{k}
-@opindex -n
-@opindex --lines
-Output the last @var{k} lines.
-However, if @var{k} starts with a @samp{+}, start printing with the
-@var{k}th line from the start of each file, instead of from the end.
-Size multiplier suffixes are the same as with the @option{-c} option.
-
 @item -q
 @itemx --quiet
 @itemx --silent
@@ -3028,6 +2997,37 @@ Size multiplier suffixes are the same as with the @option{-c} option.
 @opindex --silent
 Never print file name headers.
 
+@item --retry
+@opindex --retry
+Indefinitely try to open the specified file.
+This option is useful mainly when following (and otherwise issues a warning).
+
+When following by file descriptor (i.e., with @option{--follow=descriptor}),
+this option only affects the initial open of the file, as after a successful
+open, @command{tail} will start following the file descriptor.
+
+When following by name (i.e., with @option{--follow=name}), @command{tail}
+infinitely retries to re-open the given files until killed.
+
+Without this option, when @command{tail} encounters a file that doesn't
+exist or is otherwise inaccessible, it reports that fact and
+never checks it again.
+
+@item -s @var{number}
+@itemx --sleep-interval=@var{number}
+@opindex -s
+@opindex --sleep-interval
+Change the number of seconds to wait between iterations (the default is 1.0).
+During one iteration, every specified file is checked to see if it has
+changed size.
+Historical implementations of @command{tail} have required that
+@var{number} be an integer.  However, GNU @command{tail} accepts
+an arbitrary floating point number.  @xref{Floating point}.
+When @command{tail} uses inotify, this polling-related option
+is usually ignored.  However, if you also specify @option{--pid=@var{p}},
+@command{tail} checks whether process @var{p} is alive at least
+every @var{number} seconds.
+
 @item -v
 @itemx --verbose
 @opindex -v
@@ -3037,10 +3037,10 @@ Always print file name headers.
 @end table
 
 For compatibility @command{tail} also supports an obsolete usage
-@samp{tail -[@var{count}][bcl][f] [@var{file}]}, which is recognized
+@samp{tail -[@var{num}][bcl][f] [@var{file}]}, which is recognized
 only if it does not conflict with the usage described
 above.  This obsolete form uses exactly one option and at most one
-file.  In the option, @var{count} is an optional decimal number optionally
+file.  In the option, @var{num} is an optional decimal number optionally
 followed by a size letter (@samp{b}, @samp{c}, @samp{l}) to mean count
 by 512-byte blocks, bytes, or lines, optionally followed by @samp{f}
 which has the same meaning as @option{-f}.
@@ -3054,8 +3054,8 @@ This obsolete behavior can be enabled or disabled with the
 conformance}).
 
 Scripts intended for use on standard hosts should avoid obsolete
-syntax and should use @option{-c @var{count}[b]}, @option{-n
-@var{count}}, and/or @option{-f} instead.  If your script must also
+syntax and should use @option{-c @var{num}[b]}, @option{-n
+@var{num}}, and/or @option{-f} instead.  If your script must also
 run on hosts that support only the obsolete syntax, you can often
 rewrite it to avoid problematic usages, e.g., by using @samp{sed -n
 '$p'} rather than @samp{tail -1}.  If that's not possible, the script
diff --git a/src/head.c b/src/head.c
index e05c21935..448d89a6f 100644
--- a/src/head.c
+++ b/src/head.c
@@ -106,22 +106,22 @@ usage (int status)
 Usage: %s [OPTION]... [FILE]...\n\
 "),
               program_name);
-      fputs (_("\
-Print the first 10 lines of each FILE to standard output.\n\
+      printf (_("\
+Print the first %d lines of each FILE to standard output.\n\
 With more than one FILE, precede each with a header giving the file name.\n\
-"), stdout);
+"), DEFAULT_NUMBER);
 
       emit_stdin_note ();
       emit_mandatory_arg_note ();
 
-      fputs (_("\
-  -c, --bytes=[-]K         print the first K bytes of each file;\n\
+      printf (_("\
+  -c, --bytes=[-]NUM       print the first NUM bytes of each file;\n\
                              with the leading '-', print all but the last\n\
-                             K bytes of each file\n\
-  -n, --lines=[-]K         print the first K lines instead of the first 10;\n\
+                             NUM bytes of each file\n\
+  -n, --lines=[-]NUM       print the first NUM lines instead of the first %d;\n\
                              with the leading '-', print all but the last\n\
-                             K lines of each file\n\
-"), stdout);
+                             NUM lines of each file\n\
+"), DEFAULT_NUMBER);
       fputs (_("\
   -q, --quiet, --silent    never print headers giving file names\n\
   -v, --verbose            always print headers giving file names\n\
@@ -130,7 +130,7 @@ With more than one FILE, precede each with a header giving the file name.\n\
       fputs (VERSION_OPTION_DESCRIPTION, stdout);
       fputs (_("\
 \n\
-K may have a multiplier suffix:\n\
+NUM may have a multiplier suffix:\n\
 b 512, kB 1000, K 1024, MB 1000*1000, M 1024*1024,\n\
 GB 1000*1000*1000, G 1024*1024*1024, and so on for T, P, E, Z, Y.\n\
 "), stdout);
diff --git a/src/tail.c b/src/tail.c
index 223c8f839..0a515791f 100644
--- a/src/tail.c
+++ b/src/tail.c
@@ -263,8 +263,8 @@ With more than one FILE, precede each with a header giving the file name.\n\
       emit_mandatory_arg_note ();
 
      fputs (_("\
-  -c, --bytes=K            output the last K bytes; or use -c +K to output\n\
-                             bytes starting with the Kth of each file\n\
+  -c, --bytes=[+]NUM       output the last NUM bytes; or use -c +NUM to\n\
+                             output starting with byte NUM of each file\n\
 "), stdout);
      fputs (_("\
   -f, --follow[={name|descriptor}]\n\
@@ -273,8 +273,8 @@ With more than one FILE, precede each with a header giving the file name.\n\
   -F                       same as --follow=name --retry\n\
 "), stdout);
      printf (_("\
-  -n, --lines=K            output the last K lines, instead of the last %d;\n\
-                             or use -n +K to output starting with the Kth\n\
+  -n, --lines=[+]NUM       output the last NUM lines, instead of the last %d;\n\
+                             or use -n +NUM to output starting with line NUM\n\
       --max-unchanged-stats=N\n\
                            with --follow=name, reopen a FILE which has not\n\
                              changed size after N (default %d) iterations\n\
@@ -301,9 +301,7 @@ With more than one FILE, precede each with a header giving the file name.\n\
      fputs (VERSION_OPTION_DESCRIPTION, stdout);
      fputs (_("\
 \n\
-If the first character of K (the number of bytes or lines) is a '+',\n\
-print beginning with the Kth item from the start of each file, otherwise,\n\
-print the last K items in the file.  K may have a multiplier suffix:\n\
+NUM may have a multiplier suffix:\n\
 b 512, kB 1000, K 1024, MB 1000*1000, M 1024*1024,\n\
 GB 1000*1000*1000, G 1024*1024*1024, and so on for T, P, E, Z, Y.\n\
 \n\