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

[Jambunathan K]

oitofelix@gmail.com (Bruno Félix Rezende Ribeiro) writes:

> This bug report will be sent to the Bug-GNU-Emacs mailing list
> and the GNU bug tracker at debbugs.gnu.org.  Please check that
> the From: line contains a valid email address.  After a delay of up
> to one day, you should receive an acknowledgement at that address.
>
> Please write in English if possible, as the Emacs maintainers
> usually do not have translators for other languages.
>
> Please describe exactly what actions triggered the bug, and
> the precise symptoms of the bug.  If you can, give a recipe
> starting from `emacs -Q':
>
> In GNU Emacs Lisp Reference Manual, section 20.6.1, entitled "Basic
> Completion Functions", in the 5th paragraph one can read:
>
>   If COLLECTION is an alist (*note Association Lists::), the
>   permissible completions are the elements of the alist that are
>   either strings, or conses whose CAR is a string or symbol.
>   Symbols are converted to strings using `symbol-name'.  Other
>   elements of the alist are ignored.  (Remember that in Emacs Lisp,
>   the elements of alists do not _have_ to be conses.)  In
>   particular, a list of strings is allowed, even though we usually
>   do not think of such lists as alists.
>
> The key affirmation is "... in Emacs Lisp, the elements of alists do not
> _have_ to be conses".
>
> 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)
>
> The key affirmation here is "... It is [association lists] a list of
> cons cells ...".
>
> Hence, we conclude an association list is a list of cons cells that
> doesn't need to be cons cells.  If we assume the manual is consistent,
> we only can infer, supposing a language abuse, the following:
>
> An association list is any sort of list.
>
> or, perhaps more appropriate,
>
> 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.

[OT] Hoping to be of help to the OP.  Maintainers please skip.

I wouldn't question why you are confused.  I get confused by terms like
cons cells, alist, lists etc all the time.  I have a mental model that I
resort to when I see myself stuck or confused (See postscript below)

A typical user is unlikely to get good at both Shakespeare and English
alphabet together.  I don't mean it in a patronizing and condescending
way.

The comment in the completions section that you cite, (is probably
trying) to bring attention to a case that a consumer of the API
shouldn't overlook or the implementor of the API has specially provided
for.  Do you think a footnote would be a much better?

What I suggest is, you ask help in the Emacs help forum citing the
particular code that you are trying to get a handle on.  Once that is
conquered, re-visit this bug and provide a re-write of some sentences in
a way that would have helped you in the first place.

ps: (If you are a C-programmer) you can visualize cons cells, alists and
lists in terms of linked lists, pointers and value types.  This mental
model will be very useful to short-circuit the Elisp jargon altogether
and work around seemingly contradictory use.

> Thanks.
>
> In GNU Emacs 24.1.1 (i686-pc-linux-gnu, GTK+ Version 2.24.10)
>  of 2012-08-26 on felix-laptop
> Windowing system distributor `The X.Org Foundation', version 11.0.10903000
> Configured using:
>  `configure 'CFLAGS=-pipe -O3 -march=atom -mtune=atom -mmmx -msse -msse2
>  -msse3 -mssse3 -mfpmath=sse''

--