doc: promote 'sort --debug'

* README, doc/coreutils.texi (Introduction, sort invocation):
Suggest 'sort --debug' more prominently.

2 files changed, 61 insertions, 45 deletions

diff --git a/README b/README
index f50b6dfc4..183d4f832 100644
--- a/README
+++ b/README
@@ -59,9 +59,9 @@ files (man/*.x) are welcome.  However, the authoritative documentation
 is in texinfo form in the doc directory.
 
 
-*****************************************
+*********************************************
 On Mac OS X 10.5.1 (Darwin 9.1), test failure
------------------------------------------
+---------------------------------------------
 
 Mac OS X 10.5.1 (Darwin 9.1) provides only partial (and incompatible)
 ACL support, so although "./configure && make" succeeds, "make check"
@@ -82,9 +82,9 @@ the mean time, you can configure with --disable-nls.  For details,
 see <http://thread.gmane.org/gmane.comp.lib.gnulib.bugs/12015/>.
 
 
-***********************
+*********************
 Pre-C99 build failure
------------------------
+---------------------
 
 In 2009 we added this requirement:
 To build the coreutils from source, you must have a C99-conforming
@@ -165,6 +165,15 @@ root than when run by less privileged users.
 Reporting bugs:
 ---------------
 
+Send bug reports, questions, comments, etc. to bug-coreutils@gnu.org.
+To suggest a patch, see the files README-hacking and HACKING for tips.
+
+If you have a problem with 'sort', try running 'sort --debug', as it
+can can often help find and fix problems without having to wait for an
+answer to a bug report.  If the debug output does not suffice to fix
+the problem on your own, please compress and attach it to the rest of
+your bug report.
+
 IMPORTANT: if you take the time to report a test failure,
 please be sure to include the output of running 'make check'
 in verbose mode for each failing test.  For example,
@@ -176,9 +185,6 @@ run this command:
 For some tests, you can get even more detail by adding DEBUG=yes.
 Then include the contents of the file 'log' in your bug report.
 
-Send bug reports, questions, comments, etc. to bug-coreutils@gnu.org.
-If you would like to suggest a patch, see the files README-hacking
-and HACKING for tips.
 
 ***************************************
 
diff --git a/doc/coreutils.texi b/doc/coreutils.texi
index 595cb9fe2..64b6206d7 100644
--- a/doc/coreutils.texi
+++ b/doc/coreutils.texi
@@ -516,10 +516,19 @@ will benefit.
 The GNU utilities documented here are mostly compatible with the
 POSIX standard.
 @cindex bugs, reporting
-Please report bugs to @email{bug-coreutils@@gnu.org}.  Remember
-to include the version number, machine architecture, input files, and
+
+Please report bugs to @email{bug-coreutils@@gnu.org}.
+Include the version number, machine architecture, input files, and
 any other information needed to reproduce the bug: your input, what you
-expected, what you got, and why it is wrong.  Diffs are welcome, but
+expected, what you got, and why it is wrong.
+
+If you have a problem with @command{sort}, try running @samp{sort
+--debug}, as it can can often help find and fix problems without
+having to wait for an answer to a bug report.  If the debug output
+does not suffice to fix the problem on your own, please compress and
+attach it to the rest of your bug report.
+
+Although diffs are welcome,
 please include a description of the problem as well, since this is
 sometimes difficult to infer.  @xref{Bugs, , , gcc, Using and Porting GNU CC}.
 
@@ -4001,6 +4010,42 @@ output.  Synopsis:
 sort [@var{option}]@dots{} [@var{file}]@dots{}
 @end example
 
+@cindex sort stability
+@cindex sort's last-resort comparison
+Many options affect how @command{sort} compares lines; if the results
+are unexpected, try the @option{--debug} option to see what happened.
+A pair of lines is compared as follows:
+@command{sort} compares each pair of fields, in the
+order specified on the command line, according to the associated
+ordering options, until a difference is found or no fields are left.
+If no key fields are specified, @command{sort} uses a default key of
+the entire line.  Finally, as a last resort when all keys compare
+equal, @command{sort} compares entire lines as if no ordering options
+other than @option{--reverse} (@option{-r}) were specified.  The
+@option{--stable} (@option{-s}) option disables this @dfn{last-resort
+comparison} so that lines in which all fields compare equal are left
+in their original relative order.  The @option{--unique}
+(@option{-u}) option also disables the last-resort comparison.
+@vindex LC_ALL
+@vindex LC_COLLATE
+
+Unless otherwise specified, all comparisons use the character collating
+sequence specified by the @env{LC_COLLATE} locale.@footnote{If you
+use a non-POSIX locale (e.g., by setting @env{LC_ALL}
+to @samp{en_US}), then @command{sort} may produce output that is sorted
+differently than you're accustomed to.  In that case, set the @env{LC_ALL}
+environment variable to @samp{C}@.  Note that setting only @env{LC_COLLATE}
+has two problems.  First, it is ineffective if @env{LC_ALL} is also set.
+Second, it has undefined behavior if @env{LC_CTYPE} (or @env{LANG}, if
+@env{LC_CTYPE} is unset) is set to an incompatible value.  For example,
+you get undefined behavior if @env{LC_CTYPE} is @code{ja_JP.PCK} but
+@env{LC_COLLATE} is @code{en_US.UTF-8}.}
+A line's trailing newline is not part of the line for comparison
+purposes.  If the final byte of an input file is not a newline, GNU
+@command{sort} silently supplies one.  GNU @command{sort} (as
+specified for all GNU utilities) has no limit on input line length or
+restrictions on bytes allowed within lines.
+
 @command{sort} has three modes of operation: sort (the default), merge,
 and check for sortedness.  The following options change the operation
 mode:
@@ -4042,41 +4087,6 @@ works.
 
 @end table
 
-@cindex sort stability
-@cindex sort's last-resort comparison
-A pair of lines is compared as follows:
-@command{sort} compares each pair of fields, in the
-order specified on the command line, according to the associated
-ordering options, until a difference is found or no fields are left.
-If no key fields are specified, @command{sort} uses a default key of
-the entire line.  Finally, as a last resort when all keys compare
-equal, @command{sort} compares entire lines as if no ordering options
-other than @option{--reverse} (@option{-r}) were specified.  The
-@option{--stable} (@option{-s}) option disables this @dfn{last-resort
-comparison} so that lines in which all fields compare equal are left
-in their original relative order.  The @option{--unique}
-(@option{-u}) option also disables the last-resort comparison.
-
-@vindex LC_ALL
-@vindex LC_COLLATE
-Unless otherwise specified, all comparisons use the character collating
-sequence specified by the @env{LC_COLLATE} locale.@footnote{If you
-use a non-POSIX locale (e.g., by setting @env{LC_ALL}
-to @samp{en_US}), then @command{sort} may produce output that is sorted
-differently than you're accustomed to.  In that case, set the @env{LC_ALL}
-environment variable to @samp{C}@.  Note that setting only @env{LC_COLLATE}
-has two problems.  First, it is ineffective if @env{LC_ALL} is also set.
-Second, it has undefined behavior if @env{LC_CTYPE} (or @env{LANG}, if
-@env{LC_CTYPE} is unset) is set to an incompatible value.  For example,
-you get undefined behavior if @env{LC_CTYPE} is @code{ja_JP.PCK} but
-@env{LC_COLLATE} is @code{en_US.UTF-8}.}
-
-GNU @command{sort} (as specified for all GNU utilities) has no
-limit on input line length or restrictions on bytes allowed within lines.
-In addition, if the final byte of an input file is not a newline, GNU
-@command{sort} silently supplies one.  A line's trailing newline is not
-part of the line for comparison purposes.
-
 @cindex exit status of @command{sort}
 Exit status: