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

From: "Drew Adams" <[email-masked]>
Date: Tue, 2 Oct 2012 13:27:59 -0700

> 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.

> 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.