tutorial or guidebook text for some complex topics

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?

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

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.

RE: tutorial or guidebook text for some complex topics

[Nick Roberts]

 > GNU won't use my text, because my employer won't sign papers.

But presumably if you contribute in your own time from a separate e-mail
address they wouldn't need to sign papers.

-- 
Nick                                           http://www.inet.net.nz/~nickrob

RE: tutorial or guidebook text for some complex topics

[Drew Adams]

     > GNU won't use my text, because my employer won't sign papers.

    But presumably if you contribute in your own time from a separate e-mail
    address they wouldn't need to sign papers.

Someone knowledgeable can speak to that (I'm not a lawyer), but I doubt it.
I have offered code previously, explaining that it was created outside of
work (even years before I was employed), but that is not good enough.

IIUC, GNU does not want to take the chance that an employer might claim that
a contribution was made in the context of employment.

RE: tutorial or guidebook text for some complex topics

[Nick Roberts]

 > IIUC, GNU does not want to take the chance that an employer might claim that
 > a contribution was made in the context of employment.

If Oracle are paying you to work on Emacs or even write a tutorial or guidebook
on it, I can see there might be a problem.  If your work for them is not
related to Emacs then I can't.  It would be highly unusual for them to specify
what you do outside work.

-- 
Nick                                           http://www.inet.net.nz/~nickrob

RE: tutorial or guidebook text for some complex topics

[Drew Adams]

     > IIUC, GNU does not want to take the chance that an employer
     > might claim that a contribution was made in the context of
     > employment.

    If Oracle are paying you to work on Emacs or even write a
    tutorial or guidebook on it, I can see there might be a problem.
    If your work for them is not related to Emacs then I can't.
    It would be highly unusual for them to specify
    what you do outside work.

This is a sidebar, distracting from the real thread. I will respond, but I
don't want to extend the discussion.

My work is not related to Emacs. My employer specifies nothing about what I
do outside work. The company is simply unwilling to sign any papers,
probably thinking that there is nothing to be gained. I imagine that some
other large companies might have similar policies - lawyers run the show, to
some extent.

As I said, I am not a lawyer and am not knowledgeable in this area. RMS and
GNU legal people looked at this in detail for my case a couple of years ago.
I contribute my code freely (GPL) on Emacs Wiki, and I contribute general
ideas for Emacs development here.

RE: tutorial or guidebook text for some complex topics

[Nick Roberts]

Drew Adams writes:
 >      > IIUC, GNU does not want to take the chance that an employer
 >      > might claim that a contribution was made in the context of
 >      > employment.
 > 
 >     If Oracle are paying you to work on Emacs or even write a
 >     tutorial or guidebook on it, I can see there might be a problem.
 >     If your work for them is not related to Emacs then I can't.
 >     It would be highly unusual for them to specify
 >     what you do outside work.
 > 
 > This is a sidebar, distracting from the real thread. I will respond, but I
 > don't want to extend the discussion.

My aim is to stop `the real thread' as I don't find it appropriate to
continually suggest tasks, especially complex ones for after the release, when
you have no intention of doing them yourself.  In my opinion, its a distraction
for those who are contributing.  However, I'm sure Richard won't agree with me,
as the convenience of developers seems to come last on his list.

 > My work is not related to Emacs. My employer specifies nothing about what I
 > do outside work. The company is simply unwilling to sign any papers,
 > probably thinking that there is nothing to be gained.

And doesn't need to then if you contribute outside work.

 >                                                       I imagine that some
 > other large companies might have similar policies - lawyers run the show, to
 > some extent.

I imagine some people who work for them do contribute to Emacs in their own
capacity.

-- 
Nick                                           http://www.inet.net.nz/~nickrob

Re: tutorial or guidebook text for some complex topics

[David Kastrup]

Nick Roberts <nickrob@snap.net.nz> writes:

> Drew Adams writes:
>  >      > IIUC, GNU does not want to take the chance that an employer
>  >      > might claim that a contribution was made in the context of
>  >      > employment.
>  > 
>  >     If Oracle are paying you to work on Emacs or even write a
>  >     tutorial or guidebook on it, I can see there might be a problem.
>  >     If your work for them is not related to Emacs then I can't.
>  >     It would be highly unusual for them to specify
>  >     what you do outside work.
>  > 
>  > This is a sidebar, distracting from the real thread. I will
>  > respond, but I don't want to extend the discussion.
>
> My aim is to stop `the real thread' as I don't find it appropriate
> to continually suggest tasks, especially complex ones for after the
> release, when you have no intention of doing them yourself.  In my
> opinion, its a distraction for those who are contributing.  However,
> I'm sure Richard won't agree with me, as the convenience of
> developers seems to come last on his list.

If it is convenient not to hear about useful improvements, I would
share that sentiment.  I don't see a problem with Drew making
suggestions.  It is not like others (including myself) don't speak
ideas as they pop up.  The distracting thing is that he wants to have
them argued through to some finishing line and gets all defensive.
That's what spends time, effort and energy.

One advantage of this mailing list over Usenet is that the
participants are attentive, intelligent and decided enough that it is
mostly a waste of time to argue rather than present a point,
particularly when done repetitively.  When all has been said, it is
the time to move on.

-- 
David Kastrup, Kriemhildstr. 15, 44793 Bochum

Re: tutorial or guidebook text for some complex topics

[David Kastrup]

David Kastrup <dak@gnu.org> writes:

> Nick Roberts <nickrob@snap.net.nz> writes:
>>
>> My aim is to stop `the real thread' as I don't find it appropriate
>> to continually suggest tasks, especially complex ones for after the
>> release, when you have no intention of doing them yourself.  In my
>> opinion, its a distraction for those who are contributing.
>> However, I'm sure Richard won't agree with me, as the convenience
>> of developers seems to come last on his list.
>
> If it is convenient not to hear about useful improvements, I would
> share that sentiment.

Well, I can't make sense out of that last sentence, and I am its
author.  Probably was supposed to be something like "If `convenient'
is supposed to be synonymous with "not wanting to hear ideas about
useful improvements", I would join Richard when he happened to not
agree to bowing to convenience.

Maybe moving on is harder for Drew than for most developers here,
since his principal contributions _are_ suggestions and so he has
little else to move to.

-- 
David Kastrup, Kriemhildstr. 15, 44793 Bochum

RE: tutorial or guidebook text for some complex topics

[Drew Adams]

    Maybe moving on is harder for Drew than for most developers here,
    since his principal contributions _are_ suggestions and so he has
    little else to move to.

I have plenty to move to beyond my suggestions here, but thanks for your
concern ;-). I even have a life outside of Emacs, and not just when it
crashes ;-).

