On 19/07/2023 19:21, Dragan Simic wrote:
Clarify that the NUM values for head and tail are indices, and briefly
describe the specifics of +NUM for tail.
Signed-off-by: Dragan Simic <dsi...@manjaro.org>
---
src/head.c | 3 ++-
src/tail.c | 4 +++-
2 files changed, 5 insertions(+), 2 deletions(-)
diff --git a/src/head.c b/src/head.c
index 7bba1420c..e82f9e195 100644
--- a/src/head.c
+++ b/src/head.c
@@ -137,7 +137,8 @@ With more than one FILE, precede each with a header giving
the file name.\n\
fputs (VERSION_OPTION_DESCRIPTION, stdout);
fputs (_("\
\n\
-NUM may have a multiplier suffix:\n\
+NUM values are indices, thus counting lines and bytes in a file starts\n\
+from one. NUM may also 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, R, Q.\n\
Binary prefixes can be used, too: KiB=K, MiB=M, and so on.\n\
Well only tail -n+NUM is an index,
whereas the other combinations would be most generally considered
as a count (to skip or include).
Also this doesn't specify if the index is 0 or 1 based.
I'll apply the attached instead, which I think clarifies things.
thanks,
Pádraig
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
