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

[Aharon Robbins]

Hi.

> Date: Wed, 11 Dec 2013 11:36:12 -0500
> From: "Andrew J. Schorr" <address@hidden>
> To: Aharon Robbins <address@hidden>
> Cc: address@hidden
> Subject: Re: [bug-gawk] asort/asorti documentation issues
>
> 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?

I think you missed the part where it said that the description ignored "how".
I put that into a NOTE to make it stand out.

> 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".

Yeah, but it's good enough for an intro.

> 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.

I just removed that paragraph. It was left over fro 3.x.

> 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.

I've pushed the changes.

Thanks,

Arnold