Subject: bug#25292: Ambiguity in doc string of defvar

From: Alan Mackenzie <[email-masked]>
Date: Thu, 29 Dec 2016 19:42:38 +0000

Hello, Eli.

On Thu, Dec 29, 2016 at 08:29:15PM +0200, Eli Zaretskii wrote:
> > Date: Thu, 29 Dec 2016 18:18:38 +0000
> > From: Alan Mackenzie <[email-masked]>

> >     INITVALUE is evaluated, and if SYMBOL's value is void, it is used to
> >     set SYMBOL.                                            ^^

> That "it" is ambiguous.  By default, people tend to interpret "it" as
> referring to the last noun before it, but that's not what you mean in
> this case.

Yes, it's no better than what I was complaining about.  :-(

> And after all that, are you sure INITVALUE is always evaluated?

I've had a look at eval.c.  INITVALUE is evaluated only when it's going
to be used.

So, maybe the whole paragraph should look like this:

    If SYMBOL's value is void and the optional argument INITVALUE is
    provided, INITVALUE is evaluated and the result used to set SYMBOL.
    If SYMBOL is buffer-local, its default value is what is set;
    buffer-local values are not affected.  If INITVALUE is missing,
    SYMBOL's value is not set.
 
What do you think?

-- 
Alan Mackenzie (Nuremberg, Germany).