master 48e7f5493e4 1/4: Improved `eval` documentation

[Mattias Engdegård]

branch: master
commit 48e7f5493e4ffd31cb705adf982485c3b30fbbac
Author: Mattias Engdegård <mattiase@acm.org>
Commit: Mattias Engdegård <mattiase@acm.org>

    Improved `eval` documentation
    
    Prompted by Michael Heerdegen.
    
    * src/eval.c (Feval):
    * doc/lispref/eval.texi (Eval):
    Be more precise about the LEXICAL argument.
---
 doc/lispref/eval.texi |  9 +++++----
 src/eval.c            | 10 +++++++---
 2 files changed, 12 insertions(+), 7 deletions(-)

diff --git a/doc/lispref/eval.texi b/doc/lispref/eval.texi
index ea35d4d38c7..8af0ee49d02 100644
--- a/doc/lispref/eval.texi
+++ b/doc/lispref/eval.texi
@@ -740,16 +740,17 @@ 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.
+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
diff --git a/src/eval.c b/src/eval.c
index 9268b65aa85..f5397e9fb72 100644
--- a/src/eval.c
+++ b/src/eval.c
@@ -2364,9 +2364,13 @@ static Lisp_Object list_of_t;  /* Never-modified 
constant containing (t).  */
 
 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 ();