Document `eval' changes.

* doc/lispref/eval.texi (Eval): Document the LEXICAL arg to eval.

* doc/lispref/variables.texi (Variables, Void Variables): Use "scoping rule"
terminology consistently.
(Variable Scoping): Add index entries, and use "dynamic scope"
terminology in place of "indefinite scope" to reduce confusion.
(Lexical Binding): Document lexical environment format.
(Using Lexical Binding): Add index entries for error messages.

4 files changed, 89 insertions, 60 deletions

diff --git a/doc/lispref/ChangeLog b/doc/lispref/ChangeLog
index b1c210834d2..595102bb5ef 100644
--- a/doc/lispref/ChangeLog
+++ b/doc/lispref/ChangeLog
@@ -1,3 +1,14 @@
+2013-12-25  Chong Yidong  <cyd@gnu.org>
+
+        * eval.texi (Eval): Document the LEXICAL arg to eval.
+
+        * variables.texi (Variables, Void Variables): Use "scoping rule"
+        terminology consistently.
+        (Variable Scoping): Add index entries, and use "dynamic scope"
+        terminology in place of "indefinite scope" to reduce confusion.
+        (Lexical Binding): Document lexical environment format.
+        (Using Lexical Binding): Add index entries for error messages.
+
 2013-12-24  Tassilo Horn  <tsdh@gnu.org>
 
         * control.texi (Pattern matching case statement): Fix missing
diff --git a/doc/lispref/eval.texi b/doc/lispref/eval.texi
index df30b909cbd..4a63ec2add1 100644
--- a/doc/lispref/eval.texi
+++ b/doc/lispref/eval.texi
@@ -715,12 +715,18 @@ arguments.
 
 @defun eval form &optional lexical
 This is the basic function for evaluating an expression.  It evaluates
-@var{form} in the current environment and returns the result.  How the
-evaluation proceeds depends on the type of the object (@pxref{Forms}).
-
-The argument @var{lexical}, if non-@code{nil}, means to evaluate
-@var{form} using lexical scoping rules for variables, instead of the
-default dynamic scoping rules.  @xref{Lexical Binding}.
+@var{form} in the current environment, and returns the result.  The
+type of the @var{form} object determines how it is evaluated.
+@xref{Forms}.
+
+The argument @var{lexical} specifies the scoping rule for local
+variables (@pxref{Variable Scoping}).  If it is omitted or @code{nil},
+that means to evaluate @var{form} using the default dynamic scoping
+rule.  If it is @code{t}, that means to use the lexical scoping rule.
+The value of @var{lexical} can also be a non-empty alist specifying a
+particular @dfn{lexical environment} for lexical bindings; however,
+this feature is only useful for specialized purposes, such as in Emacs
+Lisp debuggers.  @xref{Lexical Binding}.
 
 Since @code{eval} is a function, the argument expression that appears
 in a call to @code{eval} is evaluated twice: once as preparation before
diff --git a/doc/lispref/variables.texi b/doc/lispref/variables.texi
index 941b2d880e4..5d1a47661aa 100644
--- a/doc/lispref/variables.texi
+++ b/doc/lispref/variables.texi
@@ -10,10 +10,10 @@
 In Lisp, each variable is represented by a Lisp symbol
 (@pxref{Symbols}).  The variable name is simply the symbol's name, and
 the variable's value is stored in the symbol's value cell@footnote{To
-be precise, under the default @dfn{dynamic binding} rules the value
+be precise, under the default @dfn{dynamic scoping} rule, the value
 cell always holds the variable's current value, but this is not the
-case under @dfn{lexical binding} rules.  @xref{Variable Scoping}, for
-details.}.  @xref{Symbol Components}.  In Emacs Lisp, the use of a
+case under the @dfn{lexical scoping} rule.  @xref{Variable Scoping},
+for details.}.  @xref{Symbol Components}.  In Emacs Lisp, the use of a
 symbol as a variable is independent of its use as a function name.
 
   As previously noted in this manual, a Lisp program is represented
@@ -292,20 +292,22 @@ has room to execute.
 @cindex void variable
 
   We say that a variable is void if its symbol has an unassigned value
-cell (@pxref{Symbol Components}).  Under Emacs Lisp's default dynamic
-binding rules (@pxref{Variable Scoping}), the value cell stores the
-variable's current (local or global) value.  Note that an unassigned
-value cell is @emph{not} the same as having @code{nil} in the value
-cell.  The symbol @code{nil} is a Lisp object and can be the value of
-a variable, just as any other object can be; but it is still a value.
-If a variable is void, trying to evaluate the variable signals a
-@code{void-variable} error rather than a value.
-
-  Under lexical binding rules, the value cell only holds the
-variable's global value, i.e., the value outside of any lexical
-binding construct.  When a variable is lexically bound, the local value
-is determined by the lexical environment; the variable may have a
-local value if its symbol's value cell is unassigned.
+cell (@pxref{Symbol Components}).
+
+  Under Emacs Lisp's default dynamic scoping rule (@pxref{Variable
+Scoping}), the value cell stores the variable's current (local or
+global) value.  Note that an unassigned value cell is @emph{not} the
+same as having @code{nil} in the value cell.  The symbol @code{nil} is
+a Lisp object and can be the value of a variable, just as any other
+object can be; but it is still a value.  If a variable is void, trying
+to evaluate the variable signals a @code{void-variable} error, instead
+of returning a value.
+
+  Under the optional lexical scoping rule, the value cell only holds
+the variable's global value---the value outside of any lexical binding
+construct.  When a variable is lexically bound, the local value is
+determined by the lexical environment; hence, variables can have local
+values even if their symbols' value cells are unassigned.
 
 @defun makunbound symbol
 This function empties out the value cell of @var{symbol}, making the
@@ -761,6 +763,7 @@ error is signaled.
 
 @node Variable Scoping
 @section Scoping Rules for Variable Bindings
+@cindex scoping rule
 
   When you create a local binding for a variable, that binding takes
 effect only within a limited portion of the program (@pxref{Local
@@ -774,12 +777,12 @@ binding can be accessed.  @dfn{Extent} refers to @emph{when}, as the
 program is executing, the binding exists.
 
 @cindex dynamic binding
-@cindex indefinite scope
+@cindex dynamic scope
 @cindex dynamic extent
   By default, the local bindings that Emacs creates are @dfn{dynamic
-bindings}.  Such a binding has @dfn{indefinite scope}, meaning that
-any part of the program can potentially access the variable binding.
-It also has @dfn{dynamic extent}, meaning that the binding lasts only
+bindings}.  Such a binding has @dfn{dynamic scope}, meaning that any
+part of the program can potentially access the variable binding.  It
+also has @dfn{dynamic extent}, meaning that the binding lasts only
 while the binding construct (such as the body of a @code{let} form) is
 being executed.
 
@@ -788,11 +791,12 @@ being executed.
 @cindex indefinite extent
   Emacs can optionally create @dfn{lexical bindings}.  A lexical
 binding has @dfn{lexical scope}, meaning that any reference to the
-variable must be located textually within the binding construct.  It
-also has @dfn{indefinite extent}, meaning that under some
-circumstances the binding can live on even after the binding construct
-has finished executing, by means of special objects called
-@dfn{closures}.
+variable must be located textually within the binding
+construct@footnote{With some exceptions; for instance, a lexical
+binding can also be accessed from the Lisp debugger.}.  It also has
+@dfn{indefinite extent}, meaning that under some circumstances the
+binding can live on even after the binding construct has finished
+executing, by means of special objects called @dfn{closures}.
 
   The following subsections describe dynamic binding and lexical
 binding in greater detail, and how to enable lexical binding in Emacs
@@ -814,8 +818,8 @@ at any point in the execution of the Lisp program is simply the most
 recently-created dynamic local binding for that symbol, or the global
 binding if there is no such local binding.
 
-  Dynamic bindings have indefinite scope and dynamic extent, as shown
-by the following example:
+  Dynamic bindings have dynamic scope and extent, as shown by the
+following example:
 
 @example
 @group
@@ -841,9 +845,9 @@ The function @code{getx} refers to @code{x}.  This is a ``free''
 reference, in the sense that there is no binding for @code{x} within
 that @code{defun} construct itself.  When we call @code{getx} from
 within a @code{let} form in which @code{x} is (dynamically) bound, it
-retrieves the local value of @code{x} (i.e., 1).  But when we call
-@code{getx} outside the @code{let} form, it retrieves the global value
-of @code{x} (i.e., -99).
+retrieves the local value (i.e., 1).  But when we call @code{getx}
+outside the @code{let} form, it retrieves the global value (i.e.,
+-99).
 
   Here is another example, which illustrates setting a dynamically
 bound variable using @code{setq}:
@@ -888,12 +892,11 @@ technique:
 @itemize @bullet
 @item
 If a variable has no global definition, use it as a local variable
-only within a binding construct, e.g., the body of the @code{let}
-form where the variable was bound, or the body of the function for an
-argument variable.  If this convention is followed consistently
-throughout a program, the value of the variable will not affect, nor
-be affected by, any uses of the same variable symbol elsewhere in the
-program.
+only within a binding construct, such as the body of the @code{let}
+form where the variable was bound.  If this convention is followed
+consistently throughout a program, the value of the variable will not
+affect, nor be affected by, any uses of the same variable symbol
+elsewhere in the program.
 
 @item
 Otherwise, define the variable with @code{defvar}, @code{defconst}, or
@@ -925,12 +928,16 @@ variables like @code{case-fold-search}:
 @node Lexical Binding
 @subsection Lexical Binding
 
-Optionally, you can create lexical bindings in Emacs Lisp.  A
-lexically bound variable has @dfn{lexical scope}, meaning that any
-reference to the variable must be located textually within the binding
-construct.
+  Lexical binding was introduced to Emacs, as an optional feature, in
+version 24.1.  We expect its importance to increase in the future.
+Lexical binding opens up many more opportunities for optimization, so
+programs using it are likely to run faster in future Emacs versions.
+Lexical binding is also more compatible with concurrency, which we
+want to add to Emacs in the future.
 
-  Here is an example
+  A lexically-bound variable has @dfn{lexical scope}, meaning that any
+reference to the variable must be located textually within the binding
+construct.  Here is an example
 @iftex
 (see the next subsection, for how to actually enable lexical binding):
 @end iftex
@@ -969,6 +976,14 @@ wants the current value of a variable, it looks first in the lexical
 environment; if the variable is not specified in there, it looks in
 the symbol's value cell, where the dynamic value is stored.
 
+  (Internally, the lexical environment is an alist of symbol-value
+pairs, with the final element in the alist being the symbol @code{t}
+rather than a cons cell.  Such an alist can be passed as the second
+argument to the @code{eval} function, in order to specify a lexical
+environment in which to evaluate a form.  @xref{Eval}.  Most Emacs
+Lisp programs, however, should not interact directly with lexical
+environments in this way; only specialized programs like debuggers.)
+
 @cindex closures, example of using
   Lexical bindings have indefinite extent.  Even after a binding
 construct has finished executing, its lexical environment can be
@@ -1019,13 +1034,6 @@ binding of @code{x} in that lexical environment.
 the body of a @code{defun} or @code{defmacro} cannot refer to
 surrounding lexical variables.
 
-  Currently, lexical binding is not much used within the Emacs
-sources.  However, we expect its importance to increase in the future.
-Lexical binding opens up a lot more opportunities for optimization, so
-Emacs Lisp code that makes use of lexical binding is likely to run
-faster in future Emacs versions.  Such code is also much more friendly
-to concurrency, which we want to add to Emacs in the near future.
-
 @node Using Lexical Binding
 @subsection Using Lexical Binding
 
@@ -1069,12 +1077,15 @@ discouraged.  Doing so gives rise to unspecified behavior when lexical
 binding mode is enabled (it may use lexical binding sometimes, and
 dynamic binding other times).
 
-  Converting an Emacs Lisp program to lexical binding is pretty easy.
-First, add a file-local variable setting of @code{lexical-binding} to
-@code{t} in the Emacs Lisp source file.  Second, check that every
-variable in the program which needs to be dynamically bound has a
-variable definition, so that it is not inadvertently bound lexically.
+  Converting an Emacs Lisp program to lexical binding is easy.  First,
+add a file-local variable setting of @code{lexical-binding} to
+@code{t} in the header line of the Emacs Lisp source file (@pxref{File
+Local Variables}).  Second, check that every variable in the program
+which needs to be dynamically bound has a variable definition, so that
+it is not inadvertently bound lexically.
 
+@cindex free variable
+@cindex unused lexical variable
   A simple way to find out which variables need a variable definition
 is to byte-compile the source file.  @xref{Byte Compilation}.  If a
 non-special variable is used outside of a @code{let} form, the
diff --git a/etc/NEWS b/etc/NEWS
index 2e6da37590c..00a72f03e0d 100644
--- a/etc/NEWS
+++ b/etc/NEWS
@@ -916,6 +916,7 @@ something (not just adding elements to it).
 
 * Lisp Changes in Emacs 24.4
 
++++
 ** The second argument of `eval' can now specify a lexical environment.
 
 +++