Re: tutorial or guidebook text for some complex topics

[Stefan Monnier]

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

I think that if you propose good accessor (and constructor) functions, they
have a good chance of being accepted.  There's opposition to making data
structures opaque, but that doesn't mean that you should *have* to look
under the hood.
That's why `map-keymap' was added, for example.
AFAIK, regarding keymaps, the main missing accessor function is the one that
parses a "keyelt" (which can be as simple as a function symbol, but as
complex as a big `menu-item').

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

You're in the best position to start writing this.  If you feel like you're
not up-to-the-task, try it anyway and let other people's feedback do the
grunt of the work.


        Stefan