GNU bug report logs - #6383
cat has misleading documentation

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 6383 in the body.
You can then email your comments to 6383 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: "Chas. Owens" <chas.owens <at> gmail.com>
To: bug-coreutils <at> gnu.org
Subject: cat has misleading documentation
Date: Wed, 9 Jun 2010 09:35:11 -0400

The -n option is documented as "number all output lines", but when -b
is present it only numbers non-blank lines.  The documentation should
read "number output lines".

-- 
Chas. Owens
wonkden.net
The most important skill a programmer can have is the ability to read.

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

From: Eric Blake <eblake <at> redhat.com>
To: 6383 <at> debbugs.gnu.org
Cc: chas.owens <at> gmail.com
Subject: Re: bug#6383: [PATCH] cat: improve documentation
Date: Wed,  9 Jun 2010 11:17:12 -0600

* src/cat.c (usage): Clarify that -b overrides -n.
* doc/coreutils.texi (cat invocation): Likewise.
* THANKS: Update.
Suggested by Chas. Owens, in bug 6383.
---

> The -n option is documented as "number all output lines", but when -b
> is present it only numbers non-blank lines.  The documentation should
> read "number output lines".

Thanks for the report.  -b in isolation also numbers lines; so it is
more an issue that -b overrides -n.  How about this patch, instead?

 THANKS             |    1 +
 doc/coreutils.texi |    3 ++-
 src/cat.c          |    2 +-
 3 files changed, 4 insertions(+), 2 deletions(-)

diff --git a/THANKS b/THANKS
index dce3c94..caa40de 100644
--- a/THANKS
+++ b/THANKS
diff --git a/doc/coreutils.texi b/doc/coreutils.texi
index 26b4eba..b27d9d7 100644
--- a/doc/coreutils.texi
+++ b/doc/coreutils.texi
@@ -1494,7 +1494,8 @@ cat invocation
 @itemx --number
 @opindex -n
 @opindex --number
-Number all output lines, starting with 1.
+Number all output lines, starting with 1.  This option is ignored
+if @option{-b} is in effect.

 @item -s
 @itemx --squeeze-blank
diff --git a/src/cat.c b/src/cat.c
index eebfb97..c4a2a9e 100644
--- a/src/cat.c
+++ b/src/cat.c
@@ -92,7 +92,7 @@ Usage: %s [OPTION]... [FILE]...\n\
 Concatenate FILE(s), or standard input, to standard output.\n\
 \n\
   -A, --show-all           equivalent to -vET\n\
-  -b, --number-nonblank    number nonempty output lines\n\
+  -b, --number-nonblank    number nonempty output lines, overrides -n\n\
   -e                       equivalent to -vE\n\
   -E, --show-ends          display $ at end of each line\n\
   -n, --number             number all output lines\n\
-- 
1.7.0.1

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

From: "Chas. Owens" <chas.owens <at> gmail.com>
To: Eric Blake <eblake <at> redhat.com>
Cc: 6383 <at> debbugs.gnu.org
Subject: Re: bug#6383: [PATCH] cat: improve documentation
Date: Wed, 9 Jun 2010 13:25:51 -0400

That would work as well.  I suggested removing the "all" because it
was the simplest solution and would move the text closer to what BSD
uses, but this spells out the behavior explicitly.

On Wed, Jun 9, 2010 at 13:17, Eric Blake <eblake <at> redhat.com> wrote:
> * src/cat.c (usage): Clarify that -b overrides -n.
> * doc/coreutils.texi (cat invocation): Likewise.
> * THANKS: Update.
> Suggested by Chas. Owens, in bug 6383.
> ---
>
>> The -n option is documented as "number all output lines", but when -b
>> is present it only numbers non-blank lines.  The documentation should
>> read "number output lines".
>
> Thanks for the report.  -b in isolation also numbers lines; so it is
> more an issue that -b overrides -n.  How about this patch, instead?
>
>  THANKS             |    1 +
>  doc/coreutils.texi |    3 ++-
>  src/cat.c          |    2 +-
>  3 files changed, 4 insertions(+), 2 deletions(-)
>
> diff --git a/THANKS b/THANKS
> index dce3c94..caa40de 100644
> --- a/THANKS
> +++ b/THANKS
> diff --git a/doc/coreutils.texi b/doc/coreutils.texi
> index 26b4eba..b27d9d7 100644
> --- a/doc/coreutils.texi
> +++ b/doc/coreutils.texi
> @@ -1494,7 +1494,8 @@ cat invocation
>  @itemx --number
>  @opindex -n
>  @opindex --number
> -Number all output lines, starting with 1.
> +Number all output lines, starting with 1.  This option is ignored
> +if @option{-b} is in effect.
>
>  @item -s
>  @itemx --squeeze-blank
> diff --git a/src/cat.c b/src/cat.c
> index eebfb97..c4a2a9e 100644
> --- a/src/cat.c
> +++ b/src/cat.c
> @@ -92,7 +92,7 @@ Usage: %s [OPTION]... [FILE]...\n\
>  Concatenate FILE(s), or standard input, to standard output.\n\
>  \n\
>   -A, --show-all           equivalent to -vET\n\
> -  -b, --number-nonblank    number nonempty output lines\n\
> +  -b, --number-nonblank    number nonempty output lines, overrides -n\n\
>   -e                       equivalent to -vE\n\
>   -E, --show-ends          display $ at end of each line\n\
>   -n, --number             number all output lines\n\
> --
> 1.7.0.1
>
>



-- 
Chas. Owens
wonkden.net
The most important skill a programmer can have is the ability to read.

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

From: Eric Blake <eblake <at> redhat.com>
To: "Chas. Owens" <chas.owens <at> gmail.com>
Cc: 6383 <at> debbugs.gnu.org
Subject: Re: bug#6383: [PATCH] cat: improve documentation
Date: Mon, 14 Jun 2010 15:56:41 -0600

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

On 06/09/2010 11:25 AM, Chas. Owens wrote:

[please don't top-post on technical forums]

> That would work as well.  I suggested removing the "all" because it
> was the simplest solution and would move the text closer to what BSD
> uses, but this spells out the behavior explicitly.
> 
> On Wed, Jun 9, 2010 at 13:17, Eric Blake <eblake <at> redhat.com> wrote:
>> * src/cat.c (usage): Clarify that -b overrides -n.
>> * doc/coreutils.texi (cat invocation): Likewise.
>> * THANKS: Update.
>> Suggested by Chas. Owens, in bug 6383.

No other comments, so I went ahead and pushed the patch.

Thanks again for the report!

-- 
Eric Blake   eblake <at> redhat.com    +1-801-349-2682
Libvirt virtualization library http://libvirt.org

[signature.asc (application/pgp-signature, attachment)]

Previous Next

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