Prev: Serial to Ethernet adapters
Next: Bogus "Unable to mount" error dialog
From: Nix on 15 May 2010 18:24
On 3 May 2010, Martin Gregorie stated:

> - the manpage is so terse as to be meaningless and says nothing
> about apparently valid combinations of sort parameters,
> e.g. what if I want to do a caseless sort on column 3

'info sort'
From: Martin Gregorie on 21 May 2010 11:56
On Sat, 15 May 2010 23:24:02 +0100, Nix wrote:

> On 3 May 2010, Martin Gregorie stated:
>
>> - the manpage is so terse as to be meaningless and says nothing
>> about apparently valid combinations of sort parameters, e.g. what if
>> I want to do a caseless sort on column 3
>
> 'info sort'

info is an abomination - why can't full summary informmation be in the
manpage and the rest on a set of web pages where it belongs. In this case
the sort manpage is severely deficient because doesn't so much as hint
that there may be a an ability to list a set of keys with different sort
orders and collation sequences?

Nor, for that matter, is it clear that there is an info entry.


--
martin@ | Martin Gregorie
gregorie. | Essex, UK
org |
From: Richard Kettlewell on 21 May 2010 12:36
Martin Gregorie <martin(a)address-in-sig.invalid> writes:
> On Sat, 15 May 2010 23:24:02 +0100, Nix wrote:
>> On 3 May 2010, Martin Gregorie stated:

>>> - the manpage is so terse as to be meaningless and says nothing
>>> about apparently valid combinations of sort parameters, e.g. what if
>>> I want to do a caseless sort on column 3
>>
>> 'info sort'
>
> info is an abomination - why can't full summary informmation be in the
> manpage and the rest on a set of web pages where it belongs. In this
> case the sort manpage is severely deficient because doesn't so much as
> hint that there may be a an ability to list a set of keys with
> different sort orders and collation sequences?
>
> Nor, for that matter, is it clear that there is an info entry.

In this particular case, 'info sort' on a Debian stable system just
reproduces the man page; you have to use 'info coreutils' and follow
your nose from there.

It works better in unstable, admittedly.

--
http://www.greenend.org.uk/rjk/
From: Nix on 21 May 2010 18:31
On 21 May 2010, Martin Gregorie uttered the following:

> On Sat, 15 May 2010 23:24:02 +0100, Nix wrote:
>
>> On 3 May 2010, Martin Gregorie stated:
>>
>>> - the manpage is so terse as to be meaningless and says nothing
>>> about apparently valid combinations of sort parameters, e.g. what if
>>> I want to do a caseless sort on column 3
>>
>> 'info sort'
>
> info is an abomination - why can't full summary informmation be in the
> manpage and the rest on a set of web pages where it belongs. In this case

Because the GNU project has always used texinfo for its documentation,
and because texinfo is a not-particularly-awful source format for a huge
number of different outputs (among others, info, web pages, printed
books... some of the *output* formats are nasty, but that's not the
fault of the source format.)

(These days manpages are generally generated from the texinfo and thus
are not out of date, the old criticism of the GNU project's manpages.)

> the sort manpage is severely deficient because doesn't so much as hint
> that there may be a an ability to list a set of keys with different sort
> orders and collation sequences?

That's because it's not the job of the manpage to teach you POSIX, and
manpages are an awful place to include lengthy documentation (see the
perl man wireshark manpages for horrible examples).

FWIW, 'man sort' on Solaris 10, while it documents LC_COLLATE, does not
document the possiblity of multiple key fields anywhere. On all the
systems I have access to, the first thing it gives you when you type
'man sort' is not the Unix command but sort(3C++), a description of the
sort algorithm in the hilariously out-of-date pre-standardization Rogue
Wave implementation that Solaris uses for its standard C++ library. Very
helpful.

> Nor, for that matter, is it clear that there is an info entry.

Except for the bottom of the manpage, where it says

,----
| SEE ALSO
|
| The full documentation for sort is maintained as a Texinfo
| manual. If the info and sort programs are properly installed at
| your site, the command
|
| info coreutils 'sort invocation'
|
| should give you access to the complete manual.
`----

(coreutils 8.5, but this message has been there for a long time.)

If you're not going to read the manpage far enough to see that, why
are you complaining that other things aren't present there?
From: Martin Gregorie on 22 May 2010 08:26
On Fri, 21 May 2010 23:31:27 +0100, Nix wrote:

>
> If you're not going to read the manpage far enough to see that, why are
> you complaining that other things aren't present there?

It would have been much better to have entirely omitted any discussion of
to -k option and said something like "info coreutils 'sort invocation'"
for details of how to specify a sort key.

As it is, given that the -k option definition is "-k, --key=POS1[,POS2]"
and that the partial, and rather detailed definition in the following
paragraphs:

POS is F[.C][OPTS], where F is the field number and C the character
position in the field; both are origin 1. If neither -t nor -b is in
effect, characters in a field are counted from the beginning of the
preceding whitespace. OPTS is one or more single-letter ordering
options, which override global ordering options for that key. If no
key is given, use the entire line as the key.

SIZE may be followed by the following multiplicative suffixes: % 1% of
memory, b 1, K 1024 (default), and so on for M, G, T, P, E, Z, Y.

is apparently a complete definition of the -k option I can't see why
anybody should consider that there's any need to look further.

I'm sorry, this is just a badly written and misleading man page that is
badly in need of revision. I'd much rather see a bare direction to look
at infotext than the actual content.


--
martin@ | Martin Gregorie
gregorie. | Essex, UK
org |
First  |  Prev  | 
Pages: 1 2 3
Prev: Serial to Ethernet adapters
Next: Bogus "Unable to mount" error dialog