bug#12564: 24.1; Emacs Lisp Reference Manual; Confusing paragraph regarding association lists' definition; Section 20.6.1 "Basic Completion Functions"; 5th paragraph

[oitofelix@gmail.com (Bruno Félix Rezende Ribeiro)]

"Drew Adams" <drew.adams@oracle.com> writes:

>> In the paragraph's first sentence there is a reference to section 5.8
>> "Association Lists" in the same manual, where one can read in 
>> the first paragraph:
>> 
>>   An "association list", or "alist" for short, records a mapping from
>>   keys to values.  It is a list of cons cells called 
>>   "associations": the CAR of each cons cell is the "key", and the
>>   CDR is the "associated value".(1)
>
> And where one can read the following qualification, in the eighth paragraph:
>
>    In Emacs Lisp, it is _not_ an error if an element of an association
>    list is not a cons cell.  The alist search functions simply ignore such
>    elements.  Many other versions of Lisp signal errors in such cases.
>
> You have to read beyon the intro at the beginning, to get to the details.
>
> The intro gives the basic idea and an illustrative example.  The corner case
> (ignoring a non-cons element vs raising an error) is mentioned later.  And
> that's the right presentation order, IMHO.

Yes, I actually had read that paragraph, but it's a different matter.
My bug report concern the association list definition that seems to be
given in the first paragraph, not an Emacs Lisp implementation detail,
which the 8th paragraph is about.

If the 8th paragraph was something to do with the definition, we can
conclude that an association list is just any list.  But I think it
would make the association list term useless.

Independently of Emacs Lisp specific conditions, in determined functions,
to signal errors, what is an association list?

Lets be more concise and consider the first paragraph and the 8th that
you cited.  Lets suppose the first paragraph gives the definition and
the eight just one reservation (what seems in fact).  Then, for the
manual consistence sake, that quote I had indicated as possible
inconsistent, from section 20.6.1, where one can read:

(Remember that in Emacs Lisp, the elements of alists do not _have_ to be
conses.)

has nothing to do with the definition, but with the reservation.  Thus,
it would be better if it were changed to something like:

(Remember that in Emacs Lisp, it is _not_ an error if an element of an
association list is not a cons cell.)

>
>> An association list is any list that has none elements or at least one
>> cons cell and possibly other elements.
>> 
>> Since I don't know what is the case, either I'm missing 
>> something trivial, or that is a manual bug.  Even if it's
>> consistent, I think it could be more clear.
>
> This is called _jumping to conclusions_ before reading the entire presentation
> of the topic.  It can be risky, as this experience shows.
>

If you think so...

-- 
 ,= ,-_-. =.  Bruno Félix Rezende Ribeiro (oitofelix)
((_/)o o(\_)) Uns o chamam de super-vaca...
 `-'(. .)`-'  Outros de hiper-touro...
     \_/      Eu o chamo simplesmente: meta-gnu!