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 protected]> 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
