GNU bug report logs - #22042
don't say K bytes on both head and tail's man pages

Previous Next

To add a comment to this bug, you must first unarchive it, by sending
a message to control AT debbugs.gnu.org, with unarchive 22042 in the body.
You can then email your comments to 22042 AT debbugs.gnu.org in the normal way.

Toggle the display of automated, internal messages from the tracker.

Message #5 received at submit <at> debbugs.gnu.org (full text, mbox):

From: Dan Jacobson <jidanni <at> jidanni.org>
To: bug-coreutils <at> gnu.org
Subject: don't say K bytes on both head and tail's man pages
Date: Sun, 29 Nov 2015 04:01:12 +0800

On both the head and tail man pages,
can you kindly not use "K"?

       -c, --bytes=K
              output the last K bytes; or use -c +K to output  bytes  starting
              with the Kth of each file

K bytes sounds like kilobytes.

Yes if one reads carefully it doesn't.

But instead if you used X, then one needn't read carefully and could
still read the page!

Or how about B? B bytes. Sounds even better than X.

Anyway it (K) appears several places on both man pages.

Message #8 received at 22042 <at> debbugs.gnu.org (full text, mbox):

From: Bernhard Voelker <mail <at> bernhard-voelker.de>
To: Dan Jacobson <jidanni <at> jidanni.org>, 22042 <at> debbugs.gnu.org
Subject: Re: bug#22042: don't say K bytes on both head and tail's man pages
Date: Sat, 28 Nov 2015 21:45:39 +0100

On 11/28/2015 09:01 PM, Dan Jacobson wrote:
> On both the head and tail man pages,
> can you kindly not use "K"?
> 
>        -c, --bytes=K
>               output the last K bytes; or use -c +K to output  bytes  starting
>               with the Kth of each file
> 
> K bytes sounds like kilobytes.
> 
> Yes if one reads carefully it doesn't.
> 
> But instead if you used X, then one needn't read carefully and could
> still read the page!
> 
> Or how about B? B bytes. Sounds even better than X.
> 
> Anyway it (K) appears several places on both man pages.

Thanks.
Another good spot.
I'd rather use 'N' as many users would more likely see this as
'N'umeric argument.  The following does that ... plus also switching
2 other placeholders to avoid overlapping with the explanation regarding
the suffixes K, M, G, T, etc.

Have a nice day,
Berny

From bc5ac10be70600a012e917f17c828bbc73fb2e78 Mon Sep 17 00:00:00 2001
From: Bernhard Voelker <mail <at> bernhard-voelker.de>
Date: Sat, 28 Nov 2015 21:39:23 +0100
Subject: [PATCH] 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 N instead.

* src/head.c (usage): s/K/N/ in as placeholder in the -c and -n option.
* src/tail.c (usage): Likewise.  Furthermore, disambiguate the place-
holders by using 'U' for the --max-unchanged-stats, and 'S' for the
--sleep-interval options.

Suggested by Dan Jacobson in http://bugs.gnu.org/22042
---
 src/head.c | 10 +++++-----
 src/tail.c | 22 +++++++++++-----------
 2 files changed, 16 insertions(+), 16 deletions(-)

diff --git a/src/head.c b/src/head.c
index e05c219..31d4609 100644
--- a/src/head.c
+++ b/src/head.c
@@ -115,12 +115,12 @@ With more than one FILE, precede each with a header giving the file name.\n\
       emit_mandatory_arg_note ();

       fputs (_("\
-  -c, --bytes=[-]K         print the first K bytes of each file;\n\
+  -c, --bytes=[-]N         print the first N 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\
+                             N bytes of each file\n\
+  -n, --lines=[-]N         print the first N lines instead of the first 10;\n\
                              with the leading '-', print all but the last\n\
-                             K lines of each file\n\
+                             N lines of each file\n\
 "), stdout);
       fputs (_("\
   -q, --quiet, --silent    never 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\
+N 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 223c8f8..ada3373 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=N            output the last N bytes; or use -c +N to output\n\
+                             bytes starting with the Nth of each file\n\
 "), stdout);
      fputs (_("\
   -f, --follow[={name|descriptor}]\n\
@@ -273,11 +273,11 @@ 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\
-      --max-unchanged-stats=N\n\
+  -n, --lines=N            output the last N lines, instead of the last %d;\n\
+                             or use -n +N to output starting with the Nth\n\
+      --max-unchanged-stats=U\n\
                            with --follow=name, reopen a FILE which has not\n\
-                             changed size after N (default %d) iterations\n\
+                             changed size after U (default %d) iterations\n\
                              to see if it has been unlinked or renamed\n\
                              (this is the usual case of rotated log files);\n\
                              with inotify, this option is rarely useful\n\
@@ -291,19 +291,19 @@ With more than one FILE, precede each with a header giving the file name.\n\
       --retry              keep trying to open a file if it is inaccessible\n\
 "), stdout);
      fputs (_("\
-  -s, --sleep-interval=N   with -f, sleep for approximately N seconds\n\
+  -s, --sleep-interval=S   with -f, sleep for approximately S seconds\n\
                              (default 1.0) between iterations;\n\
                              with inotify and --pid=P, check process P at\n\
-                             least once every N seconds\n\
+                             least once every S seconds\n\
   -v, --verbose            always output headers giving file names\n\
 "), stdout);
      fputs (HELP_OPTION_DESCRIPTION, stdout);
      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\
