From c04ac8a3191820d37e7858b7ca4e31cf04808cc3 Mon Sep 17 00:00:00 2001
From: Philipp Stephani
Date: Fri, 23 Dec 2016 13:14:55 +0100
Subject: Document that variable binding order is unspecified

* doc/lispref/variables.texi (Local Variables):
* cl.texi (Modify Macros): Document that binding order in 'let' and
'cl-letf' is unspecified.
---
 doc/lispref/variables.texi | 12 ++++++++++++
 1 file changed, 12 insertions(+)

(limited to 'doc/lispref')

diff --git a/doc/lispref/variables.texi b/doc/lispref/variables.texi
index a2d64815d94..ba31f856369 100644
--- a/doc/lispref/variables.texi
+++ b/doc/lispref/variables.texi
@@ -221,6 +221,18 @@ Here is an example of this: @code{z} is bound to the old value of
      @result{} (1 2)
 @end group
 @end example
+
+On the other hand, the order of @emph{bindings} is unspecified: in the
+following example, either 1 or 2 might be printed.
+
+@example
+(let ((x 1)
+      (x 2))
+  (print x))
+@end example
+
+Therefore, avoid binding a variable more than once in a single
+@code{let} form.
 @end defspec
 
 @defspec let* (bindings@dots{}) forms@dots{}
-- 
cgit v1.2.1


From d7973e808d54f1adf5224589c5cf770bb17453d2 Mon Sep 17 00:00:00 2001
From: Eli Zaretskii
Date: Mon, 26 Dec 2016 19:10:49 +0200
Subject: Document 'default-toplevel-value' and 'set-default-toplevel-value'

* doc/lispref/variables.texi (Default Value): Document
'default-toplevel-value' and 'set-default-toplevel-value'.
---
 doc/lispref/variables.texi | 38 ++++++++++++++++++++++++++++++++++++++
 1 file changed, 38 insertions(+)

(limited to 'doc/lispref')

diff --git a/doc/lispref/variables.texi b/doc/lispref/variables.texi
index ba31f856369..e231cbdfec1 100644
--- a/doc/lispref/variables.texi
+++ b/doc/lispref/variables.texi
@@ -1580,6 +1580,44 @@ an ordinary evaluated argument.
 @end example
 @end defun
 
+  A variable can be let-bound (@pxref{Local Variables}) to a
+non-default value; in that case, @code{default-value} will return the
+value from that binding, not the global value, and @code{set-default}
+will be prevented from setting the global value.  The following two
+functions allow to reference the global value even if it's masked by a
+let-binding.
+
+@cindex top-level default value
+@defun default-toplevel-value symbol
+This function returns the @dfn{top-level} default value of
+@var{symbol}, which is its value outside of any let-binding.
+@end defun
+
+@example
+@group
+(defvar variable 'global-value)
+    @result{} variable
+@end group
+@group
+(let ((variable 'let-binding))
+  (default-value 'variable))
+    @result{} let-binding
+@end group
+@group
+(let ((variable 'let-binding))
+  (default-toplevel-value 'variable))
+    @result{} global-value
+@end group
+@end example
+
+@defun set-default-toplevel-value symbol value
+This function sets the top-level default value of @var{symbol} to the
+specified @var{value}.  This comes in handy when you want to set the
+global value of @var{symbol} regardless of whether your code runs in
+the context of @var{symbol}'s let-binding.
+@end defun
+
+
 @node File Local Variables
 @section File Local Variables
 @cindex file local variables
-- 
cgit v1.2.1


From 697167b5432a89db009238cf5cbddc61e69ad339 Mon Sep 17 00:00:00 2001
From: Eli Zaretskii
Date: Tue, 27 Dec 2016 09:10:30 +0200
Subject: ; Improve wording of previous change in variables.texi

* doc/lispref/variables.texi (Default Value): Improve wording of
last change.
---
 doc/lispref/variables.texi | 13 +++++++------
 1 file changed, 7 insertions(+), 6 deletions(-)

(limited to 'doc/lispref')

diff --git a/doc/lispref/variables.texi b/doc/lispref/variables.texi
index e231cbdfec1..887643196cc 100644
--- a/doc/lispref/variables.texi
+++ b/doc/lispref/variables.texi
@@ -1580,12 +1580,13 @@ an ordinary evaluated argument.
 @end example
 @end defun
 
-  A variable can be let-bound (@pxref{Local Variables}) to a
-non-default value; in that case, @code{default-value} will return the
-value from that binding, not the global value, and @code{set-default}
-will be prevented from setting the global value.  The following two
-functions allow to reference the global value even if it's masked by a
-let-binding.
+  A variable can be let-bound (@pxref{Local Variables}) to a value.
+This makes its global value shadowed by the binding;
+@code{default-value} will then return the value from that binding, not
+the global value, and @code{set-default} will be prevented from
+setting the global value (it will change the let-bound value instead).
+The following two functions allow to reference the global value even
+if it's shadowed by a let-binding.
 
 @cindex top-level default value
 @defun default-toplevel-value symbol
-- 
cgit v1.2.1