bug#62840: 30.0.50; Doc bug: obsolete paragraph in Elisp Ref

bug#62840: 30.0.50; Doc bug: obsolete paragraph in Elisp Ref

[Nick Dokos]

---------------------------------------------------------------------------
Emacs Lisp Reference manual, Chapter "Variables", Section "Lexical
Binding" says:

--8<---------------cut here---------------start------------->8---
...
   (Internally, the lexical environment is an alist of symbol-value
pairs, with the final element in the alist being the symbol ‘t’ rather
than a cons cell.  Such an alist can be passed as the second argument to
the ‘eval’ function, in order to specify a lexical environment in which
to evaluate a form.  *Note Eval::.  Most Emacs Lisp programs, however,
should not interact directly with lexical environments in this way; only
specialized programs like debuggers.)

...
--8<---------------cut here---------------end--------------->8---

I don't know if the structure of the lexical environment was ever really
relevant: it seems to be an internal detail that should not have found
its way into the documentation in the first place, but that's guessing
on my part.

The important thing is that it does not seem to be the case any longer:
the `t' is present at the end of the lexical environment in Emacs 28.2:

    (let ((foo 233)) (lambda (x) (* x foo))) ==> (closure ((foo . 233) t) (x) (* x foo))

but it is no longer present in current upstream:

    (let ((foo 233)) (lambda (x) (* x foo))) ==> (closure ((foo . 233)) (x) (* x foo))

so the above paragraph needs modification (if not outright excision).

-- 
Nick

bug#62840: 30.0.50; Doc bug: obsolete paragraph in Elisp Ref

[Eli Zaretskii]

> From: Nick Dokos <ndokos@gmail.com>
> Date: Fri, 14 Apr 2023 13:48:59 -0400
> 
> 
> ---------------------------------------------------------------------------
> Emacs Lisp Reference manual, Chapter "Variables", Section "Lexical
> Binding" says:
> 
> --8<---------------cut here---------------start------------->8---
> ...
>    (Internally, the lexical environment is an alist of symbol-value
> pairs, with the final element in the alist being the symbol ‘t’ rather
> than a cons cell.  Such an alist can be passed as the second argument to
> the ‘eval’ function, in order to specify a lexical environment in which
> to evaluate a form.  *Note Eval::.  Most Emacs Lisp programs, however,
> should not interact directly with lexical environments in this way; only
> specialized programs like debuggers.)
> 
> ...
> --8<---------------cut here---------------end--------------->8---
> 
> I don't know if the structure of the lexical environment was ever really
> relevant: it seems to be an internal detail that should not have found
> its way into the documentation in the first place, but that's guessing
> on my part.
> 
> The important thing is that it does not seem to be the case any longer:
> the `t' is present at the end of the lexical environment in Emacs 28.2:
> 
>     (let ((foo 233)) (lambda (x) (* x foo))) ==> (closure ((foo . 233) t) (x) (* x foo))
> 
> but it is no longer present in current upstream:
> 
>     (let ((foo 233)) (lambda (x) (* x foo))) ==> (closure ((foo . 233)) (x) (* x foo))
> 
> so the above paragraph needs modification (if not outright excision).

Stefan, any comments?  Should this text be amended, deleted, or
something else?

bug#62840: 30.0.50; Doc bug: obsolete paragraph in Elisp Ref

[Stefan Monnier via Bug reports for GNU Emacs, the Swiss army knife of text editors]

>> I don't know if the structure of the lexical environment was ever really
>> relevant: it seems to be an internal detail that should not have found
>> its way into the documentation in the first place, but that's guessing
>> on my part.
>> 
>> The important thing is that it does not seem to be the case any longer:
>> the `t' is present at the end of the lexical environment in Emacs 28.2:
>> 
>>     (let ((foo 233)) (lambda (x) (* x foo))) ==> (closure ((foo . 233) t) (x) (* x foo))
>> 
>> but it is no longer present in current upstream:
>> 
>>     (let ((foo 233)) (lambda (x) (* x foo))) ==> (closure ((foo . 233)) (x) (* x foo))
>> 
>> so the above paragraph needs modification (if not outright excision).
>
> Stefan, any comments?  Should this text be amended, deleted, or
> something else?

Indeed the "with a `t` at the end" should probably not have been
documented and can be removed.  The `t` can still appear there
(sometimes it does sometimes it doesn't).  More important would be to
document that beside (SYM . VAL) pairs, the env can contain symbols,
which means that the lexical environment declared that variable as being
locally considered as a dynbind variable.

E.g. in

    (defun my-fun (baz)
      (defvar my-foo)
      (lambda (x) (let ((my-foo x)) (bar baz))))

`my-foo` will appear in the environment of the closure returned by the
function so as to remember the `defvar` since it affects the execution
of the body.


        Stefan

bug#62840: 30.0.50; Doc bug: obsolete paragraph in Elisp Ref

[Eli Zaretskii]

> From: Stefan Monnier <monnier@iro.umontreal.ca>
> Cc: Nick Dokos <ndokos@gmail.com>,  62840@debbugs.gnu.org
> Date: Sat, 15 Apr 2023 09:11:37 -0400
> 
> Indeed the "with a `t` at the end" should probably not have been
> documented and can be removed.  The `t` can still appear there
> (sometimes it does sometimes it doesn't).  More important would be to
> document that beside (SYM . VAL) pairs, the env can contain symbols,
> which means that the lexical environment declared that variable as being
> locally considered as a dynbind variable.
> 
> E.g. in
> 
>     (defun my-fun (baz)
>       (defvar my-foo)
>       (lambda (x) (let ((my-foo x)) (bar baz))))
> 
> `my-foo` will appear in the environment of the closure returned by the
> function so as to remember the `defvar` since it affects the execution
> of the body.

Thanks, fixed on the emacs-29 branch, and closing the bug.