+If the first character of N (the number of bytes or lines) is a '+',\n\
+print beginning with the Nth item from the start of each file, otherwise,\n\
+print the last N items in the file.  N 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\
-- 
2.1.4

Message #11 received at 22042 <at> debbugs.gnu.org (full text, mbox):

From: Bernhard Voelker <mail <at> bernhard-voelker.de>
To: Dan Jacobson <jidanni <at> jidanni.org>, 22042 <at> debbugs.gnu.org,
 Eric Blake <eblake <at> redhat.com>
Subject: Re: bug#22042: don't say K bytes on both head and tail's man pages
Date: Sun, 29 Nov 2015 00:02:30 +0100

On 11/28/2015 09:45 PM, Bernhard Voelker wrote:
> On 11/28/2015 09:01 PM, Dan Jacobson wrote:
>> On both the head and tail man pages,
>> can you kindly not use "K"?
>>
>>        -c, --bytes=K
>>               output the last K bytes; or use -c +K to output  bytes  starting
>>               with the Kth of each file
>>
>> K bytes sounds like kilobytes.
>>
>> Yes if one reads carefully it doesn't.
>>
>> But instead if you used X, then one needn't read carefully and could
>> still read the page!
>>
>> Or how about B? B bytes. Sounds even better than X.
>>
>> Anyway it (K) appears several places on both man pages.
> 
> Thanks.
> Another good spot.
> I'd rather use 'N' as many users would more likely see this as
> 'N'umeric argument.  The following does that ... plus also switching
> 2 other placeholders to avoid overlapping with the explanation regarding
> the suffixes K, M, G, T, etc.

oops, Eric applied the opposite patch 6 years ago:
  http://git.sv.gnu.org/cgit/coreutils.git/commit/?id=v7.4-18-gc433334

