From aafacd362db99b0227f6038c7840796d9ea017fb Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?P=C3=A1draig=20Brady?= <P@draigBrady.com>
Date: Thu, 20 Jul 2023 14:50:56 +0100
Subject: [PATCH] doc: clarify tail -n/-c +NUM operation

tail -n/-c +NUM, is different from tail -n/-c NUM,
and head -n/-c NUM, and head -n/c -NUM, in that it
specifies a 1 based index rather than a count to skip/include.
So clarify this in tail --help and tail info manual.
Note we also mention this gotcha at:
https://www.pixelbeat.org/docs/coreutils-gotchas.html#tail

* doc/coreutils.texi (tail invocation): Give examples for -c/-n +NUM,
so make it clear one has to specify a number 1 larger than
might be expected.
* src/tail.c (usage): State the skip at start edge case more clearly
in the -n description. -c is not often used with tail so we leave
full explanation of that to the info manual.  Also split the string
to simplify translation.
---
 doc/coreutils.texi | 10 ++++++----
 src/tail.c         |  7 +++++--
 2 files changed, 11 insertions(+), 6 deletions(-)

diff --git a/doc/coreutils.texi b/doc/coreutils.texi
index c3673fd3f..496e62f43 100644
--- a/doc/coreutils.texi
+++ b/doc/coreutils.texi
@@ -3090,8 +3090,9 @@ The program accepts the following options.  Also see @ref{Common options}.
 @opindex -c
 @opindex --bytes
 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.
+If @var{num} is prefixed with a @samp{+}, start printing with
+byte @var{num} from the start of each file. For example to skip the first byte
+use @code{tail -c +2}, while to skip all but the last byte use @code{tail -c 1}.
 @multiplierSuffixes{num}
 
 @item -f
@@ -3178,8 +3179,9 @@ and when following by name.
 @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.
+If @var{num} is prefixed with a @samp{+}, start printing with
+line @var{num} from the start of each file. For example to skip the first line
+use @code{tail -n +2}, while to skip all but the last line use @code{tail -n 1}.
 Size multiplier suffixes are the same as with the @option{-c} option.
 
 @item --pid=@var{pid}
diff --git a/src/tail.c b/src/tail.c
index a7e681f8e..f293551ea 100644
--- a/src/tail.c
+++ b/src/tail.c
@@ -283,7 +283,11 @@ With more than one FILE, precede each with a header giving the file name.\n\
 "), stdout);
      printf (_("\
   -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\
+                             or use -n +NUM to skip NUM-1 lines at the start\n\
+"),
+             DEFAULT_N_LINES
+             );
+     printf (_("\
       --max-unchanged-stats=N\n\
                            with --follow=name, reopen a FILE which has not\n\
                              changed size after N (default %d) iterations\n\
@@ -291,7 +295,6 @@ With more than one FILE, precede each with a header giving the file name.\n\
                              (this is the usual case of rotated log files);\n\
                              with inotify, this option is rarely useful\n\
 "),
-             DEFAULT_N_LINES,
              DEFAULT_MAX_N_UNCHANGED_STATS_BETWEEN_OPENS
              );
      fputs (_("\
-- 
2.41.0