procyberian/emacs
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

; Improve documentation of 'add-to-list'

Browse source 
* doc/lispref/lists.texi (List Variables):
* lisp/subr.el (add-to-list): Add/clarify caveats of using
'add-to-list'.
This commit is contained in:
Eli Zaretskii 2024-08-09 08:45:30 +03:00
parent bd6dfb97ff
commit a0406f7c12
2 changed files with 12 additions and 3 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

7
doc/lispref/lists.texi
View file

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

8
lisp/subr.el
View file

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