From: Mattias Engdegård <mattiase@acm.org>
Date: Mon, 23 Oct 2023 09:12:33 +0000 (+0200)
Subject: Improved `eval` documentation
X-Git-Url: http://git.eshelyaron.com/gitweb/?a=commitdiff_plain;h=48e7f5493e4ffd31cb705adf982485c3b30fbbac;p=emacs.git

Improved `eval` documentation

Prompted by Michael Heerdegen.

* src/eval.c (Feval):
* doc/lispref/eval.texi (Eval):
Be more precise about the LEXICAL argument.
---

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 ();