[Emacs-diffs] emacs-25 d7973e8: Document 'default-toplevel-value' and 'set-default-toplevel-value'

[Eli Zaretskii]

branch: emacs-25
commit d7973e808d54f1adf5224589c5cf770bb17453d2
Author: Eli Zaretskii <address@hidden>
Commit: Eli Zaretskii <address@hidden>

    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(+)

diff --git a/doc/lispref/variables.texi b/doc/lispref/variables.texi
index ba31f85..e231cbd 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.
+
address@hidden top-level default value
address@hidden default-toplevel-value symbol
+This function returns the @dfn{top-level} default value of
address@hidden, which is its value outside of any let-binding.
address@hidden defun
+
address@hidden
address@hidden
+(defvar variable 'global-value)
+    @result{} variable
address@hidden group
address@hidden
+(let ((variable 'let-binding))
+  (default-value 'variable))
+    @result{} let-binding
address@hidden group
address@hidden
+(let ((variable 'let-binding))
+  (default-toplevel-value 'variable))
+    @result{} global-value
address@hidden group
address@hidden example
+
address@hidden 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.
address@hidden defun
+
+
 @node File Local Variables
 @section File Local Variables
 @cindex file local variables