RE: tutorial or guidebook text for some complex topics

[Drew Adams]

    My aim is to stop `the real thread' as I don't find it appropriate to
    continually suggest tasks, especially complex ones for after
    the release, when you have no intention of doing them yourself.

I do intend to work on this. I brought up the idea (first contribution). I
offered to provide feedback on contributions by others (second
contribution). I offered suggestions about starting the task: examples and
logic come before words (third contribution).

Think of this as an opportunity, not a chore. If you're not interested, move
on; there is no need to try to "stop" the suggestion in its tracks (which
you appear to have done).

Imagine more Emacs programmers having a better idea what keymaps are like
structurally - is that a good thing or a bad thing? Is it worth enhancing
the doc? If it's not worth it to you, do you think you should stop others
who might think it worthwhile - in the name of preventing them from being
distracted from their important work?

I specifically proposed this for after the release, to try to forestall such
a knee-jerk reaction - to no avail. And I proposed taking the discussion and
work on this off the list, to Emacs Wiki.

Concerning my contribution - I've suggested lots of possible new features
and other improvements, and I'll continue to do so. In some cases, I've been
waiting 2 years for the release to be out before I suggest some features
(you've been warned!).

I consider that to be a constructive contribution, whether or not each of my
suggestions is implemented. In many cases, I've implemented the features
myself, and I provide well-documented source code freely, to serve as food
for thought for others. I spend a lot of time documenting my code, in hopes
that that will help others to move further.

It happens that any text or code I write won't be used by GNU, but I can
contribute abstract ideas - so I do that. I make suggestions and I report
bugs, but I don't decide what others must or must not work on (that's
effectively what you did, BTW). I've argued against some ideas, but I have
not tried to stifle their consideration.

    In my opinion, its a distraction for those who are contributing.

You have a very narrow idea of who is contributing, or even what
contributing means. Just reading this mailing list, without even posting, is
a contribution: people learn, think, and share with others (on and off
list), and that means progress. Sending a bug report is contributing. Asking
a question is contributing. Thinking about a problem is contributing.

It's never obvious how progress moves; if you think you see that movement
clearly, then you are deluding yourself. If you think only a couple dozen
"Emacs developers" are developing Emacs, then you are deluding yourself, and
you have an exaggerated idea of your own relative contribution (which is no
doubt great, in absolute terms).

    However, I'm sure Richard won't agree with me,
    as the convenience of developers seems to come last on his list.

We are all developers of Emacs, and no one of us has a sure-fire recipe for
what is convenient for all of us or best for Emacs development as a whole.
That goes for RMS as well (as I'm sure he is well aware).

Re: tutorial or guidebook text for some complex topics

[Robert J. Chassell]

    IIUC, GNU does not want to take the chance that an employer might
    claim that a contribution was made in the context of employment.

Yes, that is the problem.  I met a woman who was fighting a company
because they claimed her Ph.D. dissertation was owned by them, not by
her.

-- 
    Robert J. Chassell                          GnuPG Key ID: 004B4AC8
    bob@rattlesnake.com                         bob@gnu.org
    http://www.rattlesnake.com                  http://www.teak.cc

Re: tutorial or guidebook text for some complex topics

[Richard Stallman]

    Someone knowledgeable can speak to that (I'm not a lawyer), but I doubt it.
    I have offered code previously, explaining that it was created outside of
    work (even years before I was employed), but that is not good enough.

We do not need papers from Oracle for work that you did before
starting to work there.  However, if you had other employers at those
times, we may need disclaimers from them.

The employer that is relevant to a given piece of work is the employer
you have at the time you do the work.

RE: tutorial or guidebook text for some complex topics

[Drew Adams]

        Someone knowledgeable can speak to that (I'm not a lawyer),
        but I doubt it. I have offered code previously, explaining
        that it was created outside of work (even years before I
        was employed), but that is not good enough.

    We do not need papers from Oracle for work that you did before
    starting to work there.  However, if you had other employers at those
    times, we may need disclaimers from them.

    The employer that is relevant to a given piece of work is the employer
    you have at the time you do the work.

That was precisely the case that you reviewed a couple of years ago. The
code in question was the fit-frame stuff, which was written before my
current employment. However, you requested changes to that code (e.g.
renamings), and then you stated that because I had made those changes I
needed papers from my current employer.

The need for previous-employer signoff was not mentioned at that time, IIRC.
In any case, I'm sure you'll never get papers from my previous employers
(most of the companies were either bought or went out of business). Some of
my code was written decades ago (several employers ago), but I have made
improvements to it as the years have gone by, including recently - and that
apparently means my current employer would need to sign. I have always
worked, and I've coded Emacs for decades - outside of my work. But you will
never get a past employer to sign a disclaimer, and my current employer
won't do that either.

FWIW - I am willing to contribute my code. I believe that Oracle does not
care if I contribute - my Emacs code has no relation to my job. IIUC, GNU
will not accept a contribution without Oracle signing a disclaimer. Oracle
refuses to sign. And when I become no longer employed by Oracle (after I win
the lottery), the situation will apparently not have changed. And if, after
my employment at Oracle is finished, I update code that I am writing now,
GNU will want papers from the next employer too.

I understand why GNU adopts this position, BTW.

My understanding is that Oracle's unwillingness to sign is not motivated by
any desire to lay claim to my intellectual product in this area, but because
of some potential or perceived (though inarticulated) risk to Oracle. My
guess is that the legal department sees only possible risk and no gain -
better safe than sorry. (GNU also sees possible risk, but with presumably
some gain.) My managers up to the VP level are not opposed to my
contributing, but the VP will not sign the disclaimer because the legal
department advises him not to.

I imagine that this situation is not unique to me, and that's unfortunate.
Fortunately, there are others who are in a different situation.

This was your position, BTW:

  You should not write any code, or any text for manuals.  It is
  ok to suggest ideas *in the abstract* because they are
  not copyrightable.

  As long as you can't get a disclaimer, I have to ask you to
  please NOT post Emacs patches.  If you do, we have to be careful
  not to read them.

I've respected that. On the bright side, any ideas I suggest can no doubt be
implemented by Emacs developers in a better way than I have implemented
them. And others can play with my code, use its features as inspiration for
better features, and perhaps feed those ideas and implementation into Emacs.
There are many ways to contribute, and my code is not necessarily the best
contribution I can make anyway.

Re: tutorial or guidebook text for some complex topics

[David Kastrup]

Nick Roberts <nickrob@snap.net.nz> writes:

>  > GNU won't use my text, because my employer won't sign papers.
>
> But presumably if you contribute in your own time from a separate
> e-mail address they wouldn't need to sign papers.

Your employee contracts might preclude something like "your own time".
If you think of just not telling the FSF: the assignment contract
holds you accountable for making wrong statements.  You'd have to pay
the damage.

So better make sure that everything is as it should be.

-- 
David Kastrup, Kriemhildstr. 15, 44793 Bochum

Re: tutorial or guidebook text for some complex topics

[Richard Stallman]

    But presumably if you contribute in your own time from a separate e-mail
    address they wouldn't need to sign papers.

Don't make that assumption!  It is not necessarily safe.  The answer depends
on details including the details of the employment contract.

We make these decisions based on legal advice from lawyers.

Re: tutorial or guidebook text for some complex topics

[Stefan Monnier]

> GNU won't use my text, because my employer won't sign papers.

Have you tried to send an email to your employer requesting the signed
papers every time you send an email to emacs-devel?


        Stefan

Re: tutorial or guidebook text for some complex topics

[Eli Zaretskii]

> From: "Drew Adams" <drew.adams@oracle.com>
> Date: Mon, 23 Oct 2006 11:35:12 -0700
> 
> Suggestion for after the release -

Suggestions for improving the docs don't need to be postponed until
after the release, since docs changes can never screw the program.

> 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 tutorial is always a good idea, IMO, but the problem is that
too few people ``in the know'' know how to write good tutorials and/or
have enough time to do the job.  Volunteers are welcome, as always.

RE: tutorial or guidebook text for some complex topics

[Drew Adams]

    > Suggestion for after the release -

    Suggestions for improving the docs don't need to be postponed until
    after the release, since docs changes can never screw the program.

Fine with me, but:

- The release is imminent (hope springs eternal), and coming up with
  such a doc would take some time.

- Even if it can't break anything, it's better for doc to be
  correct, and checking that takes time too.

- Someone might feel that the doc effort distracts from finishing
  the release ;-).

    Adding tutorial is always a good idea, IMO, but the problem is that
    too few people ``in the know'' know how to write good tutorials and/or
    have enough time to do the job.  Volunteers are welcome, as always.

See my other mail about why I'm not volunteering to do the writing myself. I
will be glad to make suggestions about writing proposals from others, if
that helps.

99% of the writing is getting the thoughts right, in particular, examples
and the order of presentation (learning). That is, it's about the teaching
logic more than the words. There is little sense starting with the wording,
ever. This means that people who are not native English speakers can
nevertheless make contributions to the most important part (99%).

Someone knowledgeable about keymaps or font-lock-keywords or faces/text
properties could make a proposal of what is important to teach about that
and what examples might be appropriate, and those of us who are less
knowledgeable could then contribute text or feedback. Or, someone who is
non-expert could propose logic and examples, and have them corrected by
those who are more expert.

Re: tutorial or guidebook text for some complex topics

[Richard Stallman]

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

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

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.

Re: tutorial or guidebook text for some complex topics

[Richard Stallman]

    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?

	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?

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.

Re: tutorial or guidebook text for some complex topics

[Richard Stallman]

    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.

Whenever you are ready to spend time on Emacs, this would be a good
choice of task to work on.  It would directly lead to progress
on something you asked for.