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

[Robin Tarsiger]

Arthur Miller wrote:
> 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'.

The first argument is not itself a list. The value (as in symbol-value) of
the first argument is expected to be a list. The first sentence of the
documentation has that many levels of indirection because that's how many
levels of indirection there actually are in the behavior of the function.
Your new text does not describe it correctly.

"cons onto" a list is more specific than "add to" in terms of where the new
element winds up, though the paragraph describing the APPEND argument
also mentions this, so it's not strictly necessary.

But while looking at this, I notice that the C-h f docstring for add-to-list
that I see on my Emacs names the first argument more clearly as LIST-VAR
(neither the correct-but-overbroad SYMBOL nor the incorrect LIST), and has
the first sentence "Add ELEMENT to the value of LIST-VAR if it isn't there
yet", which seems to hit both of the points you're dissatisfied with.
Might that be a better starting point if making the elisp Info entry
more readable is desired?

-RTT