emacs-30 a0406f7c12e: ; Improve documentation of 'add-to-list'

[Eli Zaretskii]

branch: emacs-30
commit a0406f7c12e4f7f175646c6468a5ff9290da4c34
Author: Eli Zaretskii <eliz@gnu.org>
Commit: Eli Zaretskii <eliz@gnu.org>

    ; Improve documentation of 'add-to-list'
    
    * doc/lispref/lists.texi (List Variables):
    * lisp/subr.el (add-to-list): Add/clarify caveats of using
    'add-to-list'.
---
 doc/lispref/lists.texi | 7 +++++++
 lisp/subr.el           | 8 +++++---
 2 files changed, 12 insertions(+), 3 deletions(-)

diff --git a/doc/lispref/lists.texi b/doc/lispref/lists.texi
index dce9115c61b..6f4d838042a 100644
--- a/doc/lispref/lists.texi
+++ b/doc/lispref/lists.texi
@@ -840,6 +840,13 @@ 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.
 
+This function is for adding elements to configuration variables such as
+@code{load-path} (@pxref{Library Search}), @code{image-load-path}
+(@pxref{Defining Images}), etc.  Its code includes quite a few special
+checks for these uses, and emits warnings in support of them.  For this
+reason, we recommend against using it in Lisp programs for constructing
+arbitrary lists; use @code{push} instead.  @xref{List Variables}.
+
 Do not use this function when @var{symbol} refers to a lexical
 variable.
 @end defun
diff --git a/lisp/subr.el b/lisp/subr.el
index b382fa9f771..31c53a6455b 100644
--- a/lisp/subr.el
+++ b/lisp/subr.el
@@ -2386,9 +2386,11 @@ LIST-VAR should not refer to a lexical variable.
 
 The return value is the new value of LIST-VAR.
 
-This is handy to add some elements to configuration variables,
-but please do not abuse it in Elisp code, where you are usually
-better off using `push' or `cl-pushnew'.
+This is meant to be used for adding elements to configuration
+variables, such as adding a directory to a path variable
+like `load-path', but please do not abuse it to construct
+arbitrary lists in Elisp code, where using `push' or `cl-pushnew'
+will get you more efficient code.
 
 If you want to use `add-to-list' on a variable that is not
 defined until a certain package is loaded, you should put the