>From 20757fcabb82828e63096bcd02faee2ec54e3afb Mon Sep 17 00:00:00 2001
From: Noam Postavsky <npostavs@gmail.com>
Date: Sat, 10 Feb 2018 14:06:05 -0500
Subject: [PATCH v2] Explain more about (defvar foo) form (Bug#18059)

* doc/lispref/variables.texi (Defining Variables):
* doc/lispref/compile.texi (Compiler Errors): Emphasize that omitting
VALUE for `defvar' marks the variable special only locally.
---
 doc/lispref/compile.texi   |  4 ++--
 doc/lispref/variables.texi | 11 ++++++++---
 2 files changed, 10 insertions(+), 5 deletions(-)

diff --git a/doc/lispref/compile.texi b/doc/lispref/compile.texi
index 0e39866d34..77d35be1ba 100644
--- a/doc/lispref/compile.texi
+++ b/doc/lispref/compile.texi
@@ -500,8 +500,8 @@ Compiler Errors
 @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
-Variables}.
+variable as special, i.e.@: dynamically bound, but only within the
+file.)  @xref{Defining Variables}.
 @end itemize
 
   You can also suppress any and all compiler warnings within a certain
diff --git a/doc/lispref/variables.texi b/doc/lispref/variables.texi
index e025d3fd10..a6df16d03f 100644
--- a/doc/lispref/variables.texi
+++ b/doc/lispref/variables.texi
@@ -442,9 +442,13 @@ Defining Variables
 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.@: for the rest of the
+current file).  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,
@@ -488,6 +492,7 @@ Defining Variables
 
 The @code{defvar} form returns @var{symbol}, but it is normally used
 at top level in a file where its value does not matter.
+
 @end defspec
 
 @cindex constant variables
-- 
2.11.0