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.

1 files changed, 12 insertions, 6 deletions

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