gwern wrote:
> Package: coreutils
> Version: 8.5-1
> Severity: minor
>
> The existing documentation for the option:
>
> -R, --random-sort
> sort by random hash of keys
>
> This is not wrong, strictly-speaking, but it is misleading: sorting by random
> hash *sounds* like a perfect shuffle,
> which is what 99% of users want, and sorting by hash is equivalent if and if
> only there are no duplicate entries.
> If there *are* duplicate entries, then the 'random' sort will put all
> duplicates in consecutive runs.
>
> I suggest amending the line to read more like
>
> sort by random hash of keys; equivalent to perfect shuffle on
> unique keys
>
> or maybe just say
>
> sort by random hash of keys; not the same as a perfect shuffle
>
> Or at least warn in some fashion that 'random' is not quite what 'random'
> usually means on lists.
>
> (I do random shuffle with mplayer using 'sort -R', and once, to 'bias' the
> selection to a particular set of songs, I put that directory in
> 3 or 4 times; I thought I was going crazy when the first such song came up 3
> times, which I calculated at billions to one against.
> I checked everything until I began to wonder what exactly 'random hash of
> keys' meant, and then saw how it treated duplicate entries.)
Thanks for the suggestion, but we try to keep the man page pretty terse,
since it's automatically derived from sort --help output.
Did you see the "real" documentation?
`-R'
`--random-sort'
`--sort=random'
Sort by hashing the input keys and then sorting the hash values.
Choose the hash function at random, ensuring that it is free of
collisions so that differing keys have differing hash values.
This is like a random permutation of the inputs (*note shuf
invocation::), except that keys with the same value sort together.
If multiple random sort fields are specified, the same random hash
function is used for all fields. To use different random hash
functions for different fields, you can invoke `sort' more than
once.
The choice of hash function is affected by the `--random-source'
option.
There should be a note like this the end of the man page:
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 sort
should give you access to the complete manual.
--
To UNSUBSCRIBE, email to debian-bugs-dist-requ...@lists.debian.org
with a subject of "unsubscribe". Trouble? Contact listmas...@lists.debian.org
