Subject: join: suggestion for manpage/help enhacement
From: Tomas Volka <[email-masked]>
To: [email-masked]
Date: Tue, 13 Sep 2011 23:55:40 +0200
List-Id: <debbugs-submit.debbugs.gnu.org>

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