Re: [bug-gawk] asort 3rd argument does not work as documented

[Aharon Robbins]

Hi again.

> Date: Fri, 8 Nov 2013 12:49:01 -0500
> From: "Andrew J. Schorr" <address@hidden>
> To: address@hidden
> Subject: [bug-gawk] asort 3rd argument does not work as documented
>
> Hi,
>
> In doc/gawk.texi, it says:
>
>    The optional third argument @var{how} is a string which controls the rule
>    for comparing values, and the sort direction.  A single space is required
>    between the comparison mode, @samp{string} or @samp{number}, and the
>    direction specification, @samp{ascending} or @samp{descending}.  
>
> ....
>
> So it seems that there is either a documentation bug,

How does this look as a patch?

Thanks,

Arnold
------------------------------
diff --git a/doc/gawktexi.in b/doc/gawktexi.in
index bcffebf..dfc0b0e 100644
--- a/doc/gawktexi.in
+++ b/doc/gawktexi.in
@@ -14947,16 +14947,18 @@ and replaces the indices
 of the sorted values of @var{source} with sequential
 integers starting with one.  If the optional array @var{dest} is specified,
 then @var{source} is duplicated into @var{dest}.  @var{dest} is then
-sorted, leaving the indices of @var{source} unchanged.  The optional third
+sorted, leaving the indices of @var{source} unchanged.
+
+The optional third
 argument @var{how} is a string which controls the rule for comparing values,
-and the sort direction.  A single space is required between the
-comparison mode, @samp{string} or @samp{number}, and the direction 
specification,
address@hidden or @samp{descending}.  You can omit direction and/or mode
-in which case it will default to @samp{ascending} and @samp{string}, 
respectively. 
-An empty string "" is the same as the default @code{"ascending string"}
-for the value of @var{how}.  If the @samp{source} array contains subarrays as 
values,
-they will come out last(first) in the @samp{dest} array for 
@samp{ascending}(@samp{descending})
-order specification.  The value of @code{IGNORECASE} affects the sorting.
+and the sort direction.
+It should be one of the special constant values recognized for
address@hidden"sorted_in"]} (@pxref{Controlling Scanning}), with the exception
+of @code{"unsorted"}, which would make no sense.
+The default is
address@hidden"@@val_type_asc"}, which sorts by ascending value:
+numbers before strings before subarrays.
+The value of @code{IGNORECASE} affects the sorting.
 The third argument can also be a user-defined function name in which case
 the value returned by the function is used to order the array elements
 before constructing the result array.
@@ -14990,7 +14992,7 @@ In order to reverse the direction of the sorted results 
in the above example,
 @code{asort()} can be called with three arguments as follows:
 
 @example
-asort(a, a, "descending")
+asort(a, a, "@@val_type_desc")
 @end example
 
 The @code{asort()} function is described in more detail in