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

[Drew Adams]

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