From: Drew Adams <drew.adams@oracle.com>
To: "Sebastián Monía" <seb.hoagie@outlook.com>, 34842@debbugs.gnu.org
Subject: bug#34842: 26.1; Alist documentation: let-alist
Date: Wed, 13 Mar 2019 08:16:28 -0700 (PDT) [thread overview]
Message-ID: <3c296021-c231-4c62-b8e3-0e870cb224cc@default> (raw)
In-Reply-To: <BN8PR04MB555503D4DD1283F20EAC7C578B4A0@BN8PR04MB5555.namprd04.prod.outlook.com>
> In [(elisp)`Association Lists'] we should add some
> documentation about [macro `let-alist']. Below a
> suggestion.
1. I agree that it might be good to document this
macro in node `Association Lists'.
2. But the example suggested is much less clear
than the example in the doc string.
3. The example in the doc string is itself not
correct. Instead of "essentially" it should just
show the actual macroexpansion. And it should
use a different variable name than `alist'. E.g.:
(let-alist my-alist
(if (and .title .body)
.body
.site
.site.contents))
expands to:
(let ((alist my-alist))
(let ((\.title (cdr (assq 'title alist)))
(\.body (cdr (assq 'body alist)))
(\.site (cdr (assq 'site alist)))
(\.site\.contents
(cdr (assq 'contents
(cdr (assq 'site alist))))))
(if (and \.title \.body)
\.body
\.site
\.site\.contents)))
(And yes, the backslashes are necessary.)
4. The last paragraph of the doc string is unclear.
What does "access alists inside the original alist"
mean? How is anything it tries to describe
"displayed in the example above", which has NO
nesting of `let-alist'?
Whatever it might be trying to say, if the point of
the last paragraph is important, then perhaps an
example of such nesting is called for, pointing out
what is meant.
Perhaps such a paragraph and example don't need to
be in both the doc string and the manual (dunno
how important this is, not knowing what it's really
trying to say).
5. The doc (manual and doc string) should explicitly
say that `assq' is used, not `assoc'. It should not
just hand-wave about this, saying "search is done".
And it should say what it means by "this search is
done at compile time" - what the consequences of this are.
next prev parent reply other threads:[~2019-03-13 15:16 UTC|newest]
Thread overview: 13+ messages / expand[flat|nested] mbox.gz Atom feed top
2019-03-13 14:16 bug#34842: 26.1; Alist documentation: let-alist Sebastián Monía
2019-03-13 15:16 ` Drew Adams [this message]
2019-03-13 16:30 ` Sebastián Monía
2019-03-13 17:51 ` Drew Adams
2019-03-14 4:47 ` Sebastián Monía
2019-10-12 23:32 ` Lars Ingebrigtsen
2019-10-13 2:03 ` Basil L. Contovounesios
2019-10-13 2:48 ` Lars Ingebrigtsen
2019-10-13 7:15 ` Eli Zaretskii
2019-10-13 12:38 ` Basil L. Contovounesios
2019-10-13 13:15 ` Eli Zaretskii
2019-10-13 12:17 ` Basil L. Contovounesios
2019-10-13 17:39 ` Lars Ingebrigtsen
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=3c296021-c231-4c62-b8e3-0e870cb224cc@default \
--to=drew.adams@oracle.com \
--cc=34842@debbugs.gnu.org \
--cc=seb.hoagie@outlook.com \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
Code repositories for project(s) associated with this external index
https://git.savannah.gnu.org/cgit/emacs.git
https://git.savannah.gnu.org/cgit/emacs/org-mode.git
This is an external index of several public inboxes,
see mirroring instructions on how to clone and mirror
all data and code used by this external index.