Re: [Bug-readline] Minor bone to pick regarding the doc for next_history()

[Glenn Golden]

>
> The final sentence covers this.
>

Disagree. The final sentence again uses the ambiguous phrase "end of the
history list". If the reader's idea of what that means differs from yours,
then that phrase can't be considered to convey useful information.

In the previous post I argued that a reasonable interpretation of "end of
the list" is offset == history_length-1. Your interpretation is that it means
offset == history_length. I'm not criticizing your interpretation, only saying
that it is not the only reasonable one possible.

If you disagree, then by all means, argue that offset == history_length-1 is
unreasonable or foolish.  I doubt you can make this argument convincingly,
but am willing to listen.  Otoh, if you can't make that argument, then the
phrase "end of the history list" should be avoided.  I don't see any other
choice, if the goal is to provide clear documentation of the function.

>
> There are really only two cases: does the function return NULL or does it
> return a pointer to a history entry?  If the function returns NULL, the
> history offset is at the end of the list.  It doesn't matter where it
> started;
>

It surely does, in some situations.  The reason I came across this doc issue
was because it _did_ matter in what I was doing:  Moving thru the history list
and pruning/modifying certain entries, while using 'offset' to keep track of an
internal representation.  I expected the description of the pre- and post-call
values of 'offset' to hew to the documentation, and they did not.  That's why
I filed the original post.

>
> if the caller is interested in the value before calling next_history() there
> are other functions that return it.  (The value of the history offset is
> public, so an interested caller can get it before or after the next_history()
> call.  You don't have to guess.)
>

The point is that even if the caller knows the value of 'offset' before he
calls next_history(), he doesn't necessarily know the post-return value in
all cases, because the documentation doesn't unambiguously address the edge
case.  Your suggested rewording does not help because the phrase "end of the
history list" is still ambiguous.

If that ambiguity were avoided, it wouldn't be _necessary_ for the caller to
invoke other API functions to learn the value of 'offset' after the call, or to
figure out via offline experiments how the next_history() function actually
affects 'offset' at the edge conditions.  He would be able to gain that
knowledge by simply reading the documentation, not doing science experiments.

>
> I agree that the wording can be improved to clarify that incrementing the
> history offset can move it to the end.
> 

The patched text I supplied provided just that improvement, by avoiding any use
of the word "end".  It straightforwardly and completely described exactly how
the function behaves.

Look Chet, if this doc were part of any other project besides GNU, I wouldn't
even bother haranguing you about what is surely a minor point like this.  But
the standards for GNU doc have always been very high, and your work on bash an
other GNU doc is generally an exemplary combination of brevity and accuracy.
I don't understand why you're pushing back on documenting this function in a
way which clarifies its actions without introducing ambiguity.

If you don't like the particular language I originally suggested, then by all
means critique it, redact it, whatever.  But don't keep falling back on the
same phraseology that caused the issue to arise in the first place.

Here are a few wordsmithed alternatives to the original suggestion, perhaps
one of these will suit your fancy better:

Original:
    "If the current history offset points to an extant history entry, then
     increment it, otherwise leave it as is. If the conditionally incremented
     history offset points to an extant history entry, return a pointer
     to that entry, otherwise return a \fBNULL\fP pointer."

Mod 1:
    "If 'offset' points to an existing history entry, increment it, otherwise
     leave it as is.  Then, if that (possibly incremented) value of 'offset'
     points to a history entry, return a pointer to that entry, otherwise
     return a \fBNULL\fP pointer."

Mod 2:
    "If the current value of 'offset' points to an existing history entry,
     then increment 'offset', otherwise leave it as is.  If the value of
     'offset' then still points to a history entry, return a pointer to that
     entry, otherwise return a \fBNULL\fP pointer."

All of the above get the job done for the reader, fully and completely, without
any ambiguity; they accurately cover the edge cases at both the initial state
(history list empty) as well as for offset == history_length-1 and for
offset == history length.  What's not to like?