Re: Lispref add-to-list - doc is unnecessary convoluted

[Christopher Dimech <dimech@gmx.com>]

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