GNU bug report logs - #9497
join: suggestion for manpage/help enhacement

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 9497 in the body.
You can then email your comments to 9497 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: Tomas Volka <tomas.volka <at> unicorn.eu>
To: bug-coreutils <at> gnu.org
Subject: join: suggestion for manpage/help enhacement
Date: Tue, 13 Sep 2011 23:55:40 +0200

Hi,

i'm using join from time to time with varying parameters,
but just recently, i've spent quite a long time discovering
what's wrong with my command:

ie.: join -a 1 foo bar

Above outputs paired lines *AND* unpairable lines from foo,
but it is not apparent from the --help output and manpage.

join --help states:
  -a FILENUM print unpairable lines coming from file FILENUM,
  where FILENUM is 1 or 2, corresponding to FILE1 or FILE2

man join states:
  -a FILENUM print unpairable lines coming from file FILENUM, 
  where FILENUM is 1 or 2, corresponding to FILE1 or FILE2

info join states:
  `-a FILE-NUMBER'  Print a line for each unpairable line in 
   file FILE-NUMBER (either `1' or `2'), in addition to the normal 
   output.

Thus i've spent quite some time figuring why is the 'normal output'
showing up in my result, before i discovered the more detailed
description in the info page (and used -v 1 parameter instead).

I suggest to include this important fact in manpage and --help output.

Regards,
Tom

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

From: Eric Blake <eblake <at> redhat.com>
To: Tomas Volka <tomas.volka <at> unicorn.eu>
Cc: 9497 <at> debbugs.gnu.org
Subject: Re: bug#9497: join: suggestion for manpage/help enhacement
Date: Tue, 13 Sep 2011 16:08:16 -0600

On 09/13/2011 03:55 PM, Tomas Volka wrote:
> Hi,
>
> i'm using join from time to time with varying parameters,
> but just recently, i've spent quite a long time discovering
> what's wrong with my command:
>
> ie.: join -a 1 foo bar
>
> Above outputs paired lines *AND* unpairable lines from foo,
> but it is not apparent from the --help output and manpage.
>
> join --help states:
>    -a FILENUM print unpairable lines coming from file FILENUM,
>    where FILENUM is 1 or 2, corresponding to FILE1 or FILE2

Thanks for the report.  We do have this line later for -v:

  -v FILENUM        like -a FILENUM, but suppress joined output lines

If you read both -a and -v, then you realize that -a does more output 
than -v.  But I agree that this is confusing, and that we can do better.

>
> man join states:
>    -a FILENUM print unpairable lines coming from file FILENUM,
>    where FILENUM is 1 or 2, corresponding to FILE1 or FILE2

The man page is generated from --help output, so fixing one fixes the other.

>
> info join states:
>    `-a FILE-NUMBER'  Print a line for each unpairable line in
>     file FILE-NUMBER (either `1' or `2'), in addition to the normal
>     output.

Yes, this is more accurate, and matches the POSIX wording:

http://pubs.opengroup.org/onlinepubs/9699919799/utilities/join.html
"-a  file_number
    Produce a line for each unpairable line in file file_number, where 
file_number is 1 or 2, in addition to the default output. If both -a1 
and -a2 are specified, all unpairable lines shall be output.
...
-v  file_number
    Instead of the default output, produce a line only for each 
unpairable line in file_number, where file_number is 1 or 2. If both -v1 
and -v2 are specified, all unpairable lines shall be output."

>
> Thus i've spent quite some time figuring why is the 'normal output'
> showing up in my result, before i discovered the more detailed
> description in the info page (and used -v 1 parameter instead).
>
> I suggest to include this important fact in manpage and --help output.

How about the following patch, which adds "also", while maintaining line 
length by deleting the fluff word "coming"?

From 31046b6d38ab49cb815c8f6c6bc4faf6bb596de6 Mon Sep 17 00:00:00 2001
From: Eric Blake <eblake <at> redhat.com>
Date: Tue, 13 Sep 2011 16:07:11 -0600
Subject: [PATCH] join: clarify -a behavior

* src/join.c (usage): Mention that -a adds to the overall output,
rather than replacing the default output.
Suggested by Tomas Volka.
---
 src/join.c |    2 +-
 1 files changed, 1 insertions(+), 1 deletions(-)

diff --git a/src/join.c b/src/join.c
index 694fb55..809eead 100644
--- a/src/join.c
+++ b/src/join.c
@@ -194,7 +194,7 @@ For each pair of input lines with identical join 
fields, write a line to\n\
 standard output.  The default join field is the first, delimited\n\
 by whitespace.  When FILE1 or FILE2 (not both) is -, read standard 
input.\n\
 \n\
-  -a FILENUM        print unpairable lines coming from file FILENUM, 
where\n\
+  -a FILENUM        also print unpairable lines from file FILENUM, where\n\
                       FILENUM is 1 or 2, corresponding to FILE1 or 
FILE2\n\
   -e EMPTY          replace missing input fields with EMPTY\n\
 "), stdout);
