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

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!

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

[Drew Adams]

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

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]

"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!

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

-- 

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

[Chong Yidong]

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

> The key affirmation is "... in Emacs Lisp, the elements of alists do not
> _have_ to be conses".

Thanks, fixed in trunk.