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

[Arthur Miller]

Eli Zaretskii <eliz@gnu.org> writes:

>> From: Arthur Miller <arthur.miller@live.com>
>> Date: Fri, 04 Dec 2020 03:17:19 +0100
>> 
>> +This function adds the @var{element} to a list @var{list} if
>
> This will produce "... to a list LIST if ...", which is sub-optimal.
>
> You omitted the part where the current doc string warns against an
> argument that is not a list, and that's losing information.
Yes, it was on purpose, partly because hopefully the argument name LIST is
self-documenting and partly because name of the function says
add-to-list which is self-documenting too. Partly because I also dislike
the wording: "better be a list". Does not sound so proffsy to me; but we
can add description for the argument, and change name to LIST-VAR as
suggested. Maybe the argument should be called LIST-NAME

Another question, why doesn't add-to-list take a list value, why symbol?
Maybe I don't understand lisp enough, but why is this not desirable:

(add-to-list '(1 2 3) '4) or (add-to-list (list 1 2 3) 4)

>> -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}.
>
> Not sure why you want to drop the explicit suggestion to quote the
> list symbol here: it's also losing information.
Mostly because I think it is rather description of implementation and
also because I dislike the wording:

"Quote the argument yourself if that is what you want."

"If that is I want"? :-) If I don't want - is it not needed then? :-)

Is LIST-NAME ok suggestion? And I can put back info about it's value and
quote. Will have to do it tomorrow though.