bug#34842: 26.1; Alist documentation: let-alist

[Sebastián Monía]

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.