doc: clarify descriptions for tr --squeeze-repeats

* doc/coreutils.texi (uniq invocation): Fix the description of
problematic input to say "blank lines" rather than "two or more
blank lines".
(tr invocation): Clarify that -s only works with SET1 when
not translating (when SET2 not specified).  Also explicitly
state in examples where blank lines are deleted.
Also add "deleting" to the menu item.
* src/tr.c (usage): Improve the -s summary to say it always
operates on the last specified SET.

2 files changed, 22 insertions, 19 deletions

diff --git a/doc/coreutils.texi b/doc/coreutils.texi
index 88e16503d..9a27cb109 100644
--- a/doc/coreutils.texi
+++ b/doc/coreutils.texi
@@ -297,7 +297,7 @@ Operating on characters
 
 * Character sets::               Specifying sets of characters
 * Translating::                  Changing one set of characters to another
-* Squeezing::                    Squeezing repeats and deleting
+* Squeezing and deleting::       Removing characters
 
 Directory listing
 
@@ -1609,7 +1609,8 @@ if @option{-b} is in effect.
 @opindex -s
 @opindex --squeeze-blank
 @cindex squeezing empty lines
-Suppress repeated adjacent empty lines; output just one empty line
+@cindex squeezing blank lines
+Suppress repeated adjacent blank lines; output just one empty line
 instead of several.
 
 @item -t
@@ -4968,9 +4969,9 @@ may be better suited for output direct to users.
 
 @macro ambiguousGroupNote
 Note that when groups are delimited and the input stream contains
-two or more consecutive blank lines, then the output is ambiguous.
-To avoid that, filter the input through @samp{tr -s '\\n'} to replace
-each sequence of consecutive newlines with a single newline.
+blank lines, then the output is ambiguous.
+To avoid that, filter the input through @samp{tr -s '\\n'} to
+remove blank lines.
 @end macro
 @ambiguousGroupNote
 
@@ -6215,7 +6216,7 @@ options.  @xref{Common options}.  Options must precede operands.
 @menu
 * Character sets::              Specifying sets of characters.
 * Translating::                 Changing one set of characters to another.
-* Squeezing::                   Squeezing repeats and deleting.
+* Squeezing and deleting::      Removing characters.
 @end menu
 
 
@@ -6438,18 +6439,20 @@ tr -cs '[:alnum:]' '[\n*]'
 @end example
 
 
-@node Squeezing
+@node Squeezing and deleting
 @subsection Squeezing repeats and deleting
 
 @cindex squeezing repeat characters
 @cindex deleting characters
+@cindex removing characters
 
 When given just the @option{--delete} (@option{-d}) option, @command{tr}
 removes any input characters that are in @var{set1}.
 
-When given just the @option{--squeeze-repeats} (@option{-s}) option,
-@command{tr} replaces each input sequence of a repeated character that
-is in @var{set1} with a single occurrence of that character.
+When given just the @option{--squeeze-repeats} (@option{-s}) option
+and not translating, @command{tr} replaces each input sequence of a
+repeated character that is in @var{set1} with a single occurrence of
+that character.
 
 When given both @option{--delete} and @option{--squeeze-repeats}, @command{tr}
 first performs any deletions using @var{set1}, then squeezes repeats
@@ -6480,7 +6483,8 @@ tr -cs '[:alnum:]' '[\n*]'
 @end example
 
 @item
-Convert each sequence of repeated newlines to a single newline:
+Convert each sequence of repeated newlines to a single newline.
+I.e., delete blank lines:
 
 @example
 tr -s '\n'
@@ -17831,8 +17835,8 @@ $ tr '[:upper:]' '[:lower:]' < whats.gnu | tr -cd '[:alnum:]_ \n' |
 @end smallexample
 
 This command turns blanks into newlines.  The @option{-s} option squeezes
-multiple newline characters in the output into just one.  This helps us
-avoid blank lines.  (The @samp{>} is the shell's ``secondary prompt.''
+multiple newline characters in the output into just one, removing
+blank lines.  (The @samp{>} is the shell's ``secondary prompt.''
 This is what the shell prints when it notices you haven't finished
 typing in all of a command.)
 
diff --git a/src/tr.c b/src/tr.c
index fe6f466bd..a1310a863 100644
--- a/src/tr.c
+++ b/src/tr.c
@@ -293,9 +293,9 @@ writing to standard output.\n\
 \n\
   -c, -C, --complement    use the complement of SET1\n\
   -d, --delete            delete characters in SET1, do not translate\n\
-  -s, --squeeze-repeats   replace each input sequence of a repeated character\n\
-                            that is listed in SET1 with a single occurrence\n\
-                            of that character\n\
+  -s, --squeeze-repeats   replace each sequence of a repeated character\n\
+                            that is listed in the last specified SET,\n\
+                            with a single occurrence of that character\n\
   -t, --truncate-set1     first truncate SET1 to length of SET2\n\
 "), stdout);
       fputs (HELP_OPTION_DESCRIPTION, stdout);
@@ -342,9 +342,8 @@ Translation occurs if -d is not given and both SET1 and SET2 appear.\n\
 SET1 by repeating its last character as necessary.  Excess characters\n\
 of SET2 are ignored.  Only [:lower:] and [:upper:] are guaranteed to\n\
 expand in ascending order; used in SET2 while translating, they may\n\
-only be used in pairs to specify case conversion.  -s uses SET1 if not\n\
-translating nor deleting; else squeezing uses SET2 and occurs after\n\
-translation or deletion.\n\
+only be used in pairs to specify case conversion.  -s uses the last\n\
+specified SET, and occurs after translation or deletion.\n\
 "), stdout);
       emit_ancillary_info (PROGRAM_NAME);
     }