tutorial or guidebook text for some complex topics

[Drew Adams]

Suggestion for after the release -

There are a few fundamental data structures that Emacs uses that are quite
complex and variable in form. I'm thinking of things like keymaps (including
menus), font-lock-keywords, and faces/text properties.

These complex structures are generally specified accurately in the Elisp
manual. However, it is not always easy to learn about them by simply reading
such a rigorous specification.

My own experience, at least, bears that out. I've spent quite a bit of time
trying to grasp what these things are and the various forms they can take,
and most of my (still incomplete) understanding of them has come from coding
and examining code that manipulates them.

These structures are complex, with multiple possible cases to consider. They
are not abstract data types with defined accessor functions, so code that
manipulates them must explicitly "parse" them as cons trees, being careful
at each access step.

Personally, I'd prefer to see them treated as ADTs with accessor functions,
but I expect that others will disagree, so I'm not suggesting that change.

What I would suggest is that the documentation be beefed up a little, to
help users understand these critters better. I'd like to suggest that these
topics be dealt with in a tutorial or user-guide manner, with examples to
help people learn what these critters can look like and how to use them.

Adding pedagogical doc for each of these (and there may be some others)
would help, but that doc probably doesn't belong in the Elisp manual, which
is essentially a reference manual. A separate document or documents would
likely be appropriate. An analogy is the Emacs-Lisp Intro book, which leads
you by the hand to learn some Emacs-Lisp. I don't know if that book would
itself be a good target for these topics, or if, instead, a separate
document would be better.

WDOT? Anyone else think that we could use some more explanation for these
topics?