@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.
+variables (@pxref{Variable Scoping}). If it is @code{t}, that means
+to evaluate @var{form} using lexical scoping; this is the recommended
+value. If it is omitted or @code{nil}, that means to use the old
+dynamic-only variable scoping rule.
The value of @var{lexical} can also be a non-empty list specifying a
particular @dfn{lexical environment} for lexical bindings; however,
this feature is only useful for specialized purposes, such as in Emacs
Lisp debuggers. Each member of the list is either a cons cell which
represents a lexical symbol-value pair, or a symbol representing a
-dynamically bound variable.
+(special) variable that would use dynamic scoping if bound.
Since @code{eval} is a function, the argument expression that appears
in a call to @code{eval} is evaluated twice: once as preparation before
DEFUN ("eval", Feval, Seval, 1, 2, 0,
doc: /* Evaluate FORM and return its value.
-If LEXICAL is t, evaluate using lexical scoping.
-LEXICAL can also be an actual lexical environment, in the form of an
-alist mapping symbols to their value. */)
+If LEXICAL is `t', evaluate using lexical binding by default.
+This is the recommended value.
+
+If absent or `nil', use dynamic scoping only.
+
+LEXICAL can also represent an actual lexical environment; see the Info
+node `(elisp)Eval' for details. */)
(Lisp_Object form, Lisp_Object lexical)
{
specpdl_ref count = SPECPDL_INDEX ();