bug#6935: 24.0.50; doc for `font-lock-maximum-decoration'

[Drew Adams]

> >> we should work harder to make sure that the default level is OK
> >> for everyone.
> 
> > That's silly.  If there is a _default_ level then there are level
> > choices and a notion of level.
> 
> Not silly at all: if the default level is OK for everyone, there's no
> need for the notion of "levels".

If the default level is OK to everyone as a _default_ level, that does not imply
that that level is OK for everyone for their individual use.

As one member of everyone, I'm OK with a very minimal level of fontification as
the default for emacs-lisp-mode, but I'm not OK with using that level for
myself.  Being OK with having level X as the default is not the same as being OK
with using level X.

And no, everyone does not agree about which fontification level/degree/feature
_they_ should use.  One size does not fit all.

> > No one disagrees that the default level should provide 
> > minimal fontification.
> 
> I do.  And many others as well.  That's why the default is and has
> always been to use the highest level there is.  And even with this
> default, gnu.emacs.help was full (for several years, don't know about
> recent cases) of recommendations to add (setq
> font-lock-maximum-decoration t) to the user's .emacs.

Dunno whether you are right about what the default has been.  Typically, Emacs
-Q default settings have been minimal in angry-fruit-salad effects, but you
might be right wrt font-lock levels.

Irregardless of what the default values have been, the ability for users to set
the level they want is what you have put in question.  That is where the
disagreement is.

> > The point is to allow users to move to a higher level if 
> > they so wish.
> 
> The other way around.

Either way.  The point is to allow users a choice of level.

But apparently you are saying that the point is to allow users to move to a
_lower_ level if they so wish.  We can agree on that then.  Users deserve to
choose the level they want.  If the default is high, as you say, then they
should be able to choose lower, as you (apparently) claim.

But you apparently disagree with yourself in that case, since you argue both for
letting them move to a lower level and not letting them change level at all (no
levels).

> >> - "level" is the wrong way to think about this.  Instead, we 
> >> should have separate controls for different font-lock features.
> 
> > Be specific.  If you are agreeing that users should have choice and
> > control when it comes to the degree of font-locking, and you just
> > disagree with the current "level" mechanism, then propose
> > something specific.
> 
> That's exactly what the above does: use separate controls (e.g. bool
> vars) for different features.

Be specific.  Which different font-lock features for which mode?  You're just
hand-waving, saying that we could split fontification into a set of "features"
rather than a set of levels.  Sounds fine at that level of abstraction (simply
replacing numeric "levels" by boolean "features"), but the proof is in the
pudding.

> > Note that in the case I cited the user had the ability to fine-tune
> > fontification, for example by customizing individual faces.  But he
> > wanted a coarse-grain control, to change the _level_.
> 
> I don't know that case, so can't judge why he wanted to change the
> level, nor why he wanted this control to be coarse.
> 
> The notion of level is wrong, because there are different ways to
> characterize the complexity of fontification.  E.g. one of them is the
> amount of work done to determine how to highlight the text, another is
> the number of distinct elements.

Another is the visual effect for the user: how much is highlighted, and what is
highlighted or not.

> The two aren't necessarily connected
> (I almost always want my highlighting to be as precise as 
> possible, but I generally only want very few elements to be highlighted).

Sure, there are lots of such considerations.  I don't oppose a superior design
that gives users _more_ control over what gets highlighted, where, how much,
etc.

But where's the beef?  Where's the specific proposal?  Don't just say we should
drop the user control we do offer without offering something better.  If you
give users more control, great.  And not just more fine-grained control, but the
ability to easily chunk that the way they want (into features, levels or
whatever).

> BTW, from what you say, the notion of level was not needed for his
> problem since he could get the same result by tweaking faces.
> Now tweaking faces on a per-mode basis is not always easy, so we may
> need to improve this, but at least this case doesn't seem to 
> be one that justifies the necessity of levels.

Justify the necessity?  Don't be silly.  Emacs itself, and its faces,
fontifications, etc. are _not necessary_.

Changing the level can turn off (or on) lots of regexp processing and the
corresponding use of lots of faces - in this case faces that are used only by
one level and not the other.

Without this separation of regexp processing into two or more groups (levels),
the user would need to customize lots of individual faces to get the effect of
turning off their highlighting.  And that still would not have relieved him of
the processing time for matching their regexps, even if the result were, in
effect, not to highlight any such matches.

A user might want some fontification - some regexps to be matched and their text
highlighted, but not want some other fontification.  However you want to do it
(combine regexp sexps in an easy, customizable way? boolean "features"?
whatever), we should give users the ability to choose (in chunks) what gets
fontified.

As I said earlier, it would be ideal to give users an easy way to define their
own fontification levels or features or groups or whatever.  We're not there
yet.  I'm all in favor of something better than hard-coded levels.  I'm not in
favor of dropping levels in favor of nothing, while ostensibly waiting for pie
in the sky.