GNU bug report logs - #33786
doc: sort: document Debian's version-sort algorithm

Previous Next

Full log

View this message in rfc822 format

From: L A Walsh <coreutils <at> tlinx.org>
To: Assaf Gordon <assafgordon <at> gmail.com>
Cc: 33786 <at> debbugs.gnu.org
Subject: bug#33786: Bug: undocumented feature (algorithm) for version-sort (include on manpage)
Date: Tue, 18 Dec 2018 00:06:22 -0800

So undocumented features are considered wishlist items
in Gnu?   

On 12/18/2018 12:04 AM, Assaf Gordon wrote:
> 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

Previous Next

GNU bug tracking system
Copyright (C) 1999 Darren O. Benham, 1997,2003 nCipher Corporation Ltd, 1994-97 Ian Jackson.