From unknown Tue Aug 19 07:28:44 2025 Content-Disposition: inline Content-Transfer-Encoding: quoted-printable MIME-Version: 1.0 X-Mailer: MIME-tools 5.509 (Entity 5.509) Content-Type: text/plain; charset=utf-8 From: bug#9497 <9497@debbugs.gnu.org> To: bug#9497 <9497@debbugs.gnu.org> Subject: Status: join: suggestion for manpage/help enhacement Reply-To: bug#9497 <9497@debbugs.gnu.org> Date: Tue, 19 Aug 2025 14:28:44 +0000 retitle 9497 join: suggestion for manpage/help enhacement reassign 9497 coreutils submitter 9497 Tomas Volka severity 9497 normal thanks From debbugs-submit-bounces@debbugs.gnu.org Tue Sep 13 18:01:40 2011 Received: (at submit) by debbugs.gnu.org; 13 Sep 2011 22:01:40 +0000 Received: from localhost ([127.0.0.1] helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.69) (envelope-from ) id 1R3b2x-0003S9-Kw for submit@debbugs.gnu.org; Tue, 13 Sep 2011 18:01:40 -0400 Received: from eggs.gnu.org ([140.186.70.92]) by debbugs.gnu.org with esmtp (Exim 4.69) (envelope-from ) id 1R3b1s-0003AL-0A for submit@debbugs.gnu.org; Tue, 13 Sep 2011 18:00:33 -0400 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1R3axW-0000YU-0O for submit@debbugs.gnu.org; Tue, 13 Sep 2011 17:56:02 -0400 X-Spam-Checker-Version: SpamAssassin 3.3.1 (2010-03-16) on eggs.gnu.org X-Spam-Level: X-Spam-Status: No, score=-1.9 required=5.0 tests=BAYES_00 autolearn=unavailable version=3.3.1 Received: from lists.gnu.org ([140.186.70.17]:41583) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1R3axV-0000YQ-TX for submit@debbugs.gnu.org; Tue, 13 Sep 2011 17:56:01 -0400 Received: from eggs.gnu.org ([140.186.70.92]:47368) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1R3axU-0002TO-TW for bug-coreutils@gnu.org; Tue, 13 Sep 2011 17:56:01 -0400 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1R3axT-0000Y1-W1 for bug-coreutils@gnu.org; Tue, 13 Sep 2011 17:56:00 -0400 Received: from mxgw2.unicornuniverse.eu ([77.93.211.164]:49939) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1R3axT-0000XT-PR for bug-coreutils@gnu.org; Tue, 13 Sep 2011 17:55:59 -0400 Received: from smtp.unicornuniverse.eu (smtp.unicornuniverse.eu [77.93.211.162]) by mxgw2.unicornuniverse.eu (Postfix) with ESMTP id 768F89C00E for ; Tue, 13 Sep 2011 23:55:42 +0200 (CEST) Date: Tue, 13 Sep 2011 23:55:40 +0200 From: Tomas Volka To: bug-coreutils@gnu.org Subject: join: suggestion for manpage/help enhacement Message-ID: <20110913215540.GB2437@debian.pilsfree.czf> MIME-Version: 1.0 Content-Type: text/plain; charset=us-ascii Content-Disposition: inline User-Agent: Mutt/1.5.20 (2009-06-14) X-UNICORNUNIVERSE-MailScanner-Information: Please contact the ISP for more information X-UNICORNUNIVERSE-MailScanner-ID: 768F89C00E.A3C79 X-UNICORNUNIVERSE-MailScanner: Found to be clean X-UNICORNUNIVERSE-MailScanner-From: tomas.volka@unicorn.eu X-detected-operating-system: by eggs.gnu.org: GNU/Linux 2.6 (newer, 3) X-detected-operating-system: by eggs.gnu.org: GNU/Linux 2.6 (newer, 3) X-Received-From: 140.186.70.17 X-Spam-Score: -6.6 (------) X-Debbugs-Envelope-To: submit X-Mailman-Approved-At: Tue, 13 Sep 2011 18:01:38 -0400 X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.11 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Sender: debbugs-submit-bounces@debbugs.gnu.org Errors-To: debbugs-submit-bounces@debbugs.gnu.org X-Spam-Score: -6.6 (------) 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 From debbugs-submit-bounces@debbugs.gnu.org Tue Sep 13 18:12:56 2011 Received: (at 9497) by debbugs.gnu.org; 13 Sep 2011 22:12:57 +0000 Received: from localhost ([127.0.0.1] helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.69) (envelope-from ) id 1R3bDp-0003hZ-5w for submit@debbugs.gnu.org; Tue, 13 Sep 2011 18:12:56 -0400 Received: from mx1.redhat.com ([209.132.183.28]) by debbugs.gnu.org with esmtp (Exim 4.69) (envelope-from ) id 1R3bDj-0003hO-7K for 9497@debbugs.gnu.org; Tue, 13 Sep 2011 18:12:51 -0400 Received: from int-mx09.intmail.prod.int.phx2.redhat.com (int-mx09.intmail.prod.int.phx2.redhat.com [10.5.11.22]) by mx1.redhat.com (8.14.4/8.14.4) with ESMTP id p8DM8HBL001842 (version=TLSv1/SSLv3 cipher=DHE-RSA-AES256-SHA bits=256 verify=OK); Tue, 13 Sep 2011 18:08:17 -0400 Received: from [10.3.113.73] (ovpn-113-73.phx2.redhat.com [10.3.113.73]) by int-mx09.intmail.prod.int.phx2.redhat.com (8.14.4/8.14.4) with ESMTP id p8DM8GNw025092; Tue, 13 Sep 2011 18:08:16 -0400 Message-ID: <4E6FD450.80400@redhat.com> Date: Tue, 13 Sep 2011 16:08:16 -0600 From: Eric Blake Organization: Red Hat 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 MIME-Version: 1.0 To: Tomas Volka Subject: Re: bug#9497: join: suggestion for manpage/help enhacement References: <20110913215540.GB2437@debian.pilsfree.czf> In-Reply-To: <20110913215540.GB2437@debian.pilsfree.czf> Content-Type: text/plain; charset=ISO-8859-1; format=flowed Content-Transfer-Encoding: 7bit X-Scanned-By: MIMEDefang 2.68 on 10.5.11.22 X-Spam-Score: -10.3 (----------) X-Debbugs-Envelope-To: 9497 Cc: 9497@debbugs.gnu.org X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.11 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Sender: debbugs-submit-bounces@debbugs.gnu.org Errors-To: debbugs-submit-bounces@debbugs.gnu.org X-Spam-Score: -10.3 (----------) 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 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 eblake@redhat.com +1-801-349-2682 Libvirt virtualization library http://libvirt.org From debbugs-submit-bounces@debbugs.gnu.org Tue Sep 13 18:53:17 2011 Received: (at 9497) by debbugs.gnu.org; 13 Sep 2011 22:53:17 +0000 Received: from localhost ([127.0.0.1] helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.69) (envelope-from ) id 1R3bqu-0006yz-SB for submit@debbugs.gnu.org; Tue, 13 Sep 2011 18:53:17 -0400 Received: from mxgw2.unicornuniverse.eu ([77.93.211.164]) by debbugs.gnu.org with esmtp (Exim 4.69) (envelope-from ) id 1R3bqn-0006yl-J1 for 9497@debbugs.gnu.org; Tue, 13 Sep 2011 18:53:11 -0400 Received: from smtp.unicornuniverse.eu (smtp.unicornuniverse.eu [77.93.211.162]) by mxgw2.unicornuniverse.eu (Postfix) with ESMTP id 12C6A9C00E; Wed, 14 Sep 2011 00:48:25 +0200 (CEST) Date: Wed, 14 Sep 2011 00:48:23 +0200 From: Tomas Volka To: Eric Blake Subject: Re: bug#9497: join: suggestion for manpage/help enhacement Message-ID: <20110913224823.GC2437@debian.pilsfree.czf> References: <20110913215540.GB2437@debian.pilsfree.czf> <4E6FD450.80400@redhat.com> MIME-Version: 1.0 Content-Type: text/plain; charset=iso-8859-1 Content-Disposition: inline In-Reply-To: <4E6FD450.80400@redhat.com> User-Agent: Mutt/1.5.20 (2009-06-14) X-UNICORNUNIVERSE-MailScanner-Information: Please contact the ISP for more information X-UNICORNUNIVERSE-MailScanner-ID: 12C6A9C00E.AA4E5 X-UNICORNUNIVERSE-MailScanner: Found to be clean X-UNICORNUNIVERSE-MailScanner-From: tomas.volka@unicorn.eu X-Spam-Status: No Content-Transfer-Encoding: quoted-printable X-Spam-Score: -4.6 (----) X-Debbugs-Envelope-To: 9497 Cc: 9497@debbugs.gnu.org X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.11 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Sender: debbugs-submit-bounces@debbugs.gnu.org Errors-To: debbugs-submit-bounces@debbugs.gnu.org X-Spam-Score: -3.9 (---) On =DAt 13-09-11 | 16:08, Eric Blake wrote: > If you read both -a and -v, then you realize that -a does more output=20 > than -v. But I agree that this is confusing, and that we can do better= . I agree. Most users will stop reading the manpage when they reach -a and will expect -v like behavior ( because they didn't reached the -v yet ).=20 > How about the following patch, which adds "also", while maintaining > line length by deleting the fluff word "coming"? >=20 > From 31046b6d38ab49cb815c8f6c6bc4faf6bb596de6 Mon Sep 17 00:00:00 2001 > From: Eric Blake > Date: Tue, 13 Sep 2011 16:07:11 -0600 > Subject: [PATCH] join: clarify -a behavior >=20 > * 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(-) >=20 > 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, whe= re\n\ > FILENUM is 1 or 2, corresponding to FILE1 or > FILE2\n\ > -e EMPTY replace missing input fields with EMPTY\n\ > "), stdout); Yes, i think that the patch above is completely sufficient. Tom From debbugs-submit-bounces@debbugs.gnu.org Wed Sep 14 03:29:49 2011 Received: (at 9497-done) by debbugs.gnu.org; 14 Sep 2011 07:29:49 +0000 Received: from localhost ([127.0.0.1] helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.69) (envelope-from ) id 1R3jum-000397-IS for submit@debbugs.gnu.org; Wed, 14 Sep 2011 03:29:48 -0400 Received: from mx1.redhat.com ([209.132.183.28]) by debbugs.gnu.org with esmtp (Exim 4.69) (envelope-from ) id 1R3juj-00038y-2p for 9497-done@debbugs.gnu.org; Wed, 14 Sep 2011 03:29:46 -0400 Received: from int-mx09.intmail.prod.int.phx2.redhat.com (int-mx09.intmail.prod.int.phx2.redhat.com [10.5.11.22]) by mx1.redhat.com (8.14.4/8.14.4) with ESMTP id p8E7PDkp019741 (version=TLSv1/SSLv3 cipher=DHE-RSA-AES256-SHA bits=256 verify=OK); Wed, 14 Sep 2011 03:25:13 -0400 Received: from mx.meyering.net (ovpn01.gateway.prod.ext.phx2.redhat.com [10.5.9.1]) by int-mx09.intmail.prod.int.phx2.redhat.com (8.14.4/8.14.4) with ESMTP id p8E7PB1I002812; Wed, 14 Sep 2011 03:25:12 -0400 Received: from rho.meyering.net (localhost.localdomain [127.0.0.1]) by rho.meyering.net (Acme Bit-Twister) with ESMTP id 4B2E660019; Wed, 14 Sep 2011 09:25:11 +0200 (CEST) From: Jim Meyering To: Eric Blake Subject: Re: bug#9497: join: suggestion for manpage/help enhacement In-Reply-To: <4E6FD450.80400@redhat.com> (Eric Blake's message of "Tue, 13 Sep 2011 16:08:16 -0600") References: <20110913215540.GB2437@debian.pilsfree.czf> <4E6FD450.80400@redhat.com> Date: Wed, 14 Sep 2011 09:25:11 +0200 Message-ID: <87y5xry4a0.fsf@rho.meyering.net> Lines: 42 MIME-Version: 1.0 Content-Type: text/plain X-Scanned-By: MIMEDefang 2.68 on 10.5.11.22 X-Spam-Score: -10.5 (----------) X-Debbugs-Envelope-To: 9497-done Cc: Tomas Volka , 9497-done@debbugs.gnu.org X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.11 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Sender: debbugs-submit-bounces@debbugs.gnu.org Errors-To: debbugs-submit-bounces@debbugs.gnu.org X-Spam-Score: -10.5 (----------) 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 > 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 From debbugs-submit-bounces@debbugs.gnu.org Wed Sep 14 09:54:44 2011 Received: (at 9497-done) by debbugs.gnu.org; 14 Sep 2011 13:54:44 +0000 Received: from localhost ([127.0.0.1] helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.69) (envelope-from ) id 1R3pvD-0007PG-IY for submit@debbugs.gnu.org; Wed, 14 Sep 2011 09:54:44 -0400 Received: from mx1.redhat.com ([209.132.183.28]) by debbugs.gnu.org with esmtp (Exim 4.69) (envelope-from ) id 1R3pv7-0007P5-2z for 9497-done@debbugs.gnu.org; Wed, 14 Sep 2011 09:54:37 -0400 Received: from int-mx09.intmail.prod.int.phx2.redhat.com (int-mx09.intmail.prod.int.phx2.redhat.com [10.5.11.22]) by mx1.redhat.com (8.14.4/8.14.4) with ESMTP id p8EDnxMH012789 (version=TLSv1/SSLv3 cipher=DHE-RSA-AES256-SHA bits=256 verify=OK); Wed, 14 Sep 2011 09:49:59 -0400 Received: from [10.3.113.73] (ovpn-113-73.phx2.redhat.com [10.3.113.73]) by int-mx09.intmail.prod.int.phx2.redhat.com (8.14.4/8.14.4) with ESMTP id p8EDnwU4003756; Wed, 14 Sep 2011 09:49:58 -0400 Message-ID: <4E70B106.2030309@redhat.com> Date: Wed, 14 Sep 2011 07:49:58 -0600 From: Eric Blake Organization: Red Hat 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 MIME-Version: 1.0 To: Jim Meyering Subject: Re: bug#9497: join: suggestion for manpage/help enhacement References: <20110913215540.GB2437@debian.pilsfree.czf> <4E6FD450.80400@redhat.com> <87y5xry4a0.fsf@rho.meyering.net> In-Reply-To: <87y5xry4a0.fsf@rho.meyering.net> Content-Type: text/plain; charset=UTF-8; format=flowed Content-Transfer-Encoding: 7bit X-Scanned-By: MIMEDefang 2.68 on 10.5.11.22 X-Spam-Score: -10.3 (----------) X-Debbugs-Envelope-To: 9497-done Cc: Tomas Volka , 9497-done@debbugs.gnu.org X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.11 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Sender: debbugs-submit-bounces@debbugs.gnu.org Errors-To: debbugs-submit-bounces@debbugs.gnu.org X-Spam-Score: -10.3 (----------) On 09/14/2011 01:25 AM, Jim Meyering wrote: > 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 did that and pushed. -- Eric Blake eblake@redhat.com +1-801-349-2682 Libvirt virtualization library http://libvirt.org From unknown Tue Aug 19 07:28:44 2025 Received: (at fakecontrol) by fakecontrolmessage; To: internal_control@debbugs.gnu.org From: Debbugs Internal Request Subject: Internal Control Message-Id: bug archived. Date: Thu, 13 Oct 2011 11:24:05 +0000 User-Agent: Fakemail v42.6.9 # This is a fake control message. # # The action: # bug archived. thanks # This fakemail brought to you by your local debbugs # administrator