bug#33786: Bug: undocumented feature (algorithm) for version-sort (include on manpage)

[Assaf Gordon]

tags  33786 notabug
severity 33786 wishlist
retitle 33786 doc: sort: document Debian's version-sort algorithm
stop

Hello,

On 2018-12-18 12:11 a.m., L A Walsh wrote:
> meaning that if one is going to put a Debian sort into a
> general purpose tool like "sort", then the algorithm really
> needs to be documented.

It is well documented in many places online, e.g.:
https://www.debian.org/doc/debian-policy/ch-controlfields.html#version
https://readme.phys.ethz.ch/documentation/debian_version_numbers/

With a shorter summary available in the coreutils manual here:
https://www.gnu.org/software/coreutils/manual/html_node/Details-about-version-sort.html#Details-about-version-sort

> This means there is no way to verify consistent behavior
> from as the utility matures 

The sort-version.sh test ensure the behavior is consistent from
one release to the next:
https://opengrok.housegordon.com/source/xref/coreutils/tests/misc/sort-version.sh

It also ensures the behavior is compatible with Debian's definition.

> and no way to write an
> independent, auditable test case to assure that the sort algorithm, 
> operates with consistency from release to release
> as well as w/r/t other included sort algorithms.

This message contains example of how to compare results between
coreutils' sort and debian's utilities:
https://lists.gnu.org/archive/html/bug-coreutils/2018-11/msg00017.html

Here's a post about doing the same using python:
https://stackoverflow.com/a/4957741

And in NodeJS:
https://www.npmjs.com/package/deb-version-compare

I'm sure there are many other implementations that
allow easy comparison of one against the other to quickly find
any discrepancies.


As for auditable code, the actual code is here (part of gnulib):
https://opengrok.housegordon.com/source/xref/gnulib/lib/filevercmp.c

And gnulib also includes a unit-test:
https://opengrok.housegordon.com/source/xref/gnulib/tests/test-filevercmp.c

There's no better audit-ability than the source code itself.


> The request here is for the algorithm used by 'version-sort'
> be included in sort's manpage.  This should document
> sort's features for reference and use by users who are using
> the utility in its native, cmd-line environment.

If a coreutils' program implements a known standard,
it's not necessarily beneficial to include implementation details of
the standard, as this is available elsewhere.

For example, the manual for the "base64" program does not include
an explanation of what base64 is. Instead, it links to RFC4648:
https://www.gnu.org/software/coreutils/manual/html_node/base64-
invocation.html#base64-invocation

As your request is for a change in documentation, I'm marking this
as a wish-list item.
As always, concrete patches are welcomed and they go a long way towards
expediting any desired changes - if you have suggestions please do send
a patch.

> Also of importance: that the documentation should be include with the
> source and installable with the program executable.
When someone downloads coreutils' source, they automatically get
the manual (in texinfo format, easily convertible to HTML/PDF).

When they install coreutils (e.g. "make install"), the manual
is also installed (as an "info" file).


regards,
 - assaf