Update Variables chapter of Lisp manual to handle lexical binding.

* doc/lispref/variables.texi (Variables, Local Variables, Void Variables):
Edit to make the descriptions less specific to dynamic binding.
(Local Variables): Default max-specpdl-size is now 1300.
(Defining Variables): Edits for lexical scoping.  Delete
information about starting docstrings with *.  De-document
user-variable-p.
(Tips for Defining): Remove an unimportant discussion of quitting
in the middle of a load.
(Accessing Variables, Setting Variables): Discuss lexical binding.
(Variable Scoping): Rewrite.
(Scope, Extent, Impl of Scope): Nodes deleted.
(Dynamic Binding): New node, with material from Scope, Extent, and
Impl of Scope nodes.
(Dynamic Binding Tips): Rename from Using Scoping.
(Lexical Binding): Rewrite.
(Using Lexical Binding): Rename from Converting to Lexical
Binding.  Convert to subsection.

* doc/lispref/customize.texi (Variable Definitions): Add custom-variable-p.
Move user-variable-p documentation here.

doc/lispref/ChangeLog

@@ -1,3 +1,26 @@
+2012-01-24  Chong Yidong  <cyd@gnu.org>
+
+	* variables.texi (Variables, Local Variables, Void Variables):
+	Edit to make the descriptions less specific to dynamic binding.
+	(Local Variables): Default max-specpdl-size is now 1300.
+	(Defining Variables): Edits for lexical scoping.  Delete
+	information about starting docstrings with *.  De-document
+	user-variable-p.
+	(Tips for Defining): Remove an unimportant discussion of quitting
+	in the middle of a load.
+	(Accessing Variables, Setting Variables): Discuss lexical binding.
+	(Variable Scoping): Rewrite.
+	(Scope, Extent, Impl of Scope): Nodes deleted.
+	(Dynamic Binding): New node, with material from Scope, Extent, and
+	Impl of Scope nodes.
+	(Dynamic Binding Tips): Rename from Using Scoping.
+	(Lexical Binding): Rewrite.
+	(Using Lexical Binding): Rename from Converting to Lexical
+	Binding.  Convert to subsection.
+
+	* customize.texi (Variable Definitions): Add custom-variable-p.
+	Move user-variable-p documentation here.
+
 2012-01-23  Chong Yidong  <cyd@gnu.org>
 
 	* strings.texi (Text Comparison): Minor qualification.

doc/lispref/customize.texi

@@ -262,12 +262,6 @@ turn this feature back on, if someone would like to do the work.
 This macro declares @var{option} as a customizable @dfn{user option}.
 You should not quote @var{option}.
 
-This causes the function @code{user-variable-p} to return @code{t}
-when given @var{option} as an argument.  @xref{Defining Variables}.
-The argument @var{doc} specifies the documentation string for the
-variable.  (Note that there is no need to start @var{doc} with a
-@samp{*}.)
-
 The argument @var{standard} is an expression that specifies the
 standard value for @var{option}.  Evaluating the @code{defcustom} form
 evaluates @var{standard}, but does not necessarily install the
@@ -285,6 +279,9 @@ evaluate at any time.  We recommend avoiding backquotes in
 @var{standard}, because they are not expanded when editing the value,
 so list values will appear to have the wrong structure.
 
+The argument @var{doc} specifies the documentation string for the
+variable.
+
 Every @code{defcustom} should specify @code{:group} at least once.
 
 If you specify the @code{:set} keyword, to make the variable take other
@@ -474,6 +471,22 @@ A good place to put calls to this function is in the function
 or in the various hooks it calls.
 @end defun
 
+@defun custom-variable-p arg
+This function returns non-@code{nil} if @var{arg} is a customizable
+variable.  A customizable variable is either a variable that has a
+@code{standard-value} or @code{custom-autoload} property (usually
+meaning it was declared with @code{defcustom}), or an alias for
+another customizable variable.
+@end defun
+
+@defun user-variable-p arg
+This function is like @code{custom-variable-p}, except it also returns
+@code{t} if the first character of the variable's documentation string
+is the character @samp{*}.  That is an obsolete way of indicating a
+user option, so for most purposes you may consider
+@code{user-variable-p} as equivalent to @code{custom-variable-p}.
+@end defun
+
 @node Customization Types
 @section Customization Types
 

doc/lispref/elisp.texi

@@ -436,12 +436,10 @@ Variables
 
 Scoping Rules for Variable Bindings
 
-* Scope::                   Scope means where in the program a value
-                              is visible.  Comparison with other languages.
-* Extent::                  Extent means how long in time a value exists.
-* Impl of Scope::           Two ways to implement dynamic scoping.
-* Using Scoping::           How to use dynamic scoping carefully and
-                              avoid problems.
+* Dynamic Binding::         The default for binding local variables in Emacs.
+* Dynamic Binding Tips::    Avoiding problems with dynamic binding.
+* Lexical Binding::         A different type of local variable binding.
+* Using Lexical Binding::   How to enable lexical binding.
 
 Buffer-Local Variables
 

doc/lispref/objects.texi

@@ -1795,6 +1795,9 @@ with references to further information.
 @item consp
 @xref{List-related Predicates, consp}.
 
+@item custom-variable-p
+@xref{Variable Definitions, custom-variable-p}.
+
 @item display-table-p
 @xref{Display Tables, display-table-p}.
 
@@ -1870,9 +1873,6 @@ with references to further information.
 @item syntax-table-p
 @xref{Syntax Tables, syntax-table-p}.
 
-@item user-variable-p
-@xref{Defining Variables, user-variable-p}.
-
 @item vectorp
 @xref{Vectors, vectorp}.