From: Lars Ingebrigtsen <larsi@gnus.org>
Date: Mon, 23 Aug 2021 00:13:40 +0000 (+0200)
Subject: Document `dlet'
X-Git-Tag: emacs-28.0.90~1349
X-Git-Url: http://git.eshelyaron.com/gitweb/?a=commitdiff_plain;h=cc2c150636e63aba4cd6f3c3d63a38072dd63018;p=emacs.git

Document `dlet'

* doc/lispref/variables.texi (Local Variables): Document `dlet'.
---

diff --git a/doc/lispref/variables.texi b/doc/lispref/variables.texi
index 9356fb9f699..8a11154b730 100644
--- a/doc/lispref/variables.texi
+++ b/doc/lispref/variables.texi
@@ -284,6 +284,20 @@ being run once:
                     (remove-hook 'post-command-hook hookfun))))
   (add-hook 'post-command-hook hookfun))
 @end lisp
+@end defspec
+
+@defspec dlet (bindings@dots{}) forms@dots{}
+This special form is like @code{let}, but it binds all variables
+dynamically.  This is rarely useful---you usually want to bind normal
+variables lexically, and special variables (i.e., variables that are
+defined with @code{defvar}) dynamically, and this is what @code{let}
+does.
+
+@code{dlet} can be useful when interfacing with old code that assumes
+that certain variables are dynamically bound, but it's impractical to
+@code{defvar} these variables.  @code{dlet} will temporarily make the
+bound variables special, execute the forms, and then make the
+variables non-special again.
 @end defspec
 
   Here is a complete list of the other facilities that create local
diff --git a/etc/NEWS b/etc/NEWS
index 1866ed0d6d0..80185a5d719 100644
--- a/etc/NEWS
+++ b/etc/NEWS
@@ -3594,8 +3594,10 @@ supporting Lisp files when 'require' is unsuitable.
 ** New function 'file-modes-number-to-symbolic' to convert a numeric
 file mode specification into symbolic form.
 
++++
 ** New macro 'dlet' to dynamically bind variables.
 
+---
 ** The variable 'force-new-style-backquotes' has been removed.
 This removes the final remaining trace of old-style backquotes.