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

Previous Next

Full log

View this message in rfc822 format

From: help-debbugs <at> gnu.org (GNU bug Tracking System)
To: Tomas Volka <tomas.volka <at> unicorn.eu>
Subject: bug#9497: closed (Re: bug#9497: join: suggestion for manpage/help
 enhacement)
Date: Wed, 14 Sep 2011 07:30:03 +0000

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

Your bug report

#9497: join: suggestion for manpage/help enhacement

which was filed against the coreutils package, has been closed.

The explanation is attached below, along with your original report.
If you require more details, please reply to 9497 <at> debbugs.gnu.org.

-- 
9497: http://debbugs.gnu.org/cgi/bugreport.cgi?bug=9497
GNU Bug Tracking System
Contact help-debbugs <at> gnu.org with problems

[Message part 2 (message/rfc822, inline)]

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 part 3 (message/rfc822, inline)]

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

Previous Next

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