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

[Stefan Monnier <monnier@iro.umontreal.ca>]

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

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

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

The other way around.

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

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

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.


        Stefan