Re: [PATCH] update info documentation about version sort

[Jim Meyering]

Kamil Dudka wrote:
> proposed patch which updates info documentation about version sort (to reflect
> filevercmp behavior) is attached.
>
> Kamil
>
> From 6ae36e04df4db674ab2022c12df0319b768260dd Mon Sep 17 00:00:00 2001
> From: Kamil Dudka <address@hidden>
> Date: Wed, 25 Feb 2009 10:10:36 +0100
> Subject: [PATCH] update info documentation about version sort
>
> * doc/coreutils.texi: Reflect current filevercmp behavior.
> ---
>  doc/coreutils.texi |   22 +++++++++++++---------
>  1 files changed, 13 insertions(+), 9 deletions(-)
>
> diff --git a/doc/coreutils.texi b/doc/coreutils.texi
> index 2c1fae5..c65927d 100644
> --- a/doc/coreutils.texi
> +++ b/doc/coreutils.texi
> @@ -6661,21 +6661,25 @@ foo.zml-25.gz      foo.zml-25.gz
>  foo.zml-6.gz       foo.zml-100.gz
>  @end example
>
> -Note also that numeric parts with leading zeros are considered as
> -fractional one:
> +The file names are compared in a way that if VER1 and VER2 are version 
> numbers
> +and PREFIX and SUFFIX (SUFFIX defined as (\.[A-Za-z][A-Za-z0-9]*)*) are 
> strings
> +then VER1 < VER2 implies that file "PREFIX VER1 SUFFIX" is before
> +"PREFIX VER2 SUFFIX".
> +
> +Note also that leading zeros of numeric parts are ignored:
>
>  @example
>  $ ls -1            $ ls -1v
> -abc-1.007.tgz      abc-1.007.tgz
> -abc-1.012b.tgz     abc-1.01a.tgz
> +abc-1.007.tgz      abc-1.01a.tgz
> +abc-1.012b.tgz     abc-1.007.tgz
>  abc-1.01a.tgz      abc-1.012b.tgz
>  @end example
>
> -This functionality is implemented using the @code{strverscmp} function.
> address@hidden/Array Comparison, , , libc, The GNU C Library Reference 
> Manual}.
> -One result of that implementation decision is that @code{ls -v} does not
> -use the locale category, @env{LC_COLLATE}.  As a result, non-numeric prefixes
> -are sorted as if @env{LC_COLLATE} were set to @code{C}.
> +This functionality is implemented using the @code{fileverscmp} function
> +from gnulib. One result of that implementation decision is that @code{ls -v}
> +and @code{sort -V} does not use the locale category, @env{LC_COLLATE}.
> +As a result, non-numeric prefixes are sorted as if @env{LC_COLLATE} were set
> +to @code{C}.

Thank you. (and thanks for reminding me about it today).
Here are some suggested changes.
Please sanity-check and let me know.

diff --git a/doc/coreutils.texi b/doc/coreutils.texi
index 9deb8c0..930bb8a 100644
--- a/doc/coreutils.texi
+++ b/doc/coreutils.texi
@@ -6661,10 +6661,12 @@ More details about version sort
 foo.zml-6.gz       foo.zml-100.gz
 @end example

-The file names are compared in a way that if VER1 and VER2 are version numbers
-and PREFIX and SUFFIX (SUFFIX defined as (\.[A-Za-z][A-Za-z0-9]*)*) are strings
-then VER1 < VER2 implies that file "PREFIX VER1 SUFFIX" is before
-"PREFIX VER2 SUFFIX".
+Version-sorted strings are compared such that if @var{ver1} and @var{ver2}
+are version numbers and @var{prefix} and @var{suffix} (@var{suffix} matching
+the regular expression @samp{(\.[A-Za-z][A-Za-z0-9]*)*}) are strings then
address@hidden < @var{ver2} implies that the name composed of
address@hidden @var{ver1} @var{suffix}'' sorts before
address@hidden @var{ver2} @var{suffix}''.

 Note also that leading zeros of numeric parts are ignored:

@@ -6675,11 +6677,11 @@ More details about version sort
 abc-1.01a.tgz      abc-1.012b.tgz
 @end example

-This functionality is implemented using the @code{fileverscmp} function
-from gnulib. One result of that implementation decision is that @code{ls -v}
-and @code{sort -V} does not use the locale category, @env{LC_COLLATE}.
-As a result, non-numeric prefixes are sorted as if @env{LC_COLLATE} were set
-to @code{C}.
+This functionality is implemented using gnulib's @code{fileverscmp} 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}.

 @node General output formatting
 @subsection General output formatting