bug#8460: 24.0.50; Doc string of `lexical-binding'

bug#8460: 24.0.50; Doc string of `lexical-binding'

[Drew Adams]

It says that it "only applies to code evaluated by `eval-buffer' and
`eval-region'."  That is at best misleading.  `C-M-x' eventually calls
`eval-region', but a user would not guess that the doc string applies
also to `C-M-x'.  It would perhaps be better to characterize the
situations where it does _not_ apply to code evaluation.
 
It is also misleading in that it is sufficient to visit a file, such as
`minibuffer.el', that has "-*- lexical-binding: t -*-" in its first
line, for the value to be non-nil and thus affect pretty much anything
you do in that buffer.

In GNU Emacs 24.0.50.1 (i386-mingw-nt5.1.2600)
 of 2011-04-04 on 3249CTO
Windowing system distributor `Microsoft Corp.', version 5.1.2600
configured using `configure --with-gcc (4.5) --no-opt --cflags
-Ic:/imagesupport/include'
 

bug#8460: 24.0.50; Doc string of `lexical-binding'

[Lars Magne Ingebrigtsen]

"Drew Adams" <drew.adams@oracle.com> writes:

> It says that it "only applies to code evaluated by `eval-buffer' and
> `eval-region'."  That is at best misleading.  `C-M-x' eventually calls
> `eval-region', but a user would not guess that the doc string applies
> also to `C-M-x'.  It would perhaps be better to characterize the
> situations where it does _not_ apply to code evaluation.

True.  But I've, at least, changed the doc text to clarify that it
doesn't "only" apply to these functions.

> It is also misleading in that it is sufficient to visit a file, such as
> `minibuffer.el', that has "-*- lexical-binding: t -*-" in its first
> line, for the value to be non-nil and thus affect pretty much anything
> you do in that buffer.

The doc string says:

This variable is automatically set from the file variables of an
interpreted Lisp file read using `load'.

Do you have a suggestion as to how to clarify this?

-- 
(domestic pets only, the antidote for overdose, milk.)
  bloggy blog http://lars.ingebrigtsen.no/

bug#8460: 24.0.50; Doc string of `lexical-binding'

[Drew Adams]

> > It says that it "only applies to code evaluated by `eval-buffer' and
> > `eval-region'."  That is at best misleading.  `C-M-x' 
> > eventually calls `eval-region', but a user would not guess that the
> > doc string applies also to `C-M-x'.  It would perhaps be better to
> > characterize the situations where it does _not_ apply to code
> > evaluation.
> 
> True.  But I've, at least, changed the doc text to clarify that it
> doesn't "only" apply to these functions.

Good.

But it needs to somehow characterize what contexts it applies to and what it
does not apply to (when it has an effect or does not).

I haven't seen your fix, but it could be misleading to just mention `eval-*'
even if you remove "only".

> > It is also misleading in that it is sufficient to visit a 
> > file, such as `minibuffer.el', that has "-*- lexical-binding: t -*-"
> > in its first line, for the value to be non-nil and thus affect pretty 
> > much anything you do in that buffer.
> 
> The doc string says:
> 
> This variable is automatically set from the file variables of an
> interpreted Lisp file read using `load'.
> 
> Do you have a suggestion as to how to clarify this?

I think the problem was that sentence coming after the "only" statement.  The
impression was that it might well be set from file variables but it still "only
applies..." etc.

The end result needs to somehow characterize when it does and does not apply.

bug#8460: 24.0.50; Doc string of `lexical-binding'

[Lars Magne Ingebrigtsen]

"Drew Adams" <drew.adams@oracle.com> writes:

> 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.

-- 
(domestic pets only, the antidote for overdose, milk.)
  bloggy blog http://lars.ingebrigtsen.no/

bug#8460: 24.0.50; Doc string of `lexical-binding'

[Drew Adams]

> > 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?

bug#8460: 24.0.50; Doc string of `lexical-binding'

[Stefan Monnier]

> 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."

We could indeed.  Tho I think a better docstring could be:

   Non-nil means that the code in the current buffer should be evaluated
   with lexical binding.


-- Stefan

bug#8460: 24.0.50; Doc string of `lexical-binding'

[Drew Adams]

> I think a better docstring could be:
>    Non-nil means that the code in the current buffer should 
>    be evaluated with lexical binding.

Agreed.

bug#8460: 24.0.50; Doc string of `lexical-binding'

[Lars Magne Ingebrigtsen]

Stefan Monnier <monnier@iro.umontreal.ca> writes:

> We could indeed.  Tho I think a better docstring could be:
>
>    Non-nil means that the code in the current buffer should be evaluated
>    with lexical binding.

I've now changed the doc string and added this.

-- 
(domestic pets only, the antidote for overdose, milk.)
  bloggy blog http://lars.ingebrigtsen.no/