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

[Richard Stallman]

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

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

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

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

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

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

      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.

-- 
Dr Richard Stallman (https://stallman.org)
Chief GNUisance of the GNU Project (https://gnu.org)
Founder, Free Software Foundation (https://fsf.org)
Internet Hall-of-Famer (https://internethalloffame.org)