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

[Drew Adams]

> > > why doesn't add-to-list take a list value, why symbol?
> >
> > That's its specific purpose: update the value
> > of a (list-valued) _variable_.  It's all about
> > a variable - updating its value.
> >
> > The doc is very clear:
> > https://www.gnu.org/software/emacs/manual/html_node/elisp/List-Variables.html
> >
> > Please read the entire topic (node).
>
> I understand the obvious

I'm not sure you do.  Or maybe it's not so obvious.

I suggest you read that manual node again.  I'm not
talking about the doc string.  It's important to
read about all of what's in that node, as the things
presented are related - you can compare and contrast
them to better understand what each is for (what it
does).

> Was it necessary for some reason that I don't
> understand to design this function this way?
> Or could have just taken a list from the very beginning?

It's not about modifying a list.  And it's not about
consing an element onto a list.  It's about consing
an element onto a list that is the value of a
_variable_ and reassigning that variable to the
result.

A function that takes only a list as arg has no way
of assigning any value to a _variable_.

This function (and it is a function, unlike, say,
`setq') takes a _symbol_ as arg - a symbol whose
value as a _variable_ is a list.  And it returns
the same symbol, after changing its value to be a
list that has the argument value as car and the
original value (list) as cdr.

That's all.

You can compare it with the macro `push', if you
like.  That macro has, as its second arg, a _place_,
which can be, for example, a variable.  It adds a
value to the list that's stored in the place.

If the place is a variable then that list is the
value of the variable.  For a variable, `push'
thus updates the value of a list-valued variable
to be a list whose car is the argument value and
whose cdr is the original value (list).

The essential difference between `add-to-list'
and `push' (in the case of pushing to a variable
place) is that the former is a function and the
latter is a macro.  You can pass a sexp as first
arg to `add-to-list', and it gets _evaluated_ to
provide the variable to use.