; 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

@@ -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

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,
+This is meant to be used for adding elements to configuration
-but please do not abuse it in Elisp code, where you are usually
+variables, such as adding a directory to a path variable
-better off using `push' or `cl-pushnew'.
+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