From mboxrd@z Thu Jan  1 00:00:00 1970
Path: news.gmane.io!.POSTED.blaine.gmane.org!not-for-mail
From: Richard Stallman <rms@gnu.org>
Newsgroups: gmane.emacs.bugs
Subject: bug#66756: 30.0.50;
 [PATCH] Improve discussion of 'let' in Elisp Introduction manual
Date: Sun, 03 Dec 2023 22:08:37 -0500
Message-ID: <E1r9zK1-0003MB-PT@fencepost.gnu.org>
References: <a9812c1d-71e4-5f3f-83a4-a2923e649f3a@gmail.com>
 <a5120e2f-b008-1b74-1ad9-3fe7d861b13c@gmail.com>
 <E1qx8nq-0007DY-HV@fencepost.gnu.org>
 <3ade119d-0f0d-e60e-1bdc-9c7e02c1559c@gmail.com>
 <E1r4YeF-0001fe-Ex@fencepost.gnu.org>
 <381836df-c16f-b3e7-d0c4-473290e165de@gmail.com>
 <f44cca7f-13bb-a41a-c9ce-55f1b736c52b@gmail.com>
 <E1r5zuY-00041H-Bl@fencepost.gnu.org>
 <9239b6bd-b476-b6c1-aef9-245e439aee42@gmail.com> <83jzq7fx5o.fsf@gnu.org>
 <64d90b0b-e003-7bc3-5312-6c7ab4c4591f@gmail.com> <838r6nfkfj.fsf@gnu.org>
 <fb691578-f89f-d0d1-aab0-7e9e4236bab1@gmail.com> <83jzq6e0dn.fsf@gnu.org>
 <0fe9fc29-11d5-2983-8970-3f4b7969df2d@gmail.com>
Reply-To: rms@gnu.org
Content-Type: text/plain; charset=Utf-8
Injection-Info: ciao.gmane.io; posting-host="blaine.gmane.org:116.202.254.214";
	logging-data="6639"; mail-complaints-to="usenet@ciao.gmane.io"
Cc: eliz@gnu.org, 66756@debbugs.gnu.org
To: Jim Porter <jporterbugs@gmail.com>
Original-X-From: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane-mx.org@gnu.org Mon Dec 04 04:09:16 2023
Return-path: <bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane-mx.org@gnu.org>
Envelope-to: geb-bug-gnu-emacs@m.gmane-mx.org
Original-Received: from lists.gnu.org ([209.51.188.17])
	by ciao.gmane.io with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256)
	(Exim 4.92)
	(envelope-from <bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane-mx.org@gnu.org>)
	id 1r9zKe-0001Yg-Mc
	for geb-bug-gnu-emacs@m.gmane-mx.org; Mon, 04 Dec 2023 04:09:16 +0100
Original-Received: from localhost ([::1] helo=lists1p.gnu.org)
	by lists.gnu.org with esmtp (Exim 4.90_1)
	(envelope-from <bug-gnu-emacs-bounces@gnu.org>)
	id 1r9zKI-0003aD-G3; Sun, 03 Dec 2023 22:08:54 -0500
Original-Received: from eggs.gnu.org ([2001:470:142:3::10])
 by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256)
 (Exim 4.90_1) (envelope-from <Debian-debbugs@debbugs.gnu.org>)
 id 1r9zKG-0003Zn-P8
 for bug-gnu-emacs@gnu.org; Sun, 03 Dec 2023 22:08:52 -0500
Original-Received: from debbugs.gnu.org ([2001:470:142:5::43])
 by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_128_GCM_SHA256:128)
 (Exim 4.90_1) (envelope-from <Debian-debbugs@debbugs.gnu.org>)
 id 1r9zKG-0005yI-G3
 for bug-gnu-emacs@gnu.org; Sun, 03 Dec 2023 22:08:52 -0500
Original-Received: from Debian-debbugs by debbugs.gnu.org with local (Exim 4.84_2)
 (envelope-from <Debian-debbugs@debbugs.gnu.org>) id 1r9zKQ-0003cH-4K
 for bug-gnu-emacs@gnu.org; Sun, 03 Dec 2023 22:09:02 -0500
