[Top][All Lists]
[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
bug#9497: join: suggestion for manpage/help enhacement
From: |
Eric Blake |
Subject: |
bug#9497: join: suggestion for manpage/help enhacement |
Date: |
Tue, 13 Sep 2011 16:08:16 -0600 |
User-agent: |
Mozilla/5.0 (X11; U; Linux x86_64; en-US; rv:1.9.2.20) Gecko/20110831 Fedora/3.1.12-2.fc14 Lightning/1.0b3pre Mnenhy/0.8.3 Thunderbird/3.1.12 |
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