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

[Jim Porter]

On 12/3/2023 7:08 PM, Richard Stallman wrote:
> [[[ To any NSA and FBI agents reading my email: please consider    ]]]
> [[[ whether defending the US Constitution against all enemies,     ]]]
> [[[ foreign or domestic, requires you to follow Snowden's example. ]]]
>
>    > +means his house, not yours.  (Symbols used in argument lists work the
>    > +same way.
>
> Maybe that sentence should be more explicit about which symbols it
> refers to and which aspect of "working".  Perhaps like this:
>
>     (The symbols used to name function arguments are bound as local variables
>     in exactly the same way.)

Makes sense to me. Done.

> This statement
>
>        However, outside
>      +of the @code{let} body (such as when calling a function that was
>      +defined elsewhere), calling @code{setq} for a variable named by the
>      +@code{let} expression will @emph{not} affect that local variable.
>
> is true only in lexical binding.  With dynamic binding, such a setq
> _will_ set the let's local variable (in the simplest cases).

Correct. Based on Eli's suggestions, I've worded this initial section to 
assume that lexical binding is in effect. I put a footnote here to 
mention this, but otherwise I'm trying my hardest to avoid front-loading 
the 'let' documentation with an explanation of lexical binding.

>      +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 validscop.
>
> Typo there.

Thanks. I think that was a mistake from when I was searching for "scope" 
to ensure I didn't inadvertently use the term in this section. (I wanted 
to avoid mentioning another CS term here, and I think "binding" is 
enough for what we want to say.)

>      +As we discussed before, when you create local variables with
>      +@code{let} under lexical binding, those variables are valid only
>      +within the body of the @code{let} expression.
>
> Where is this previous discussion?  I don't see it.  The distinction
> of dynamic vs lexical was first introduced two paragraphs above,
> and its effects on binding have not been discussed yet.
>
> Is this a reference to the following?
>
>        However, outside
>      +of the @code{let} body (such as when calling a function that was
>      +defined elsewhere), calling @code{setq} for a variable named by the
>      +@code{let} expression will @emph{not} affect that local variable.
>
> That may be meant as a discussion of local binding with lexical scoping,
> but it isn't one, since it doesn't say "lexical scoping."

Correct. I added a cross-reference back to that section. With that and 
the footnote in the "let Prevents Confusion" section, hopefully this is 
clearer now.

>        (On the other hand, if
>      +you call a function defined within a @code{let} body,
>
> I recommend "that was defined within"; it is more clear.

Done.

>      +Under dynamic binding, the rules are different: instead, when you use
>      +@code{let}, the local variables you've created are valid during
>      +execution of the let expression.
>
> @code needed here.

Fixed.

>        When you bind a variable
>      +with @code{let}, it puts the new binding you've specified on the top
>      +of the stack,
>
> For clarity, I suggest "bind a variable dynamically" or something to reiterate
> that this sentence is only about dynamic binding.  Without that, the reader
> could take it to be independent of which mode is currently selected.

Done.

On 12/3/2023 7:08 PM, Richard Stallman wrote:
> The new node How let Binds Variables is 110 lines long.  Such a long
> node is cumbersome, especially for cross-references to it.
>
> Can you find a way to subdivide it into smaller nodes?
>
> It could have some text at the beginning, then a few subnodes.

I've split this into a main section and two subnodes: one describing how 
lexical and dynamic binding work, and one showing an example of how they 
behave differently in practice. Maybe the titles could be improved, but 
they're the best I could come up with at the time...

0001-Introduce-let-using-lexical-binding-in-the-Lisp-Intr.patch
Description: Text document