From: Eli Zaretskii <eliz@gnu.org>
Date: Fri, 9 Aug 2024 05:45:30 +0000 (+0300)
Subject: ; Improve documentation of 'add-to-list'
X-Git-Url: http://git.eshelyaron.com/gitweb/?a=commitdiff_plain;h=b9762c6a84407413e757e19f8ca862e8426d32be;p=emacs.git

; 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'.

(cherry picked from commit a0406f7c12e4f7f175646c6468a5ff9290da4c34)
---

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 0bc8d7ba7e1..b8753835467 100644
--- a/lisp/subr.el
+++ b/lisp/subr.el
@@ -2385,9 +2385,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