RE: tutorial or guidebook text for some complex topics

[Drew Adams]

        I was suggesting more user-guide material or a tutorial -
        something along
        the lines of the Emacs-Lisp Intro (but short).

    The place for such material about keymaps is in the Lisp manual.  What
    concepts about keymaps do you think need further tutorial explanation?

Just the structure, with all its possible variations that one might run
into. As mentioned before:

    (Stefan)
    "keyelt" (which can be as simple as a function symbol,
    but as complex as a big `menu-item').

    (Drew)
    Yes...
    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....

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

        I think the documentation of font-lock-keywords is complete.
        I agree it is hard to grasp, but I don't know how to make
        it clearer.  Does anyone else have an idea?

        Yes, it is probably complete. I was speaking only to the
        hard-to-learn part.

        The best help is provided by walking a reader through
        examples. Examples are the place to start. Again, see the
        Emacs-Lisp Intro for a good presentation model.

    Can you find a few examples in the code that you think would be
    good for explaining this?

I don't have the time to do that right now. I'm not sure existing code
should be used as is for such examples, but it might not be a bad place to
start to look for raw material. I just don't have the time to dig for it
now.

Again, what's needed is to describe the different possible variations, with
examples.