Merge from origin/emacs-25

697167b ; Improve wording of previous change in variables.texi
d7973e8 Document 'default-toplevel-value' and 'set-default-toplevel-v...
8b71826 Don't modify minibuffer variables globally
5b5e036 Revert to pre-25.1 behavior in ffap
19994a1 * lisp/ffap.el: Fix obsolete comment referencing ffap-bug.
3ace730 Attempt to fix 64-bit AIX build
f69bd79 Clarify usage of 'ediff-cleanup-hook' (Bug#24675)
c04ac8a Document that variable binding order is unspecified
272554a * lisp/desktop.el (desktop-buffers-not-to-save): Doc fix.
08de101 Fix M-x hints on Mac port
86a297a Work around reporting a dpi change in apply_xft_settings
cf1f985 ; lisp/skeleton.el (skeleton-insert): Fix typo in last change
9e1209d Amend the version number of CC Mode 5.33 -> 5.32.99.  Don't m...
88cdf14 Improve skeleton docstrings

3 files changed, 64 insertions, 3 deletions

diff --git a/doc/lispref/variables.texi b/doc/lispref/variables.texi
index d9096dac018..4936f7a921a 100644
--- a/doc/lispref/variables.texi
+++ b/doc/lispref/variables.texi
@@ -223,6 +223,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{}
@@ -1630,6 +1642,45 @@ an ordinary evaluated argument.
 @end example
 @end defun
 
+  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
+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
diff --git a/doc/misc/cl.texi b/doc/misc/cl.texi
index 4f15cf53d4a..5af41a4465e 100644
--- a/doc/misc/cl.texi
+++ b/doc/misc/cl.texi
@@ -1179,6 +1179,11 @@ behavior.  (@code{point} and @code{point-marker} are equivalent
 as @code{setf} places; each will accept either an integer or a
 marker as the stored value.)
 
+Like in the case of @code{let}, the @var{value} forms are evaluated in
+the order they appear, but the order of bindings is unspecified.
+Therefore, avoid binding the same @var{place} more than once in a
+single @code{cl-letf} form.
+
 Since generalized variables look like lists, @code{let}'s shorthand
 of using @samp{foo} for @samp{(foo nil)} as a @var{binding} would
 be ambiguous in @code{cl-letf} and is not allowed.
diff --git a/doc/misc/ediff.texi b/doc/misc/ediff.texi
index 376aaeea46e..896a6041e86 100644
--- a/doc/misc/ediff.texi
+++ b/doc/misc/ediff.texi
@@ -1247,9 +1247,14 @@ merged (see @code{ediff-cleanup-hook}, below).
 @vindex ediff-cleanup-hook
 This hook is run just before @code{ediff-quit-hook}.  This is a good
 place to do various cleanups, such as deleting the variant buffers.
-Ediff provides a function, @code{ediff-janitor}, as one such possible
-hook, which you can add to @code{ediff-cleanup-hook} with
-@code{add-hook}.
+Ediff provides a helper function, @code{ediff-janitor}, that you can
+invoke from a private hook function.  For example:
+
+@example
+(defun my-ediff-janitor ()
+  (ediff-janitor nil nil))
+(add-hook 'ediff-cleanup-hook #'my-ediff-janitor)
+@end example
 
 @findex ediff-janitor
 This function kills buffers A, B, and, possibly, C, if these buffers aren't