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

[Bruno Félix Rezende Ribeiro]

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.

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

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