[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
Re: [Bug-readline] Minor bone to pick regarding the doc for next_history
Re: [Bug-readline] Minor bone to pick regarding the doc for next_history()
Sat, 11 Apr 2015 13:51:09 -0400
Mozilla/5.0 (Macintosh; Intel Mac OS X 10.10; rv:31.0) Gecko/20100101 Thunderbird/31.6.0
On 4/7/15 6:24 AM, Glenn Golden wrote:
> The second is important though, about the semantics of the phrase "already
> at the end of the history list".
> Consider these three pre-call situations, all of which can occur in practice:
> (1) offset == history_length-2
> (2) offset == history_length-1
> (3) offset == history_length
> Think about these vis a vis your phrase "already at the end of the history
> list" and the meaning the reader may attach to it. It seems to me that (1)
> and (3) have no wiggle room for interpretation: Situation (1) cannot
> be interpreted as "already at the end of the history list" and (3) _must_ be
> interpreted as "already at the end of the history list". No wiggle room.
> Now consider situation (2), and read the first sentence of your text above,
> as if you were a first-time reader. Ask yourself: Does the phrase "not already
> at the end of the history list" apply to (2)?
> If the reader's answer is 'yes' (i.e. 'offset' is "not at the end of the
> history list") then your text correctly describes the function's actual
> behavior upon return: The value of 'offset' has been incremented and is now
> equal to history_length. But if his answer is 'no', then he gets the
> wrong idea about the value of 'offset' upon return: He thinks it'll still
> be history_length-1, because according to your text it wasn't incremented.
The final sentence covers this. 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; 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.) In this case, incrementing the history offset to the next entry
moves it to the end of the history list.
I agree that the wording can be improved to clarify that incrementing the
history offset can move it to the end.
``The lyf so short, the craft so long to lerne.'' - Chaucer
``Ars longa, vita brevis'' - Hippocrates
Chet Ramey, ITS, CWRU address@hidden http://cnswww.cns.cwru.edu/~chet/