Subject: 30.0.91; mention special variables in lexbind Info page
From: Mike Kupfer <[email-masked]>
To: [email-masked]
Date: Mon, 25 Nov 2024 16:52:05 -0800
List-Id: <debbugs-submit.debbugs.gnu.org>

When I first read up on lexical binding, I didn't realize that I also
needed to review the documentation for dynamic binding, so that I
could learn about special variables.  I think it would be good for the
Info page for lexical binding to mention special variables, clarify
that the specialness also affects new bindings (not just the initial
defvar/defcustom/defconst), and provide a link to the page for dynamic
binding (for details about special variables).

I've enclosed a draft patch for your consideration.

thanks,
mike

user:        Mike Kupfer <[email-masked]>
date:        Mon Nov 25 15:37:53 2024 -0800
files:       doc/lispref/variables.texi
description:
Mention special variables in lexical binding documentation

* doc/lispref/variables.texi (Lexical Binding): Briefly mention
special variables and their semantics.

diff --git a/doc/lispref/variables.texi b/doc/lispref/variables.texi
--- a/doc/lispref/variables.texi
+++ b/doc/lispref/variables.texi
@@ -1096,7 +1096,7 @@
 @end example
 
 @noindent
-The @code{let} binding defines a lexical environment in which the
+Here, the @code{let} binding defines a lexical environment in which the
 variable @code{x} is locally bound to 0.  Within this binding
 construct, we define a lambda expression which increments @code{x} by
 one and returns the incremented value.  This lambda expression is
@@ -1113,6 +1113,12 @@
 variable's dynamic binding (i.e., the contents of its symbol's value
 cell).
 
+  Note also that variables may be declared special, in which case they
+will use dynamic binding, even for new bindings such as a @code{let}
+binding.  Depending on how the variable is declared, it can be
+special globally, for a single file, or for a portion of a file.
+@xref{Dynamic Binding} for details.
+
 @node Dynamic Binding
 @subsection Dynamic Binding