[Top][All Lists]

[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

From: Chet Ramey
Subject: Re: [Bug-readline] Minor bone to pick regarding the doc for next_history()
Date: Sat, 11 Apr 2015 13:51:09 -0400
User-agent: 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 
> reasonably
> 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/

reply via email to

[Prev in Thread] Current Thread [Next in Thread]