doc: enhance and reference info about version comparison

* doc/coreutils.texi (sort invocation): Reference the additional
info about filevercmp rather than the unused strverscmp.
(Details about version sort): Add some examples that are not
handled well by fileversmp.
* src/ls.c: Change a comment referencing the now unused strverscmp.

2 files changed, 33 insertions, 25 deletions

diff --git a/doc/coreutils.texi b/doc/coreutils.texi
index 3721beea4..e097c257d 100644
--- a/doc/coreutils.texi
+++ b/doc/coreutils.texi
@@ -3862,10 +3862,9 @@ To compare such strings numerically, use the
 @opindex -V
 @opindex --version-sort
 @cindex version number sort
-@vindex LC_NUMERIC
-Sort per @code{strverscmp(3)}.  This is a normal string comparison, except
-that embedded decimal numbers are sorted by numeric value
-(see @option{--numeric-sort} above).
+Sort by version name and number.  It behaves like a standard sort,
+except that each sequence of decimal digits is treated numerically
+as an index/version number.  (@xref{Details about version sort}.)
 
 @item -r
 @itemx --reverse
@@ -6685,23 +6684,17 @@ after the last @samp{.}); files with no extension are sorted first.
 @node Details about version sort
 @subsection Details about version sort
 
-The version sort takes into account the fact that file names frequently include
-indices or version numbers.  Standard sorting functions usually do not produce
-the ordering that people expect because comparisons are made on a
-character-by-character basis.  The version
-sort addresses this problem, and is especially useful when browsing
-directories that contain many files with indices/version numbers in their
-names:
+Version sorting handles the fact that file names frequently include indices or
+version numbers.  Standard sorting usually does not produce the order that one
+expects because comparisons are made on a character-by-character basis.
+Version sorting is especially useful when browsing directories that contain
+many files with indices/version numbers in their names:
 
 @example
 $ ls -1            $ ls -1v
-foo.zml-1.gz       foo.zml-1.gz
-foo.zml-100.gz     foo.zml-2.gz
-foo.zml-12.gz      foo.zml-6.gz
-foo.zml-13.gz      foo.zml-12.gz
-foo.zml-2.gz       foo.zml-13.gz
-foo.zml-25.gz      foo.zml-25.gz
-foo.zml-6.gz       foo.zml-100.gz
+abc.zml-1.gz       abc.zml-1.gz
+abc.zml-12.gz      abc.zml-2.gz
+abc.zml-2.gz       abc.zml-12.gz
 @end example
 
 Version-sorted strings are compared such that if @var{ver1} and @var{ver2}
@@ -6720,11 +6713,27 @@ abc-1.012b.tgz     abc-1.007.tgz
 abc-1.01a.tgz      abc-1.012b.tgz
 @end example
 
-This functionality is implemented using gnulib's @code{filevercmp} function.
-One result of that implementation decision is that @samp{ls -v}
-and @samp{sort -V} do not use the locale category, @env{LC_COLLATE},
-which means non-numeric prefixes are sorted as if @env{LC_COLLATE} were set
-to @samp{C}.
+This functionality is implemented using gnulib's @code{filevercmp} function,
+which has some caveats worth noting.
+
+@itemize @bullet
+@item @env{LC_COLLATE} is ignored, which means @samp{ls -v} and @samp{sort -V}
+will sort non-numeric prefixes as if the @env{LC_COLLATE} locale category
+was set to @samp{C}.
+@item Some suffixes will not be matched by the regular
+expression mentioned above.  Consequently these examples may
+not sort as you expect:
+
+@example
+abc-1.2.3.4.7z
+abc-1.2.3.7z
+@end example
+
+@example
+abc-1.2.3.4.x86_64.rpm
+abc-1.2.3.x86_64.rpm
+@end example
+@end itemize
 
 @node General output formatting
 @subsection General output formatting
diff --git a/src/ls.c b/src/ls.c
index aeaa58417..6c1f275dc 100644
--- a/src/ls.c
+++ b/src/ls.c
@@ -3272,8 +3272,7 @@ DEFINE_SORT_FUNCTIONS (extension, cmp_extension)
    All the other sort options, in fact, need xstrcoll and strcmp variants,
    because they all use a string comparison (either as the primary or secondary
    sort key), and xstrcoll has the ability to do a longjmp if strcoll fails for
-   locale reasons.  Last, strverscmp is ALWAYS available in coreutils,
-   thanks to the gnulib library. */
+   locale reasons.  Lastly, filevercmp is ALWAYS available with gnulib.  */
 static inline int
 cmp_version (struct fileinfo const *a, struct fileinfo const *b)
 {