unofficial mirror of emacs-devel@gnu.org 
 help / color / mirror / code / Atom feed
* Lispref add-to-list - doc is unnecessary convoluted
@ 2020-12-04  2:17 Arthur Miller
  2020-12-04  2:27 ` Christopher Dimech
                   ` (2 more replies)
  0 siblings, 3 replies; 23+ messages in thread
From: Arthur Miller @ 2020-12-04  2:17 UTC (permalink / raw)
  To: emacs-devel

[-- Attachment #1: Type: text/plain, Size: 1758 bytes --]

Function: add-to-list symbol element &optional append compare-fn

    This function sets the variable symbol by consing element onto the old value, if element is not already a member of that value. It returns the resulting list, whether updated or not. The value of symbol had better be a list already before the call. add-to-list uses compare-fn to compare element against existing list members; if compare-fn is nil, it uses equal.

    Normally, if element is added, it is added to the front of symbol, but if the optional argument append is non-nil, it is added at the end.

    The argument symbol is not implicitly quoted; add-to-list is an ordinary function, like set and unlike setq. Quote the argument yourself if that is what you want.

    Do not use this function when symbol refers to a lexical variable. 

I think this doc is unnecessary convoluted and I don't see reason why it
describes the implementation. That first sentence make something so
simple as add-to-list sound so complicated for some reason when you read
it, and requires one to think twice through what it say (at least me).

Other functions does not do so, so why this one? I don't think it is
necessary since docs anyway says how it add to list (front/back) kist a
three sentences further. 

I think it is more clear to use word 'list' instead of 'symbol' (element
is a symbol too for example). Not least because docs later says: "better
be a list". It clarifies intentions, and hopefully removes the need to say
things like 'better be a list'.

I hope I don't hurt anyone's feelings; I dont' know who wrote it, but I
would like to suggest a slight modification, patch included. I am not
native english speaker, so if you agree to change it, somebody please
look through it.


[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #2: add-to-list-doc.patch --]
[-- Type: text/x-patch, Size: 1787 bytes --]

diff --git a/doc/lispref/lists.texi b/doc/lispref/lists.texi
index ae793d5e15..c7f6a46aeb 100644
--- a/doc/lispref/lists.texi
+++ b/doc/lispref/lists.texi
@@ -761,22 +761,19 @@ List Variables
 
   Two functions modify lists that are the values of variables.
 
-@defun add-to-list symbol element &optional append compare-fn
-This function sets the variable @var{symbol} by consing @var{element}
-onto the old value, if @var{element} is not already a member of that
-value.  It returns the resulting list, whether updated or not.  The
-value of @var{symbol} had better be a list already before the call.
-@code{add-to-list} uses @var{compare-fn} to compare @var{element}
-against existing list members; if @var{compare-fn} is @code{nil}, it
-uses @code{equal}.
+@defun add-to-list list element &optional append compare-fn
+This function adds the @var{element} to a list @var{list} if
+@var{element} is not already a member of that value.  It returns the
+resulting list, whether updated or not.  @code{add-to-list} uses
+@var{compare-fn} to compare @var{element}  against existing list
+members; if @var{compare-fn} is @code{nil}, it uses @code{equal}.
 
 Normally, if @var{element} is added, it is added to the front of
-@var{symbol}, but if the optional argument @var{append} is
+@var{list}, but if the optional argument @var{append} is
 non-@code{nil}, it is added at the end.
 
-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.
+The argument @var{list} is not implicitly quoted; @code{add-to-list}
+is an ordinary function, like @code{set} and unlike @code{setq}.
 
 Do not use this function when @var{symbol} refers to a lexical
 variable.

^ permalink raw reply related	[flat|nested] 23+ messages in thread

end of thread, other threads:[~2020-12-06 14:01 UTC | newest]

Thread overview: 23+ messages (download: mbox.gz follow: Atom feed
-- links below jump to the message on this page --
2020-12-04  2:17 Lispref add-to-list - doc is unnecessary convoluted Arthur Miller
2020-12-04  2:27 ` Christopher Dimech
2020-12-04  2:36 ` Robin Tarsiger
2020-12-04  3:29   ` Arthur Miller
2020-12-04  3:35   ` Arthur Miller
2020-12-04  8:35     ` Lars Ingebrigtsen
2020-12-04  8:29 ` Eli Zaretskii
2020-12-04 15:28   ` Arthur Miller
2020-12-04 15:56     ` Robin Tarsiger
2020-12-04 16:14       ` Ad-hoc list structure tutorializing (was: Lispref add-to-list - doc is unnecessary convoluted) Robin Tarsiger
2020-12-04 20:24         ` Ad-hoc list structure tutorializing Stefan Monnier
2020-12-04 21:12           ` Christopher Dimech
2020-12-05  7:45             ` Eli Zaretskii
2020-12-06  5:45               ` Richard Stallman
2020-12-06  5:57                 ` Robin Tarsiger
2020-12-06 14:01                   ` Arthur Miller
2020-12-06  5:39             ` Richard Stallman
2020-12-04 21:40           ` add-to-list vs cl-pushnew Robin Tarsiger
2020-12-04 21:51             ` Robin Tarsiger
2020-12-04 22:47         ` Sv: Ad-hoc list structure tutorializing (was: Lispref add-to-list - doc is unnecessary convoluted) arthur miller
2020-12-04 17:03     ` Lispref add-to-list - doc is unnecessary convoluted Drew Adams
2020-12-04 17:24       ` arthur miller
2020-12-04 18:02         ` Drew Adams

Code repositories for project(s) associated with this public inbox

	https://git.savannah.gnu.org/cgit/emacs.git

This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).