From: "Sebastián Monía" <seb.hoagie@outlook.com>
To: "34842@debbugs.gnu.org" <34842@debbugs.gnu.org>
Subject: bug#34842: 26.1; Alist documentation: let-alist
Date: Wed, 13 Mar 2019 16:30:16 +0000 [thread overview]
Message-ID: <BN8PR04MB5555A95657B2651F4689FE408B4A0@BN8PR04MB5555.namprd04.prod.outlook.com> (raw)
In-Reply-To: <3c296021-c231-4c62-b8e3-0e870cb224cc@default>
[-- Attachment #1: Type: text/plain, Size: 2435 bytes --]
I thought that the example in the docstring was too long compared to the smaller/simpler examples in the rest of the page, but wouldn't be against using that instead if it's more clear.
The nested access example is in .site.contents, maybe being explicit about which line displays the concept would be a nice improvement.
And most of what you said in point 5 is above my level so I will defer to people with more knowledge.
Thank you for your feedback Drew!
---------------------------------------------------
Why Emacs?
http://david.rothlis.net/emacs/why.html
From: Drew Adams
Sent: Wednesday, March 13, 9:16 AM
Subject: RE: bug#34842: 26.1; Alist documentation: let-alist
To: Sebastián Monía, 34842@debbugs.gnu.org
> 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.
[-- Attachment #2: Type: text/html, Size: 4473 bytes --]
next prev parent reply other threads:[~2019-03-13 16:30 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
2019-03-13 16:30 ` Sebastián Monía [this message]
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=BN8PR04MB5555A95657B2651F4689FE408B4A0@BN8PR04MB5555.namprd04.prod.outlook.com \
--to=seb.hoagie@outlook.com \
--cc=34842@debbugs.gnu.org \
/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.