bug#66756: 30.0.50; [PATCH] Improve discussion of 'let' in Elisp Introduction manual

[Jim Porter <jporterbugs@gmail.com>]

[-- Attachment #1: Type: text/plain, Size: 1544 bytes --]

On 11/18/2023 7:39 PM, Richard Stallman wrote:
>    > +parts a ``scope'').  For historical reasons, Emacs Lisp uses a form of
>    > +variable binding called ``dynamic binding'' by default.  However, in
>    > +this manual, we discuss the preferred form of binding, called
>    > +``lexical binding'' (if you have programmed in other languages before,
>    > +you're likely already familiar with how lexical binding behaves).  In
>    > +order to use lexical binding in a program, you should add this to the
>    > +first line of your Emacs Lisp file:
>    > +
>    > +@example
>    > +;;; -*- lexical-binding: t -*-
>    > +@end example
>    > +
>    > +For more information about this, @pxref{Selecting Lisp Dialect, , ,
>    > +elisp, The Emacs Lisp Reference Manual}.
> 
> Do we want to change the default some day to lexical binding:?  If so,
> we should say so somewhere in this manual -- perhaps here, perhaps
> elsewhere,

I believe that's the goal, yes. I've added a note that the maintainers 
eventually plan on making lexical binding the default.

>    > +If we instead change @code{lexical-binding} to have a value of
>    > +@code{nil}, we will get a different result here.
> 
> "Get a different result" is vague -- it would be clearer if it said
> concretely what will happen.
> 
> I suggest you show the dynamci situation in the same way you show the lexical
> situation.  That will help people compare the two.

Done. I've also expanded the prose explanation at the end in order to 
re-emphasize the differences between the two.

[-- Attachment #2: 0001-Introduce-let-using-lexical-binding-in-the-Lisp-Intr.patch --]
[-- Type: text/plain, Size: 6590 bytes --]

From f805ebf65dc218c7ae63251a357a4deaaf45d752 Mon Sep 17 00:00:00 2001
From: Jim Porter <jporterbugs@gmail.com>
Date: Wed, 25 Oct 2023 20:43:57 -0700
Subject: [PATCH] Introduce 'let' using lexical binding in the Lisp
 Introduction

Bug#66756.

* doc/lispintro/emacs-lisp-intro.texi (Prevent confusion): Rework the
explanation to discuss how things work under lexical binding.
(How let Binds Variables): Describe the differences between lexical
and dynamic binding (including how to configure it).
---
 doc/lispintro/emacs-lisp-intro.texi | 115 ++++++++++++++++++++++++----
 1 file changed, 98 insertions(+), 17 deletions(-)

diff --git a/doc/lispintro/emacs-lisp-intro.texi b/doc/lispintro/emacs-lisp-intro.texi
index c5b33ac5eaa..554ba4a7560 100644
--- a/doc/lispintro/emacs-lisp-intro.texi
+++ b/doc/lispintro/emacs-lisp-intro.texi
@@ -3591,6 +3591,7 @@ let
 * Parts of let Expression::
 * Sample let Expression::
 * Uninitialized let Variables::
+* How let Binds Variables::
 @end menu
 
 @ifnottex
@@ -3601,25 +3602,22 @@ Prevent confusion
 @cindex @samp{local variable} defined
 @cindex @samp{variable, local}, defined
 The @code{let} special form prevents confusion.  @code{let} creates a
-name for a @dfn{local variable} that overshadows any use of the same
-name outside the @code{let} expression.  This is like understanding
-that whenever your host refers to ``the house'', he means his house, not
-yours.  (Symbols used in argument lists work the same way.
+name for a @dfn{local variable} that overrides any use of the same
+name outside the @code{let} expression (in computer science jargon, we
+call this ``binding'' the variable).  This is like understanding that
+in your host's home, whenever he refers to ``the house'', he means his
+house, not yours.  (Symbols used in argument lists work the same way.
 @xref{defun, , The @code{defun} Macro}.)
 
-Local variables created by a @code{let} expression retain their value
-@emph{only} within the @code{let} expression itself (and within
-expressions called within the @code{let} expression); the local
-variables have no effect outside the @code{let} expression.
-
-Another way to think about @code{let} is that it is like a @code{setq}
-that is temporary and local.  The values set by @code{let} are
-automatically undone when the @code{let} is finished.  The setting
-only affects expressions that are inside the bounds of the @code{let}
-expression.  In computer science jargon, we would say the binding of
-a symbol is visible only in functions called in the @code{let} form;
-in Emacs Lisp, the default scoping is dynamic, not lexical.  (The
-non-default lexical binding is not discussed in this manual.)
+Another way to think about @code{let} is that it defines a place in
+your code where the variables you named have their own local meaning.
+Outside of the @code{let} body, they have another meaning (or they may
+not be defined at all).  This means that inside the @code{let} body,
+calling @code{setq} for a variable named by the @code{let} expression
+will set the value of the @emph{local} variable of that name.  This
+also means that outside of the @code{let} body, calling @code{setq}
+for a variable named by the @code{let} expression will @emph{not}
+affect that local variable.
 
 @code{let} can create more than one variable at once.  Also,
 @code{let} gives each variable it creates an initial value, either a
@@ -3779,6 +3777,89 @@ Uninitialized let Variables
 @samp{%s}.)  The four variables as a group are put into a list to
 delimit them from the body of the @code{let}.
 
+@node How let Binds Variables
+@subsection How @code{let} Binds Variables
+@cindex Lexical binding
+@cindex Binding, lexical
+@cindex Dynamic binding
+@cindex Binding, dynamic
+
+Emacs Lisp supports two different ways of binding variable names to
+their values.  These ways affect the parts of your program where a
+particular binding is valid (in computer science jargon, we call these
+parts a ``scope'').  For historical reasons, Emacs Lisp uses a form of
+variable binding called ``dynamic binding'' by default.  However, in
+this manual, we primarily discuss the preferred form of binding,
+called ``lexical binding'' unless otherwise noted (in the future, the
+Emacs maintainers plan to change the default to lexical binding).  If
+you have programmed in other languages before, you're likely already
+familiar with how lexical binding behaves.
+
+In order to use lexical binding in a program, you should add this to
+the first line of your Emacs Lisp file:
+
+@example
+;;; -*- lexical-binding: t -*-
+@end example
+
+For more information about this, @pxref{Selecting Lisp Dialect, , ,
+elisp, The Emacs Lisp Reference Manual}.
+
+As we discussed before, under lexical binding, @code{let} defines a
+@emph{place} in your code where the variables have their own local
+meaning.  Under dynamic binding, the rules are different: instead, you
+are defining a @emph{time} in your code when the variables have their
+own local meaning.
+
+Another way to think about @code{let} when using dynamic binding is
+that it is like a @code{setq} that is temporary and local.  The values
+set by @code{let} are automatically undone when the @code{let} is
+finished.  The setting only affects expressions that are inside the
+bounds of the @code{let} expression.
+
+In some cases, both lexical and dynamic binding behave identically.
+However, in other cases, they can change the meaning of your program.
+For example, under lexical binding, if you call a function inside of a
+@code{let} body, that function's body would be unable to ``see'' (or
+modify) the value of a local variable from the @code{let} expression:
+
+@example
+;;; -*- lexical-binding: t -*-
+
+(setq x 1)
+
+(defun getx ()
+  x)
+
+(let ((x 2))
+  (getx))
+     @result{} 1
+@end example
+
+@noindent
+If we use dynamic binding instead, the behavior is different:
+
+@example
+;;; -*- lexical-binding: nil -*-
+
+(setq x 1)
+
+(defun getx ()
+  x)
+
+(let ((x 2))
+  (getx))
+     @result{} 2
+@end example
+
+Now, the result of @samp{(getx)} is @samp{2}!  That's because under
+dynamic binding, when @code{getx} looks for the value of @code{x}, it
+sees the value we set in our @code{let} expression.  In other words,
+the call to @code{getx} happens during the @emph{time} when our
+@code{let} expression is active.  Under lexical binding, @code{getx}
+doesn't see the value from our @code{let} expression.  That's because
+it happens in a different @emph{place} than the @code{let} body.
+
 @node if
 @section The @code{if} Special Form
 @findex if
-- 
2.25.1