emacs-27 d07f177 1/2: Clarify add-to-list documentation (bug#39373)

[Mattias Engdegård]

branch: emacs-27
commit d07f177382b24945e1f579744702908b33605c3e
Author: Mattias Engdegård <address@hidden>
Commit: Mattias Engdegård <address@hidden>

    Clarify add-to-list documentation (bug#39373)
    
    While add-to-list often works with lexical variables, this is a hack
    that isn't always effective; better tell the user not to try.
    
    * doc/lispref/lists.texi (List Variables): Add a note about lexical
    variables to the add-to-list description.  Fix the equivalent code.
    * lisp/subr.el (add-to-list): Amend doc string.
---
 doc/lispref/lists.texi | 8 ++++++--
 lisp/subr.el           | 1 +
 2 files changed, 7 insertions(+), 2 deletions(-)

diff --git a/doc/lispref/lists.texi b/doc/lispref/lists.texi
index 5ef21d0..ce0d9a3 100644
--- a/doc/lispref/lists.texi
+++ b/doc/lispref/lists.texi
@@ -777,6 +777,9 @@ non-@code{nil}, it is added at the end.
 The argument @var{symbol} is not implicitly quoted; @code{add-to-list}
 is an ordinary function, like @code{set} and unlike @code{setq}.  Quote
 the argument yourself if that is what you want.
+
+Do not use this function when @var{symbol} refers to a lexical
+variable.
 @end defun
 
 Here's a scenario showing how to use @code{add-to-list}:
@@ -799,8 +802,9 @@ foo                       ;; @r{@code{foo} was changed.}
 @var{value})} is this:
 
 @example
-(or (member @var{value} @var{var})
-    (setq @var{var} (cons @var{value} @var{var})))
+(if (member @var{value} @var{var})
+    @var{var}
+  (setq @var{var} (cons @var{value} @var{var})))
 @end example
 
 @defun add-to-ordered-list symbol element &optional order
diff --git a/lisp/subr.el b/lisp/subr.el
index a4fdc6b..05fb823 100644
--- a/lisp/subr.el
+++ b/lisp/subr.el
@@ -1845,6 +1845,7 @@ COMPARE-FN if that's non-nil.
 If ELEMENT is added, it is added at the beginning of the list,
 unless the optional argument APPEND is non-nil, in which case
 ELEMENT is added at the end.
+LIST-VAR should not refer to a lexical variable.
 
 The return value is the new value of LIST-VAR.