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.

7 files changed, 53 insertions, 19 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
diff --git a/lisp/org/ob-lisp.el b/lisp/org/ob-lisp.el
index c156ca34a7c..d4a7c37133d 100644
--- a/lisp/org/ob-lisp.el
+++ b/lisp/org/ob-lisp.el
@@ -54,7 +54,7 @@ Valid values include `slime-eval' and `sly-eval'."
   :group 'org-babel
   :version "26.1"
   :package-version '(Org . "9.0")
-  :type 'function)
+  :type 'symbol)
 
 (defcustom org-babel-lisp-dir-fmt
   "(let ((*default-pathname-defaults* #P%S\n)) %%s\n)"
diff --git a/src/lisp.h b/src/lisp.h
index a7f0a1d78ff..aefdaeaf12f 100644
--- a/src/lisp.h
+++ b/src/lisp.h
@@ -2685,13 +2685,12 @@ struct Lisp_Buffer_Objfwd
    variable, you must first make sure the right binding is loaded;
    then you can access the value in (or through) `realvalue'.
 
-   `buffer' and `frame' are the buffer and frame for which the loaded
-   binding was found.  If those have changed, to make sure the right
-   binding is loaded it is necessary to find which binding goes with
-   the current buffer and selected frame, then load it.  To load it,
-   first unload the previous binding, then copy the value of the new
-   binding into `realvalue' (or through it).  Also update
-   LOADED-BINDING to point to the newly loaded binding.
+   `where' is the buffer for which the loaded binding was found.  If
+   it has changed, to make sure the right binding is loaded it is
+   necessary to find which binding goes with the current buffer, then
+   load it.  To load it, first unload the previous binding, then copy
+   the value of the new binding into `realvalue' (or through it).
+   Also update LOADED-BINDING to point to the newly loaded binding.
 
    `local_if_set' indicates that merely setting the variable creates a
    local binding for the current buffer.  Otherwise the latter, setting
@@ -2707,14 +2706,14 @@ struct Lisp_Buffer_Local_Value
     bool_bf found : 1;
     /* If non-NULL, a forwarding to the C var where it should also be set.  */
     union Lisp_Fwd *fwd;        /* Should never be (Buffer|Kboard)_Objfwd.  */
-    /* The buffer or frame for which the loaded binding was found.  */
+    /* The buffer for which the loaded binding was found.  */
     Lisp_Object where;
     /* A cons cell that holds the default value.  It has the form
        (SYMBOL . DEFAULT-VALUE).  */
     Lisp_Object defcell;
     /* The cons cell from `where's parameter alist.
        It always has the form (SYMBOL . VALUE)
-       Note that if `forward' is non-nil, VALUE may be out of date.
+       Note that if `fwd' is non-NULL, VALUE may be out of date.
        Also if the currently loaded binding is the default binding, then
        this is `eq'ual to defcell.  */
     Lisp_Object valcell;