[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
bug#12564: 24.1; Emacs Lisp Reference Manual; Confusing paragraph regard
From: |
Jambunathan K |
Subject: |
bug#12564: 24.1; Emacs Lisp Reference Manual; Confusing paragraph regarding association lists' definition; Section 20.6.1 "Basic Completion Functions"; 5th paragraph |
Date: |
Wed, 03 Oct 2012 18:18:25 +0530 |
User-agent: |
Gnus/5.13 (Gnus v5.13) Emacs/24.2.50 (gnu/linux) |
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''
--