RE: tutorial or guidebook text for some complex topics

[Drew Adams]

        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.

    I did a lot of work on the keymap documentation in response
    to your last suggestion.  Is there any part of it which is
    still insufficient?

I doubt it. As far as reference material goes, it is good: accurate,
complete, concise.

I was suggesting more user-guide material or a tutorial - something along
the lines of the Emacs-Lisp Intro (but short). I suspect that only a
relatively small number of Emacs-Lisp programmers are comfortable with
keymaps in all their forms, and I think it would help Emacs development
(including 3rd-party features) for more people to be familiar with them.
That was the motivation.

    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.

    As for faces and text properties, they are very simple structurally.
    They are just plists.  What aspect of them do you find complex?

I don't know. I recall trying to wade through some code that examined font
specs (with defaulting, inheritance, merging etc.), and it seemed complex.
Perhaps it had to do with face-spec-reset-face and set-face-attribute. I
don't remember.