From b9762c6a84407413e757e19f8ca862e8426d32be Mon Sep 17 00:00:00 2001 From: Eli Zaretskii Date: Fri, 9 Aug 2024 08:45:30 +0300 Subject: [PATCH] ; 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) --- 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 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 -- 2.39.2