RE: tutorial or guidebook text for some complex topics

[Drew Adams]

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

I agree about that, of course: not opaque, and not obliging people to pick
things apart piece by piece, referring to the doc or other code as a roadmap
at every turn.

    That's why `map-keymap' was added, for example.

I'm very glad it was. Thank you, to whomever was responsible.

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

I don't have any particular suggestions to make here.

Yes, I agree about keyelt (though there might be a better name for that). I
was thinking of menu-item details like the prompt string, whether
`menu-item' is present, key-binding reminder (shortcut), and so on. The form
of a menu item is quite variable, and accessor functions could help reduce
that complexity (e.g. some combinations can only occur together).

I was reminded of this recently, when I discovered that Imenu used string
values instead of symbols, following symbol `keymap'.  The spec in the
manual allows for this, but AFAIK, this is the only place where that is
done. Code that treats keymaps in a general fashion has many different cases
to consider, largely for "hysterical raisins" (SM, 2006). Access functions
would address those cases.

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

GNU won't use my text, because my employer won't sign papers. I can
contribute suggestions to existing proposals, however, as well as general
ideas (like this one, to add some pedagogical doc for our complex but
important data structures).

I also will purposely try to stay out of this one to some extent, based on
the fiasco that occurred the last time I made tutorial suggestions. Instead
of considering the multiple suggestions made, we plunged down a rat hole of
anti-mouse alarmism. AFAIK, there was no constructive outcome, in spite of
some good suggestions. (Take that with a sense of humor, or don't bother to
take it at all, please.)

A start, I think, would be for interested people to contribute examples,
typical and perhaps not so typical (gotchas). Good examples can form the
core of a pedagogical text. We could discuss the examples first, and then go
on to discuss the narrative thread.

Another good way to start would be for someone to try to explain, using
examples, what the manual already says using a concise, rigorous
specification. For example, try explaining the syntax of font-lock-keywords
with examples of the various cases, perhaps using some existing code as
illustration.

This could be done here or, if people consider that a distraction, it could
be done on a page or two at Emacs Wiki. The wiki is a good place for
collaborative editing, but email is generally better for dialog.