Merge from origin/emacs-26

b8ebf5fb64 * src/lisp.h (struct Lisp_Buffer_Local_Value): Update comm...
8c92a37cb4 * doc/emacs/trouble.texi: Fix location of `emacs-version' ...
10b1f2fdd5 Explain more about (defvar foo) form (Bug#18059)
68c2f336b1 * doc/lispref/buffers.texi (Buffer List): Fix grammar.
7e720c6851 * doc/lispref/anti.texi (Antinews): Fix grammar.
a6a821d29b * lisp/org/ob-lisp.el (org-babel-lisp-eval-fn): Tweak type.

5 files changed, 44 insertions, 9 deletions

diff --git a/doc/emacs/trouble.texi b/doc/emacs/trouble.texi
index c0dc3d472e3..fc9a64d375e 100644
--- a/doc/emacs/trouble.texi
+++ b/doc/emacs/trouble.texi
@@ -594,7 +594,6 @@ with the manual, one of them must be wrong; that is a bug.
 @cindex bug reporting
 @cindex report an Emacs bug, how to
 
-@findex emacs-version
   When you decide that there is a bug, it is important to report it
 and to report it in a way which is useful.  What is most useful is an
 exact description of what commands you type, starting with the shell
@@ -717,6 +716,7 @@ should include all these things:
 The version number of Emacs.  Without this, we won't know whether there is any
 point in looking for the bug in the current version of GNU Emacs.
 
+@findex emacs-version
 @kbd{M-x report-emacs-bug} includes this information automatically,
 but if you are not using that command for your report you can get the
 version number by typing @kbd{M-x emacs-version @key{RET}}.  If that
diff --git a/doc/lispref/anti.texi b/doc/lispref/anti.texi
index ef28415d591..556203b69f0 100644
--- a/doc/lispref/anti.texi
+++ b/doc/lispref/anti.texi
@@ -164,9 +164,10 @@ come, and learning to use yet another API is a burden.
 
 @item
 The function @code{read-multiple-choice} is also gone, in recognition
-of the fact that nothing makes Emacs Lisp hacker rejoice more than the
-need to sit down and write yet another interactive question-and-answer
-function, and make it optimal for each specific case.
+of the fact that nothing makes Emacs Lisp hackers rejoice more than
+the need to sit down and write yet another interactive
+question-and-answer function, and make it optimal for each specific
+case.
 
 @item
 The function @code{add-variable-watcher} and the corresponding
diff --git a/doc/lispref/buffers.texi b/doc/lispref/buffers.texi
index a72e1eb69fc..cfd2fb7715b 100644
--- a/doc/lispref/buffers.texi
+++ b/doc/lispref/buffers.texi
@@ -891,7 +891,7 @@ This function operates on each frame's @code{buffer-list} parameter as
 well as the fundamental buffer list; therefore, the buffer that you bury
 will come last in the value of @code{(buffer-list @var{frame})} and in
 the value of @code{(buffer-list)}.  In addition, it also puts the buffer
-at the end of the list of buffer of the selected window (@pxref{Window
+at the end of the list of buffers of the selected window (@pxref{Window
 History}) provided it is shown in that window.
 
 If @var{buffer-or-name} is @code{nil} or omitted, this means to bury the
diff --git a/doc/lispref/compile.texi b/doc/lispref/compile.texi
index 0e39866d349..e665b84f9b8 100644
--- a/doc/lispref/compile.texi
+++ b/doc/lispref/compile.texi
@@ -500,7 +500,8 @@ You can tell the compiler that a function is defined using
 @item
 Likewise, you can tell the compiler that a variable is defined using
 @code{defvar} with no initial value.  (Note that this marks the
-variable as special, i.e.@: dynamically bound.)  @xref{Defining
+variable as special, i.e.@: dynamically bound, but only within the
+current lexical scope, or file if at top-level.)  @xref{Defining
 Variables}.
 @end itemize
 
diff --git a/doc/lispref/variables.texi b/doc/lispref/variables.texi
index b80bc88a585..4d04335d83a 100644
--- a/doc/lispref/variables.texi
+++ b/doc/lispref/variables.texi
@@ -443,9 +443,13 @@ dynamically bound value; @pxref{Void Variables}), then @var{value} is
 evaluated and @var{symbol} is set to the result.  But if @var{symbol}
 is not void, @var{value} is not evaluated, and @var{symbol}'s value is
 left unchanged.  If @var{value} is omitted, the value of @var{symbol}
-is not changed in any case.  Using @code{defvar} with no value is one
-method of suppressing byte compilation warnings, see @ref{Compiler
-Errors}.
+is not changed in any case.
+
+Note that specifying a value, even @code{nil}, marks the variable as
+special permanently.  Whereas if @var{value} is omitted then the
+variable is only marked special locally (i.e.@: within the current
+lexical scope, or file if at the top-level).  This can be useful for
+suppressing byte compilation warnings, see @ref{Compiler Errors}.
 
 If @var{symbol} has a buffer-local binding in the current buffer,
 @code{defvar} acts on the default value, which is buffer-independent,
@@ -489,6 +493,9 @@ it a documentation string:
 
 The @code{defvar} form returns @var{symbol}, but it is normally used
 at top level in a file where its value does not matter.
+
+For a more elaborate example of using @code{defvar} without a value,
+see @ref{Local defvar example}.
 @end defspec
 
 @cindex constant variables
@@ -1165,6 +1172,32 @@ variables}.  Every variable that has been defined with @code{defvar},
 (@pxref{Defining Variables}).  All other variables are subject to
 lexical binding.
 
+@anchor{Local defvar example}
+Using @code{defvar} without a value, it is possible to bind a variable
+dynamically just in one file, or in just one part of a file while
+still binding it lexically elsewhere.  For example:
+
+@example
+@group
+(let (_)
+  (defvar x)      ; @r{Let-bindings of @code{x} will be dynamic within this let.}
+  (let ((x -99))  ; @r{This is a dynamic binding of @code{x}.}
+    (defun get-dynamic-x ()
+      x)))
+
+(let ((x 'lexical)) ; @r{This is a lexical binding of @code{x}.}
+  (defun get-lexical-x ()
+    x))
+
+(let (_)
+  (defvar x)
+  (let ((x 'dynamic))
+    (list (get-lexical-x)
+          (get-dynamic-x))))
+    @result{} (lexical dynamic)
+@end group
+@end example
+
 @defun special-variable-p symbol
 This function returns non-@code{nil} if @var{symbol} is a special
 variable (i.e., it has a @code{defvar}, @code{defcustom}, or