bug#23556: sort(1): misleading description of option -n

[Carsten Hey]

Hi,

looks like this weekend's (routing?) problems related to mail delivery
to @gnu.org addresses, which were also noticed by at least three other
people, are resolved now :)

I forwarded my mail to the Debian BTS (since it didn't get delivered at
first), but the people that read it there did not get its actual
intention (and if multiple people do so, the sender likely did something
wrong).  Reading this Debian bug would not provide any additional useful
information.

* Assaf Gordon [2016-05-16 15:07 -0400]:
> On 05/14/2016 10:17 AM, Carsten Hey wrote:
> >the man page sort(1) contains a misleading description of the option -n:
> [...]
> >
> >     $ man sort | grep -A1 -- --numeric-sort | sed -n -e 's/^ *//' -e '1!p'
> >     compare according to string numerical value
> [...]
> >This description reads as if this command:
> >
> >$ printf '%s\n' 'x 9' 'x 10' | sort -n
> >x 10
> >x 9
> [...]
> >but instead, -n stops doing its magic after finding the first
> >non-numeric, non-whitespace character. There is a short and simple
> >way to summarize this behaviour.
>
> IIUC, you are disputing the accuracy (or clarity) of the term "string
> numerical value" on the manual page, and not the actual behavior of
> "sort -n" …

Exactly.  It seems like many people have problems to understand mails
that contain code, but are neither a patch nor complain about the
behaviour of a program - maybe my wording was suboptimal too.  I'll
consider this in future when I write similar mails.

> The description says "string numeric value" - which (to me) does not
> mean anything other than numeric value (implying letters will not be
> sorted properly), but opinions clearly differ.

We all know that '1st', '2nd', '3rd', …, '9th', '10th' and so on are
sorted in this order if -n is used.  We also know that piping lines that
match ./[0-9][0-9]* to sort -n (which happens every time I upgrade my
mobile's operating system) is a useless use of -n.

Neither the description of -n in the man page, nor the explanation how
you would read these words explain this difference in any way, at least
without an additional definition of "string numeric value".

> If you have a suggestion for improved wording, I'm sure they can be
> considered for inclusion.

If I would not know that "string numeric value" is proper English,
I wouldn't consider it to be correct, hence I'm likely the wrong person
to suggest a concrete wording, …

> the description in the man page is derived from "sort --help",
> and thus kept brief.

…, especially, when it needs to be that short.

I assume that a brief and proper description would either contain the
word "beginning" or the word "initial".  Suggestions I have at the
moment are "sort a text's initial numeric parts", "sort initial numeric
parts of a text" and "sort numbers at the beginning of a text", but
a native speaker is likely able to find something better and more
correct (actually, the initial numeric parts aren't sorted, they are
used as sorting key).

Due to the need to translate those stings, a change after a release
might be better than a change before a release.


Thanks,
Carsten