X-Loop: help-debbugs@gnu.org
Resent-From: Richard Stallman <rms@gnu.org>
Original-Sender: "Debbugs-submit" <debbugs-submit-bounces@debbugs.gnu.org>
Resent-CC: bug-gnu-emacs@gnu.org
Resent-Date: Mon, 04 Dec 2023 03:09:02 +0000
Resent-Message-ID: <handler.66756.B66756.170165933813874@debbugs.gnu.org>
Resent-Sender: help-debbugs@gnu.org
X-GNU-PR-Message: followup 66756
X-GNU-PR-Package: emacs
X-GNU-PR-Keywords: patch
Original-Received: via spool by 66756-submit@debbugs.gnu.org id=B66756.170165933813874
 (code B ref 66756); Mon, 04 Dec 2023 03:09:02 +0000
Original-Received: (at 66756) by debbugs.gnu.org; 4 Dec 2023 03:08:58 +0000
Original-Received: from localhost ([127.0.0.1]:33218 helo=debbugs.gnu.org)
 by debbugs.gnu.org with esmtp (Exim 4.84_2)
 (envelope-from <debbugs-submit-bounces@debbugs.gnu.org>)
 id 1r9zKL-0003bi-TB
 for submit@debbugs.gnu.org; Sun, 03 Dec 2023 22:08:58 -0500
Original-Received: from eggs.gnu.org ([2001:470:142:3::10]:57780)
 by debbugs.gnu.org with esmtp (Exim 4.84_2)
 (envelope-from <rms@gnu.org>) id 1r9zKI-0003bQ-VT
 for 66756@debbugs.gnu.org; Sun, 03 Dec 2023 22:08:56 -0500
Original-Received: from fencepost.gnu.org ([2001:470:142:3::e])
 by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256)
 (Exim 4.90_1) (envelope-from <rms@gnu.org>)
 id 1r9zK2-0005x9-48; Sun, 03 Dec 2023 22:08:39 -0500
DKIM-Signature: v=1; a=rsa-sha256; q=dns/txt; c=relaxed/relaxed; d=gnu.org;
 s=fencepost-gnu-org; h=Date:References:Subject:In-Reply-To:To:From:
 mime-version; bh=TBU9lZ3rpIrZ+UmC4n1pt6YYCsbnMRvo86nzhdO8qAI=; b=mD67VNg0NS7L
 xImqtqG6E7OOO90DmJ746kiMMsN/IsjRAi/hY439P7ECMKP86hUPlHu3ZsN+OMi51ccLB/fKoZCh+
 I62efibomBZZmrPH9Xjv9g+iR0gc4wvuprjy3oHBnlgTXErJF8FNbcxPYvUzy4/S0OxXRw/7H0xUO
 mYS91EEGtLOYCiAQTWMvF//PwmCeetNe2OCjGqInJkZpDcIC1MSMs99EZHMqAwkC3vgtbvLujZcAB
 dEUgt/k7BnRb7PEdoOb+G0Sx7jTxLiwzSnAjQxIWuB8KeSFvV0MBKo5xcHLF2d+DuEzJ/GRrs0iIm
 IZBZlfcB7G32Ks7ofsRYJQ==;
Original-Received: from rms by fencepost.gnu.org with local (Exim 4.90_1)
 (envelope-from <rms@gnu.org>)
 id 1r9zK1-0003MB-PT; Sun, 03 Dec 2023 22:08:37 -0500
In-Reply-To: <0fe9fc29-11d5-2983-8970-3f4b7969df2d@gmail.com> (message from
 Jim Porter on Thu, 30 Nov 2023 13:03:52 -0800)
X-BeenThere: debbugs-submit@debbugs.gnu.org
X-Mailman-Version: 2.1.18
Precedence: list
X-BeenThere: bug-gnu-emacs@gnu.org
List-Id: "Bug reports for GNU Emacs,
 the Swiss army knife of text editors" <bug-gnu-emacs.gnu.org>
List-Unsubscribe: <https://lists.gnu.org/mailman/options/bug-gnu-emacs>,
 <mailto:bug-gnu-emacs-request@gnu.org?subject=unsubscribe>
List-Archive: <https://lists.gnu.org/archive/html/bug-gnu-emacs>
List-Post: <mailto:bug-gnu-emacs@gnu.org>
List-Help: <mailto:bug-gnu-emacs-request@gnu.org?subject=help>
List-Subscribe: <https://lists.gnu.org/mailman/listinfo/bug-gnu-emacs>,
 <mailto:bug-gnu-emacs-request@gnu.org?subject=subscribe>
Errors-To: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane-mx.org@gnu.org
Original-Sender: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane-mx.org@gnu.org
Xref: news.gmane.io gmane.emacs.bugs:275466
Archived-At: <http://permalink.gmane.org/gmane.emacs.bugs/275466>

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