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

[Jim Porter]

On 10/26/2023 12:09 AM, Eli Zaretskii wrote:
> Thanks.
>
> The challenge in updating the Lisp Introduction manual is to try to
> keep its informal and reader-friendly style as much as possible.  It
> is not just another ELisp Reference manual!  So please try to keep
> that in mind when you write the text, and in particular try not to
> modify the existing text that is still accurate -- it was written by a
> master, and each word there counts, even if it looks at first sight as
> not important.

Ok, here's a second attempt. I've tried to avoid changing anything that 
I don't think is truly necessary. I did alter a bit of the original 
wording to emphasize that under lexical binding, 'let' isn't about time, 
but about place. For example, that's why I changed this:

> This is like understanding that whenever your host refers to ``the house'', he 
> means his house, not yours.

to this:

> This is like understanding that in your host's home, whenever he refers to 
> ``the house'', he means his house, not yours.

My previous concern about the "lexical binding" digression still applies 
though. However, I'm not sure how to get around that at present; if we 
want to talk about lexical binding in the manual, we need to get users 
to enable it, so I think it's unavoidable that we at least mention it. I 
tried to introduce the jargon as gently as I could (by first introducing 
the term "binding" on its own before mentioning "lexical/dynamic 
binding"), but it's still a bit intimidating. On the positive side, when 
lexical binding is the default, we could remove that entire digression.

There's also an argument that the example I added is in the wrong spot, 
since we haven't actually introduced the 'let' syntax yet. However, I 
personally find the example to be pretty useful since it shows off one 
of the key differences between lexical and dynamic binding, and helps 
show one of the boundaries of the 'let' form's scope. I myself tend to 
learn best by seeing examples of that sort. Fixing the order so we 
introduce the syntax first would require more extensive changes to this 
section...

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