Proposal to make font-locking easier to understand

[Alan Mackenzie]

I've experienced considerable difficulty in coming to grips with font-locking 
in the last few months.  I'm sure it shouldn't be that difficult.  I've
tried to analyse why it's difficult, and a short glib answer is that the
font-lock manual pages are less easy to understand than most.

However, I think that a big problem is that clear meaningful names
haven't been chosen for the things involved.  Even after months of
studying the man pages, my eyes still glaze over when I see
"font-lock-keywords" for example, and have to think very hard what the
"-keywords" means.  I see "font-lock-keywords-only", and I try to think
what sort of wierd concoction of regexps and matchers and specifiers and
what have you applies only to keywords, and how it differs from
"font-lock-keywords" itself.  The following quote from font-lock.el says
it all, I think:

> There are actually three passes; (a) the syntactic keyword pass, (b)
> the syntactic pass and (c) the keyword pass.  Confused?

Yes, extremely!  I would like to propose that things get renamed
sensibly, for example:

The "syntactic keyword pass" should become the "syntax-table-property pass";
..  "syntactic pass"         ................. "string pass";
    "keyword pass" should stay as it is, since it's self-explanatory once
the other confusing terms are cleared away.

"font-lock-keywords-only"  should become "font-lock-no-string-pass".
("...-keywords-only" has been an inaccurate name ever since the
syntax-table-property pass has existed) since the name doesn't clearly
suggest that the variable is a flag.)

"font-lock-keywords-case-fold-search" should become
"..-keywords-case-insensitive".  This makes clearer that we're talking
about a flag, not a regular expression used in searching, or a
user-supplied function which is to do this type of searching, or ....

"font-lock-syntactic-keywords" should become
"...-syntax-table-property-spec".  What exactly springs to mind with
"..-syntactic keywords"?  Is it a flag saying whether this pass should be
done?  Is it a function?.  And that's only after my poor brain's managed
to twig that we're talking about setting syntax-table properties.

-- 
Alan Mackenzie (Munich, Germany)
Email: aacm@muuc.dee; to decode, wherever there is a repeated letter
(like "aa"), remove half of them (leaving, say, "a").