Subject: Re: bug#26029: Problems with join

From: Assaf Gordon <[email-masked]>
Date: Fri, 31 Mar 2017 03:54:19 +0000

Hello,

Attached a small patch mentioning the obsolete '-j1 N' syntax.

Becuse it is rather rare, I only added it to the texinfo
manual, not to the man-page (or --help screen).

I'm 50:50 about whether this justifies an entire section in the manual,
or perhaps it'll be enough to mention it in the 'gotcha' page.

Comments welcomed,
 - assaf

>From d0d51f85cc6f1ce1a330bd45b4072778b74b0cc9 Mon Sep 17 00:00:00 2001
From: Assaf Gordon <[email-masked]>
Date: Thu, 30 Mar 2017 22:58:46 -0400
Subject: [PATCH] doc: mention obsolete join -j1/-j2 syntax

'-j1 N' is equivalent to '-1 N', not to '-1 N -2 N' to comply
with older POSIX requirements. Mention and warn about this obsolete
syntax. Discussed in https://bugs.gnu.org/26029 .

* doc/coreutils.texi (join): New subsection.
---
 doc/coreutils.texi | 55 ++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 55 insertions(+)

diff --git a/doc/coreutils.texi b/doc/coreutils.texi
index b8e24aa..3db359c 100644
--- a/doc/coreutils.texi
+++ b/doc/coreutils.texi
@@ -6155,6 +6155,7 @@ fields from @var{file1}, then the remaining fields from @var{file2}.
 * Paired and unpaired lines::    Controlling @command{join}'s field matching.
 * Header lines::                 Working with header lines in files.
 * Set operations::               Union, Intersection and Difference of files.
+* Obsolete join syntax::         Obsolete @option{-j1/2} syntax.
 @end menu
 
 @node General options in join
@@ -6622,6 +6623,60 @@ All examples above operate on entire lines and not on specific fields:
 @command{sort} without @option{-k} and @command{join -t''} both consider
 entire lines as the key.
 
+@node Obsolete join syntax
+@subsection Obsolete @option{-j1/2} syntax
+
+The options @option{-j1} and @option{-j2} when @emph{followed by a number}
+are treated in a special way: instead of setting the key field for both
+files, they set the key field for the respective file alone.
+
+That is: @samp{-j1 3} is equivalent to @samp{-1 3}, @emph{not} to
+@samp{-1 3 -2 3}.
+
+When not followed by a number, @option{-j1} and @option{-j2} behave
+as expected (that is: set the key field for both files: @samp{-j2}
+is equivalent to @samp{-1 2 -2 2}).
+
+This usage is discouraged, and was implemented comply with older
+POSIX specifications.
+
+@exdent Using the following two input files:
+@example
+@group
+$ cat a.txt
+1 2 A
+2 3 B
+
+$ cat b.txt
+1 2 X
+2 3 Y
+@end group
+@end example
+
+@exdent Using @samp{-jN} is equivalent to @samp{-1 N -2 N}:
+
+@example
+@group
+$ join -j1 a.txt b.txt
+1 2 A 2 X
+2 3 B 3 Y
+
+$ join -1 1 -2 1 a.txt b.txt
+1 2 A 2 X
+2 3 B 3 Y
+@end group
+@end example
+
+@exdent Except when followed by a number:
+@example
+@group
+$ join -j1 2 a.txt b.txt
+2 1 A 3 Y
+
+$ join -1 2 a.txt b.txt
+2 1 A 3 Y
+@end group
+@end example
 
 @node Operating on characters
 @chapter Operating on characters
-- 
1.9.0