master cc2c150: Document `dlet'

[Lars Ingebrigtsen]

branch: master
commit cc2c150636e63aba4cd6f3c3d63a38072dd63018
Author: Lars Ingebrigtsen <larsi@gnus.org>
Commit: Lars Ingebrigtsen <larsi@gnus.org>

    Document `dlet'
    
    * doc/lispref/variables.texi (Local Variables): Document `dlet'.
---
 doc/lispref/variables.texi | 14 ++++++++++++++
 etc/NEWS                   |  2 ++
 2 files changed, 16 insertions(+)

diff --git a/doc/lispref/variables.texi b/doc/lispref/variables.texi
index 9356fb9..8a11154 100644
--- a/doc/lispref/variables.texi
+++ b/doc/lispref/variables.texi
@@ -286,6 +286,20 @@ being run once:
 @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
 bindings:
 
diff --git a/etc/NEWS b/etc/NEWS
index 1866ed0..80185a5 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.