--- Begin Message ---
Subject: |
join: suggestion for manpage/help enhacement |
Date: |
Tue, 13 Sep 2011 23:55:40 +0200 |
User-agent: |
Mutt/1.5.20 (2009-06-14) |
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
--- End Message ---
--- Begin Message ---
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 <address@hidden>
> 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
--- End Message ---