[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
Re: Lispref add-to-list - doc is unnecessary convoluted
From: |
Christopher Dimech |
Subject: |
Re: Lispref add-to-list - doc is unnecessary convoluted |
Date: |
Fri, 4 Dec 2020 03:27:07 +0100 |
> Sent: Friday, December 04, 2020 at 3:17 AM
> From: "Arthur Miller" <arthur.miller@live.com>
> To: emacs-devel@gnu.org
> Subject: Lispref add-to-list - doc is unnecessary convoluted
>
> 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).
I concur.
> 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'.
Agree
> 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.
Not hurt. I shall read it and report back.
Cheers
C*