bug#9497: join: suggestion for manpage/help enhacement

[Eric Blake]

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 <address@hidden>
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   address@hidden    +1-801-349-2682
Libvirt virtualization library http://libvirt.org