The archives (http://lists.gnu.org/archive/html/coreutils/) start 2010,
so does anyone remember why K would be less ambigous than N?

Have a nice day,
Berny

Message #14 received at 22042 <at> debbugs.gnu.org (full text, mbox):

From: Pádraig Brady <P <at> draigBrady.com>
To: Bernhard Voelker <mail <at> bernhard-voelker.de>,
 Dan Jacobson <jidanni <at> jidanni.org>, 22042 <at> debbugs.gnu.org,
 Eric Blake <eblake <at> redhat.com>
Subject: Re: bug#22042: don't say K bytes on both head and tail's man pages
Date: Sat, 28 Nov 2015 23:16:21 +0000

On 28/11/15 23:02, Bernhard Voelker wrote:
> On 11/28/2015 09:45 PM, Bernhard Voelker wrote:
>> On 11/28/2015 09:01 PM, Dan Jacobson wrote:
>>> On both the head and tail man pages,
>>> can you kindly not use "K"?
>>>
>>>        -c, --bytes=K
>>>               output the last K bytes; or use -c +K to output  bytes  starting
>>>               with the Kth of each file
>>>
>>> K bytes sounds like kilobytes.
>>>
>>> Yes if one reads carefully it doesn't.
>>>
>>> But instead if you used X, then one needn't read carefully and could
>>> still read the page!
>>>
>>> Or how about B? B bytes. Sounds even better than X.
>>>
>>> Anyway it (K) appears several places on both man pages.
>>
>> Thanks.
>> Another good spot.
>> I'd rather use 'N' as many users would more likely see this as
>> 'N'umeric argument.  The following does that ... plus also switching
>> 2 other placeholders to avoid overlapping with the explanation regarding
>> the suffixes K, M, G, T, etc.
> 
> oops, Eric applied the opposite patch 6 years ago:
>   http://git.sv.gnu.org/cgit/coreutils.git/commit/?id=v7.4-18-gc433334
> 
> The archives (http://lists.gnu.org/archive/html/coreutils/) start 2010,
> so does anyone remember why K would be less ambigous than N?

The mailing list split around then:
I remember having slight reservations about K too.
http://lists.gnu.org/archive/html/bug-coreutils/2009-05/msg00279.html
Nothing much better comes to mind.

cheers,
Pádraig

Message #17 received at 22042 <at> debbugs.gnu.org (full text, mbox):

From: Assaf Gordon <assafgordon <at> gmail.com>
To: Pádraig Brady <P <at> draigBrady.com>,
 Bernhard Voelker <mail <at> bernhard-voelker.de>,
 Dan Jacobson <jidanni <at> jidanni.org>, 22042 <at> debbugs.gnu.org,
 Eric Blake <eblake <at> redhat.com>
Subject: Re: bug#22042: don't say K bytes on both head and tail's man pages
Date: Sat, 28 Nov 2015 18:31:11 -0500

On 11/28/2015 06:16 PM, Pádraig Brady wrote:
> On 28/11/15 23:02, Bernhard Voelker wrote:
>>
>> The archives (http://lists.gnu.org/archive/html/coreutils/) start 2010,
>> so does anyone remember why K would be less ambigous than N?
>
> The mailing list split around then:
> I remember having slight reservations about K too.
> http://lists.gnu.org/archive/html/bug-coreutils/2009-05/msg00279.html
> Nothing much better comes to mind.

Likely this message:
http://lists.gnu.org/archive/html/bug-coreutils/2009-05/msg00200.html

Perhaps it was too similar/confusing to the (now discouraged) usage of "-N" with N being a digit (e.g. "head -9" to display 9 lines) ?


Slightly off topic,
if you want to search in multiple gnu mailing lists at once,
this hack might help:
  http://search.housegordon.org/

regards,
 -assaf

Message #20 received at 22042 <at> debbugs.gnu.org (full text, mbox):

From: Bernhard Voelker <mail <at> bernhard-voelker.de>
To: Pádraig Brady <P <at> draigBrady.com>,
 Dan Jacobson <jidanni <at> jidanni.org>, 22042 <at> debbugs.gnu.org,
 Eric Blake <eblake <at> redhat.com>
Subject: Re: bug#22042: don't say K bytes on both head and tail's man pages
Date: Mon, 30 Nov 2015 00:35:55 +0100

On 11/29/2015 12:16 AM, Pádraig Brady wrote:
> I remember having slight reservations about K too.
> http://lists.gnu.org/archive/html/bug-coreutils/2009-05/msg00279.html
> Nothing much better comes to mind.

Thanks.
In that discussion, also longer alternatives like COUNT or CNT were
mentioned.  If we decide to go that way, I'd favor NUM among those
suggestions, as it may also be used as is in translations.

While at it, I'm wondering if it would make sense to emphasize
the optional plus ('+') for tail in the first column, similar as
for the minus ('-') for head (although only for 'man head', but
not in the Texi documentation):

  $ src/head --help | grep -A2 -- '^[ ]*-[cn]'
    -c, --bytes=[-]K         print the first K bytes of each file;
                               with the leading '-', print all but the last
                               K bytes of each file
    -n, --lines=[-]K         print the first K lines instead of the first 10;
                               with the leading '-', print all but the last
                               K lines of each file

  $ src/tail --help | grep -A1 -- '^[ ]*-[cn]'
    -c, --bytes=K            output the last K bytes; or use -c +K to output
                               bytes starting with the Kth of each file
  --
    -n, --lines=K            output the last K lines, instead of the last 10;
                               or use -n +K to output starting with the Kth

Is there some GNU standard for this?  I couldn't find much.

Have a nice day,
Berny

Message #23 received at 22042 <at> debbugs.gnu.org (full text, mbox):

From: Pádraig Brady <P <at> draigBrady.com>
To: Bernhard Voelker <mail <at> bernhard-voelker.de>,
 Dan Jacobson <jidanni <at> jidanni.org>, 22042 <at> debbugs.gnu.org,
 Eric Blake <eblake <at> redhat.com>
Subject: Re: bug#22042: don't say K bytes on both head and tail's man pages
Date: Mon, 30 Nov 2015 14:52:14 +0000

On 29/11/15 23:35, Bernhard Voelker wrote:
> On 11/29/2015 12:16 AM, Pádraig Brady wrote:
>> I remember having slight reservations about K too.
>> http://lists.gnu.org/archive/html/bug-coreutils/2009-05/msg00279.html
>> Nothing much better comes to mind.
> 
> Thanks.
> In that discussion, also longer alternatives like COUNT or CNT were
> mentioned.  If we decide to go that way, I'd favor NUM among those
> suggestions, as it may also be used as is in translations.
> 
> While at it, I'm wondering if it would make sense to emphasize
> the optional plus ('+') for tail in the first column, similar as
> for the minus ('-') for head (although only for 'man head', but
> not in the Texi documentation):
> 
>   $ src/head --help | grep -A2 -- '^[ ]*-[cn]'
>     -c, --bytes=[-]K         print the first K bytes of each file;
>                                with the leading '-', print all but the last
>                                K bytes of each file
>     -n, --lines=[-]K         print the first K lines instead of the first 10;
>                                with the leading '-', print all but the last
>                                K lines of each file
> 
>   $ src/tail --help | grep -A1 -- '^[ ]*-[cn]'
>     -c, --bytes=K            output the last K bytes; or use -c +K to output
>                                bytes starting with the Kth of each file
>   --
>     -n, --lines=K            output the last K lines, instead of the last 10;
>                                or use -n +K to output starting with the Kth
> 
> Is there some GNU standard for this?  I couldn't find much.

+1 for [+]NUM

cheers,
Pádraig

Message #26 received at 22042 <at> debbugs.gnu.org (full text, mbox):

From: Jim Meyering <jim <at> meyering.net>
To: Pádraig Brady <P <at> draigbrady.com>
Cc: Bernhard Voelker <mail <at> bernhard-voelker.de>, Eric Blake <eblake <at> redhat.com>,
 22042 <at> debbugs.gnu.org, Dan Jacobson <jidanni <at> jidanni.org>
Subject: Re: bug#22042: don't say K bytes on both head and tail's man pages
Date: Mon, 30 Nov 2015 09:23:17 -0800

On Mon, Nov 30, 2015 at 6:52 AM, Pádraig Brady <P <at> draigbrady.com> wrote:
> On 29/11/15 23:35, Bernhard Voelker wrote:
>> On 11/29/2015 12:16 AM, Pádraig Brady wrote:
>>> I remember having slight reservations about K too.
>>> http://lists.gnu.org/archive/html/bug-coreutils/2009-05/msg00279.html
>>> Nothing much better comes to mind.
>>
>> Thanks.
>> In that discussion, also longer alternatives like COUNT or CNT were
>> mentioned.  If we decide to go that way, I'd favor NUM among those
>> suggestions, as it may also be used as is in translations.
>>
>> While at it, I'm wondering if it would make sense to emphasize
>> the optional plus ('+') for tail in the first column, similar as
>> for the minus ('-') for head (although only for 'man head', but
>> not in the Texi documentation):
>>
>>   $ src/head --help | grep -A2 -- '^[ ]*-[cn]'
>>     -c, --bytes=[-]K         print the first K bytes of each file;
>>                                with the leading '-', print all but the last
>>                                K bytes of each file
>>     -n, --lines=[-]K         print the first K lines instead of the first 10;
>>                                with the leading '-', print all but the last
>>                                K lines of each file
>>
>>   $ src/tail --help | grep -A1 -- '^[ ]*-[cn]'
>>     -c, --bytes=K            output the last K bytes; or use -c +K to output
>>                                bytes starting with the Kth of each file
>>   --
>>     -n, --lines=K            output the last K lines, instead of the last 10;
>>                                or use -n +K to output starting with the Kth
>>
>> Is there some GNU standard for this?  I couldn't find much.
>
> +1 for [+]NUM

Fine with me, except for "NUMth" or "NUM'th", which do not read well.
I guess we could change s/with the Kth/with line NUM/

Message #29 received at 22042 <at> debbugs.gnu.org (full text, mbox):

From: Paul Eggert <eggert <at> cs.ucla.edu>
To: Jim Meyering <jim <at> meyering.net>, Pádraig Brady
 <P <at> draigbrady.com>
Cc: Bernhard Voelker <mail <at> bernhard-voelker.de>, Eric Blake <eblake <at> redhat.com>,
 22042 <at> debbugs.gnu.org, Dan Jacobson <jidanni <at> jidanni.org>
Subject: Re: bug#22042: don't say K bytes on both head and tail's man pages
Date: Mon, 30 Nov 2015 09:30:28 -0800

On 11/30/2015 09:23 AM, Jim Meyering wrote:
> Fine with me, except for "NUMth" or "NUM'th", which do not read well.

The more-common usage is "NUMBERth", generated by 'tar --help' and also 
used in the sed manual.  It's a little odd but it sort of rhymes with 
"fourth".

Message #32 received at 22042 <at> debbugs.gnu.org (full text, mbox):

From: Bernhard Voelker <mail <at> bernhard-voelker.de>
To: Paul Eggert <eggert <at> cs.ucla.edu>, Jim Meyering <jim <at> meyering.net>,
 Pádraig Brady <P <at> draigbrady.com>
Cc: Eric Blake <eblake <at> redhat.com>, 22042 <at> debbugs.gnu.org,
 Dan Jacobson <jidanni <at> jidanni.org>
Subject: Re: bug#22042: don't say K bytes on both head and tail's man pages
Date: Mon, 30 Nov 2015 22:14:11 +0100

[Message part 1 (text/plain, inline)]

On 11/30/2015 06:30 PM, Paul Eggert wrote:
> On 11/30/2015 09:23 AM, Jim Meyering wrote:
>> Fine with me, except for "NUMth" or "NUM'th", which do not read well.
> 
> The more-common usage is "NUMBERth", generated by 'tar --help' and also 
> used in the sed manual.  It's a little odd but it sort of rhymes with 
> "fourth".

Thanks for all the suggestions.
I think NUMBER is a bit long, and reduces the space for the description,
or it my destroy the aligning.

My suggestion is NUM (which is also used in grep(1) BTW).
Patch attached ... it's just not so tiny because I also fixed the order
of the options of tail in the Texinfo manual.

Have a nice day,
Berny

[0001-doc-avoid-confusing-K-argument-in-the-man-pages-of-h.patch (text/x-patch, attachment)]

Message #37 received at 22042-done <at> debbugs.gnu.org (full text, mbox):

From: Pádraig Brady <P <at> draigBrady.com>
To: Bernhard Voelker <mail <at> bernhard-voelker.de>
Cc: Dan Jacobson <jidanni <at> jidanni.org>, 22042-done <at> debbugs.gnu.org
Subject: Re: bug#22042: don't say K bytes on both head and tail's man pages
Date: Mon, 30 Nov 2015 22:36:23 +0000

On 30/11/15 21:14, Bernhard Voelker wrote:
> On 11/30/2015 06:30 PM, Paul Eggert wrote:
>> On 11/30/2015 09:23 AM, Jim Meyering wrote:
>>> Fine with me, except for "NUMth" or "NUM'th", which do not read well.
>>
>> The more-common usage is "NUMBERth", generated by 'tar --help' and also 
>> used in the sed manual.  It's a little odd but it sort of rhymes with 
>> "fourth".
> 
> Thanks for all the suggestions.
> I think NUMBER is a bit long, and reduces the space for the description,
> or it my destroy the aligning.
> 
> My suggestion is NUM (which is also used in grep(1) BTW).
> Patch attached ... it's just not so tiny because I also fixed the order
> of the options of tail in the Texinfo manual.

Lots of little changes adding up to a much better result.

Looks good.

Marking bug as done.

thanks!
Pádraig

Message #40 received at 22042-done <at> debbugs.gnu.org (full text, mbox):

From: Bernhard Voelker <mail <at> bernhard-voelker.de>
To: Pádraig Brady <P <at> draigBrady.com>
Cc: Dan Jacobson <jidanni <at> jidanni.org>, 22042-done <at> debbugs.gnu.org
Subject: Re: bug#22042: don't say K bytes on both head and tail's man pages
Date: Tue, 1 Dec 2015 08:47:55 +0100

On 11/30/2015 11:36 PM, Pádraig Brady wrote:
> Looks good.
> 
> Marking bug as done.

Thanks, pushed at
http://git.sv.gnu.org/cgit/coreutils.git/commit/?id=f7ab20c

Have a nice day,
Berny

Previous Next

GNU bug tracking system
Copyright (C) 1999 Darren O. Benham, 1997,2003 nCipher Corporation Ltd, 1994-97 Ian Jackson.