Subject: Re: bug#23665: spaces in keys: doc, --debug in LC_ALL=C

From: Pádraig Brady <[email-masked]>
Date: Wed, 1 Jun 2016 12:05:07 +0100

On 01/06/16 03:15, Assaf Gordon wrote:
>
>> On May 31, 2016, at 20:54, Pádraig Brady <[email-masked]> wrote:
>>
>> On 01/06/16 01:38, Assaf Gordon wrote:
>>>
>>> 2. add a bit more verbose progress information to the 'sort-debug-warn.sh' test - just so it'll be easier to discuss to the changed messages.
>>>
>>> 3. removes the 'maybe_space_aligned' and modifies the condition a bit.
>>
>> 2 and 3 are good to push.
>
> Thank you, pushed in:
>   http://git.savannah.gnu.org/cgit/coreutils.git/commit/?id=d548f87595a193e21b170368bc8fc2ded4dadb73
>   http://git.savannah.gnu.org/cgit/coreutils.git/commit/?id=6223bf94bfeac75fb4252095864a80545ba00a0d
>
> ====
>
> Regarding documentation: how about the following?
>
> 'sort' without '-t' separates fields by whitespace (tab and space characters) and considers the whitespace characters to be part of the field's text. Use 'b' sorting option to skip leading spaces.
>

I've added essentially that summary to the --key description in the attached.

> Example:

I think these examples are a bit verbose for the info docs
for the amount of info they convey. There are so many combinations
of field handling options that it's best to give the rules
and defer to the --debug option for what's actually happening.

What I have done is to expand this discussion on field handling in:
http://www.pixelbeat.org/docs/coreutils-gotchas.html#sort

and drilling down from there have given an example of a comparison
where leading blanks are significant (and useful) at the bottom of:
http://www.pixelbeat.org/patches/coreutils/sort-debug/

cheers,
Pádraig.
>From a3311c966e34f2d9f8aa6b1de31b211124803d02 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?P=C3=A1draig=20Brady?= <[email-masked]>
Date: Wed, 1 Jun 2016 11:56:47 +0100
Subject: [PATCH] doc: clarify sort --key handling of default field separators

* doc/coreutils.texi (sort invocation): Mention in the summary
dicussion that --key is used to specify fields.  Give a summary
in the --key description, of the most common use case of specifying
a field, and that by default those fields include the blank separators
at the start of each field in the comparisons.
---
 doc/coreutils.texi | 11 +++++++++--
 1 file changed, 9 insertions(+), 2 deletions(-)

diff --git a/doc/coreutils.texi b/doc/coreutils.texi
index 6a671bb..47c63db 100644
--- a/doc/coreutils.texi
+++ b/doc/coreutils.texi
@@ -4022,7 +4022,7 @@ sort [@var{option}]@dots{} [@var{file}]@dots{}
 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
+@command{sort} compares each pair of fields (see @option{--key}), 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
@@ -4332,7 +4332,14 @@ Specify a sort field that consists of the part of the line between
 @var{pos1} and @var{pos2} (or the end of the line, if @var{pos2} is
 omitted), @emph{inclusive}.
 
-Each @var{pos} has the form @samp{@var{f}[.@var{c}][@var{opts}]},
+In its simplest form @var{pos} specifies a field number (starting with 1),
+with fields being separated by runs of blank characters, and by default
+those blanks being included in the comparison at the start of each field.
+To adjust the handling of blank characters see the @option{-b} and
+@option{-t} options.
+
+More generally,
+each @var{pos} has the form @samp{@var{f}[.@var{c}][@var{opts}]},
 where @var{f} is the number of the field to use, and @var{c} is the number
 of the first character from the beginning of the field.  Fields and character
 positions are numbered starting with 1; a character position of zero in
-- 
2.5.5