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

[Arthur Miller]

Robin Tarsiger <rtt@dasyatidae.com> writes:

> 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.
Ok, I agree; my explanation is not that pedantic as you are describing
it; thank you for pointing it out, I wasn't so pedantic when I was
thinking about it, even if implicitly understand it is so. However, I
must ask is that distinction important in this particular case? I
understand you think so; but if you think twice or maybe three time?

I am not an lisp expert, and obivously I needed to look up exactly how
the thing worked, so I red it, despite being using it for very long now;
and I will try to explain how I percieve the issue:

This pedantic treatize of the language, which is more correct than what
I use, is surely correct and has merits, but is it necessary for the end
user; in this particular case? I think that pedancy in this case adds
more confusion then clarification.

I think that conceptually we think of adding to a list, not to a symbol
or to a list-var. At least me. The function name itself suggests we are
adding to a list. When we add to a linked list in C, we are actually
copying a value of an address into some other address in memory; but we
use term "add to list", because that term let us reason in terms of
higher abstraction. In this case cons is the primitve, symbol is our
pointer; so what is wrong to reason about that operation in higher
abstraction as of adding to the list?

I don't think LIST-VAR sounds much better (or worse), per se. It sounds
better in combination with "to the value of":

"Add ELEMENT to the value of LIST-VAR if it isn't there yet"

Maybe that should be in lispref docs instead; entire sentence. It is still
more clear than the current version. In my opinion. Opinions are subjective
:-).


> "cons onto" a list is more specific than "add to" in terms of where the new
> element winds up,
I agree that "cons onto" is more specific to how the operation is
implemented; but I don't think it is necessary for the user of the API,
nor is actually position really necessary; it just says "adds"; but as
you self note, it is mentioned afterwards anyway, which was one of
reasons I reflect over it.

We can add it to the comment below the function, where it shows alternative
implementation. I can agree that it is illustrative and more of a
"tutorial approach" so we don't need to throw it away completely; but I
think it is also important to be clear and concise, especially in the
opening to a function, which add-to-list is not. I can rewrite and add
that info to the end.

> 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?
It is always desired to make any programming documentation more
readable! :-).