Explain more about (defvar foo) form (Bug#18059)

* doc/lispref/variables.texi (Defining Variables)
(Using Lexical Binding):
* doc/lispref/compile.texi (Compiler Errors): Emphasize that omitting
VALUE for `defvar' marks the variable special only locally.
* doc/lispref/variables.texi (Using Lexical Binding): Add example of
using `defvar' without VALUE.

2 files changed, 38 insertions, 4 deletions

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