-- 
1.7.4.4



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

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

From: Tomas Volka <tomas.volka <at> unicorn.eu>
To: Eric Blake <eblake <at> redhat.com>
Cc: 9497 <at> debbugs.gnu.org
Subject: Re: bug#9497: join: suggestion for manpage/help enhacement
Date: Wed, 14 Sep 2011 00:48:23 +0200

On Út 13-09-11 | 16:08, Eric Blake wrote:

> If you read both -a and -v, then you realize that -a does more output 
> than -v.  But I agree that this is confusing, and that we can do better.

I agree. Most users will stop reading the manpage when they reach
-a and will expect -v like behavior ( because they didn't reached the -v
yet ). 

> How about the following patch, which adds "also", while maintaining
> line length by deleting the fluff word "coming"?
> 
> From 31046b6d38ab49cb815c8f6c6bc4faf6bb596de6 Mon Sep 17 00:00:00 2001
> From: Eric Blake <eblake <at> redhat.com>
> Date: Tue, 13 Sep 2011 16:07:11 -0600
> Subject: [PATCH] join: clarify -a behavior
> 
> * src/join.c (usage): Mention that -a adds to the overall output,
> rather than replacing the default output.
> Suggested by Tomas Volka.
> ---
>  src/join.c |    2 +-
>  1 files changed, 1 insertions(+), 1 deletions(-)
> 
> diff --git a/src/join.c b/src/join.c
> index 694fb55..809eead 100644
> --- a/src/join.c
> +++ b/src/join.c
> @@ -194,7 +194,7 @@ For each pair of input lines with identical join
> fields, write a line to\n\
>  standard output.  The default join field is the first, delimited\n\
>  by whitespace.  When FILE1 or FILE2 (not both) is -, read standard
> input.\n\
>  \n\
> -  -a FILENUM        print unpairable lines coming from file
> FILENUM, where\n\
> +  -a FILENUM        also print unpairable lines from file FILENUM, where\n\
>                        FILENUM is 1 or 2, corresponding to FILE1 or
> FILE2\n\
>    -e EMPTY          replace missing input fields with EMPTY\n\
>  "), stdout);


Yes, i think that the patch above is completely sufficient.

Tom

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

From: Jim Meyering <jim <at> meyering.net>
To: Eric Blake <eblake <at> redhat.com>
Cc: Tomas Volka <tomas.volka <at> unicorn.eu>, 9497-done <at> debbugs.gnu.org
Subject: Re: bug#9497: join: suggestion for manpage/help enhacement
Date: Wed, 14 Sep 2011 09:25:11 +0200

Eric Blake wrote:
...
> How about the following patch, which adds "also", while maintaining line length by deleting the fluff word "coming"?
>
> From 31046b6d38ab49cb815c8f6c6bc4faf6bb596de6 Mon Sep 17 00:00:00 2001
> From: Eric Blake <eblake <at> redhat.com>
> Date: Tue, 13 Sep 2011 16:07:11 -0600
> Subject: [PATCH] join: clarify -a behavior

Thank you both.

Please change the one-line summary to start with "doc: " e.g.,

    doc: improve description of join's -a option

so that a naive categorization lists it as a documentation change
rather than a join bug fix

I've marked this as done.

> * src/join.c (usage): Mention that -a adds to the overall output,
> rather than replacing the default output.
> Suggested by Tomas Volka.
> ---
>  src/join.c |    2 +-
>  1 files changed, 1 insertions(+), 1 deletions(-)
>
> diff --git a/src/join.c b/src/join.c
> index 694fb55..809eead 100644
> --- a/src/join.c
> +++ b/src/join.c
> @@ -194,7 +194,7 @@ For each pair of input lines with identical join fields, write a line to\n\
>  standard output.  The default join field is the first, delimited\n\
>  by whitespace.  When FILE1 or FILE2 (not both) is -, read standard input.\n\
>  \n\
> -  -a FILENUM        print unpairable lines coming from file FILENUM, where\n\
> +  -a FILENUM        also print unpairable lines from file FILENUM, where\n\
>                        FILENUM is 1 or 2, corresponding to FILE1 or FILE2\n\
>    -e EMPTY          replace missing input fields with EMPTY\n\
>  "), stdout);
> --
> 1.7.4.4

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

From: Eric Blake <eblake <at> redhat.com>
To: Jim Meyering <jim <at> meyering.net>
Cc: Tomas Volka <tomas.volka <at> unicorn.eu>, 9497-done <at> debbugs.gnu.org
Subject: Re: bug#9497: join: suggestion for manpage/help enhacement
Date: Wed, 14 Sep 2011 07:49:58 -0600

On 09/14/2011 01:25 AM, Jim Meyering wrote:
> Please change the one-line summary to start with "doc: " e.g.,
>
>      doc: improve description of join's -a option
>
> so that a naive categorization lists it as a documentation change
> rather than a join bug fix

I did that and pushed.

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

Previous Next

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