GNU bug report logs - #8460
24.0.50; Doc string of `lexical-binding'

Previous Next

To add a comment to this bug, you must first unarchive it, by sending
a message to control AT debbugs.gnu.org, with unarchive 8460 in the body.
You can then email your comments to 8460 AT debbugs.gnu.org in the normal way.

Toggle the display of automated, internal messages from the tracker.

Message #5 received at submit <at> debbugs.gnu.org (full text, mbox):

From: "Drew Adams" <drew.adams <at> oracle.com>
To: <bug-gnu-emacs <at> gnu.org>
Subject: 24.0.50; Doc string of `lexical-binding'
Date: Sat, 9 Apr 2011 11:06:28 -0700

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'
 

Message #8 received at 8460 <at> debbugs.gnu.org (full text, mbox):

From: Lars Magne Ingebrigtsen <larsi <at> gnus.org>
To: "Drew Adams" <drew.adams <at> oracle.com>
Cc: 8460 <at> debbugs.gnu.org
Subject: Re: 24.0.50; Doc string of `lexical-binding'
Date: Fri, 15 Jul 2011 14:59:01 +0200

"Drew Adams" <drew.adams <at> 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/

Message #11 received at 8460 <at> debbugs.gnu.org (full text, mbox):

From: "Drew Adams" <drew.adams <at> oracle.com>
To: "'Lars Magne Ingebrigtsen'" <larsi <at> gnus.org>
Cc: 8460 <at> debbugs.gnu.org
Subject: RE: 24.0.50; Doc string of `lexical-binding'
Date: Fri, 15 Jul 2011 07:01:10 -0700

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

Message #14 received at 8460 <at> debbugs.gnu.org (full text, mbox):

From: Lars Magne Ingebrigtsen <larsi <at> gnus.org>
To: "Drew Adams" <drew.adams <at> oracle.com>
Cc: 8460 <at> debbugs.gnu.org
Subject: Re: 24.0.50; Doc string of `lexical-binding'
Date: Fri, 15 Jul 2011 16:09:32 +0200

"Drew Adams" <drew.adams <at> 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/

Message #17 received at 8460 <at> debbugs.gnu.org (full text, mbox):

From: "Drew Adams" <drew.adams <at> oracle.com>
To: "'Lars Magne Ingebrigtsen'" <larsi <at> gnus.org>
Cc: 8460 <at> debbugs.gnu.org
Subject: RE: 24.0.50; Doc string of `lexical-binding'
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?

Message #20 received at 8460 <at> debbugs.gnu.org (full text, mbox):

From: Stefan Monnier <monnier <at> iro.umontreal.ca>
To: "Drew Adams" <drew.adams <at> oracle.com>
Cc: 8460 <at> debbugs.gnu.org, 'Lars Magne Ingebrigtsen' <larsi <at> gnus.org>
Subject: Re: bug#8460: 24.0.50; Doc string of `lexical-binding'
Date: Mon, 18 Jul 2011 09:38:01 -0400

> 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

Message #23 received at 8460 <at> debbugs.gnu.org (full text, mbox):

From: "Drew Adams" <drew.adams <at> oracle.com>
To: "'Stefan Monnier'" <monnier <at> iro.umontreal.ca>
Cc: 8460 <at> debbugs.gnu.org, 'Lars Magne Ingebrigtsen' <larsi <at> gnus.org>
Subject: RE: bug#8460: 24.0.50; Doc string of `lexical-binding'
Date: Mon, 18 Jul 2011 06:45:55 -0700

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

Agreed.

Message #30 received at 8460 <at> debbugs.gnu.org (full text, mbox):

From: Lars Magne Ingebrigtsen <larsi <at> gnus.org>
To: Stefan Monnier <monnier <at> iro.umontreal.ca>
Cc: 8460 <at> debbugs.gnu.org, Drew Adams <drew.adams <at> oracle.com>
Subject: Re: bug#8460: 24.0.50; Doc string of `lexical-binding'
Date: Tue, 19 Jul 2011 17:18:00 +0200

Stefan Monnier <monnier <at> 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/

Previous Next

GNU bug tracking system
Copyright (C) 1999 Darren O. Benham, 1997,2003 nCipher Corporation Ltd, 1994-97 Ian Jackson.