doc: clarify the operation of the comm -123 parameters

* src/comm.c (usage): give more information on the -123 parameters,
with examples to show that they can be combined.
Addresses <http://savannah.gnu.org/bugs/?24974>.
* doc/coreutils.texi (comm invocation): Mention that the
column separators are suppressed along with the column.
Suggestion from Dan Jacobson.
* man/comm.x: Reference other commands that match adjacent lines.
* man/join.x: ditto.
* man/uniq.x: ditto.

diff --git a/doc/coreutils.texi b/doc/coreutils.texi
index b96fdb20291856db1d530aead257195cf8c58492..1a3075ffec8aba8828edf7aa606d933f79712312 100644 (file)
--- a/doc/coreutils.texi
+++ b/doc/coreutils.texi
@@ -4565,7 +4565,7 @@ Columns are separated by a single TAB character.
 @opindex -2
 @opindex -3
 The options @option{-1}, @option{-2}, and @option{-3} suppress printing of
-the corresponding columns.  Also see @ref{Common options}.
+the corresponding columns (and separators).  Also see @ref{Common options}.
 
 Unlike some other comparison utilities, @command{comm} has an exit
 status that does not depend on the result of the comparison.

diff --git a/man/comm.x b/man/comm.x
index dfc84806e89af7bdc5a94a53c31a974253fdc6ec..d4d8e00dade60a6a1cbebed1f6f5208ed4db54b4 100644 (file)
--- a/man/comm.x
+++ b/man/comm.x
@@ -2,3 +2,5 @@
 comm \- compare two sorted files line by line
 [DESCRIPTION]
 .\" Add any additional description here
+[SEE ALSO]
+join(1), uniq(1)

diff --git a/man/join.x b/man/join.x
index 6f50791f26aeda591de475140f3dbf1ae80acc2b..f83e8ceca5f0eb57b3e33f1032958bb266da9f0b 100644 (file)
--- a/man/join.x
+++ b/man/join.x
@@ -2,3 +2,5 @@
 join \- join lines of two files on a common field
 [DESCRIPTION]
 .\" Add any additional description here
+[SEE ALSO]
+comm(1), uniq(1)

diff --git a/man/uniq.x b/man/uniq.x
index 0221d92ab492e13e458d09c942180647d632c5ad..98a95f996fa0ea1fc020ad771172fedb3a9a68f1 100644 (file)
--- a/man/uniq.x
+++ b/man/uniq.x
@@ -2,3 +2,5 @@
 uniq \- report or omit repeated lines
 [DESCRIPTION]
 .\" Add any additional description here
+[SEE ALSO]
+comm(1), join(1)

diff --git a/src/comm.c b/src/comm.c
index 3c5b09ad4d9f48ad0b06b9e9baf1f0ed6873d837..e37cf887570afb8b159721fb9bf4678e154e125f 100644 (file)
--- a/src/comm.c
+++ b/src/comm.c
@@ -114,9 +114,9 @@ and column three contains lines common to both files.\n\
 "), stdout);
       fputs (_("\
 \n\
-  -1              suppress lines unique to FILE1\n\
-  -2              suppress lines unique to FILE2\n\
-  -3              suppress lines that appear in both files\n\
+  -1              suppress column 1 (lines unique to FILE1)\n\
+  -2              suppress column 2 (lines unique to FILE2)\n\
+  -3              suppress column 3 (lines that appear in both files)\n\
 "), stdout);
       fputs (_("\
 \n\
@@ -133,6 +133,13 @@ and column three contains lines common to both files.\n\
 \n\
 Note, comparisons honor the rules specified by `LC_COLLATE'.\n\
 "), stdout);
+      printf (_("\
+\n\
+Examples:\n\
+  %s -12 file1 file2  Print only lines present in both file1 and file2.\n\
+  %s -3  file1 file2  Print lines in file1 not in file2, and vice versa.\n\
+"),
+             program_name, program_name);
       emit_bug_reporting_address ();
     }
   exit (status);