Re: [bug-gawk] asort/asorti documentation issues

[Andrew J. Schorr]

Hi Arnold,

Sorry for the delay.  I have been very busy.

On Mon, Dec 09, 2013 at 09:43:18PM +0200, Aharon Robbins wrote:
> It is likely easiest to apply the diff and then format a PDF and review
> that; it's much easier to see if the word flow makes sense by looking at
> the formatted manual than by just reading the source.

OK, I built doc/gawk.pdf and then searched for "asort" and read those
sections.  Here are a couple of comments:

In "9.1.3 String-Manipulation Functions", it says:

   For asort(), gawk sorts the values of source and replaces the indices of the
   sorted values of source with sequential integers starting with one.

This is true for the default case, but not necessarily true when a "how"
argument is specified.  Does that point need to be made here?
And below, it says:

   The asorti() function works similarly to asort(), however, the indices are
   sorted, instead of the values.

This is again true in the default case, but not for some values of "how".

Later, in "12.2 Controlling Array Traversal and Array Sorting", it says:

    In addition, two built-in functions, asort() and asorti(), let you sort
    arrays based on the array values and indices, respectively.

This is again not true for some values of "how".

I think the language in 12.2.2 looks good.  But I don't understand this
one sentence:

   Sorting the array by replacing the indices provides maximal flexibility.

Is this simply saying that gawk's sorting features are powerful, or is it
recommending one particular way of sorting over another?  I'm not sure
what that sentence is supposed to convey.

Overall, it's much better.  I think it's probably OK as is, but a user
could get confused if they don't read 12.2.2.

Thanks for tackling this,
Andy