; 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 dce9115c61bf174f03fbb59775a58b3869730b65..6f4d838042a8a17893eb55258fb07cf8b101fbd2 100644 (file)
--- 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 0bc8d7ba7e1a3dc95cbf903eed5016c29a51c033..b87538354674b67a42d88ec3b3a2640e17f735d0 100644 (file)
--- 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