Subject: RE: 24.0.50; Doc string of `lexical-binding'

From: "Drew Adams" <[email-masked]>
Date: Fri, 15 Jul 2011 08:19:39 -0700

> > I haven't seen your fix, but it could be misleading to just 
> > mention `eval-*' even if you remove "only".
> 
> The current text is:
> 
> ---
> If non-nil, use lexical binding when evaluating code.
> This applies to code evaluated by `eval-buffer' and `eval-region' and
> other commands that call these functions, like `eval-defun' and
> the like.
> This variable is automatically set from the file variables of an
> interpreted Lisp file read using `load'.
> ---
> 
> I'm not sure that that's much clearer than the original, actually.

The problem is this: We say that it "applies to" a certain number of cases.
That begs the question, "What does it _not_ apply to?"

IOW, why don't we just say this?

 "Non-nil means use lexical binding when evaluating code."

Presumably there is some good reason why we don't.  And that good reason remains
a mystery: in what cases does non-nil _not_ mean to use lexical binding when
evaluating code?

Or if there are really no such cases, and the only reason for mentioning
`eval-*' in the first place was to give some examples, then make that clear.

Say, in that case, "For example, ... `eval-buffer'...".

Currently it is not clear (I have no idea, in fact) whether non-nil always means
use lexical binding or not.  And if not, I have no idea what those "not" cases
are.  In sum, I haven't a clue what the value does, except that at least in some
cases it means use lexical binding when evaluating code.

It's not about the _wording_.  I can help with the wording if you provide the
content.  What is it that we are trying to communicate to users, exactly?