Subject: 24.0.50; doc for `font-lock-maximum-decoration'

From: "Drew Adams" <[email-masked]>
Date: Fri, 27 Aug 2010 21:06:09 -0700

The doc for `font-lock-maximum-fontification' is not very
clear/complete.
 
1. For one thing, the Emacs manual deals with it only using a `setq'
example:
 
  (setq font-lock-maximum-decoration
        '((c-mode . 1) (c++-mode . 1)))
 
We should tell users how they can use Customize for customizing it.
(No, it is not obvious how to do that.)  We should not be privileging
Lisp code in .emacs this way - especially fairly complex Lisp code.

2. The doc string and the Customize help for it (same thing) do not help
much either.  In particular, they are missing the info that if you add
an entry for one or more modes, then you will likely want to also add
a catch-all entry for all other modes.
 
The latter notion is not presented explicitly, but the example given
does help in this regard.  One problem is that the choice of `all' as
the UI label gives the impression that it might override other,
mode-specific entries.  For example, you might well think that order is
important and that an entry of `all' overrides any other entries that
follow.  `all' should really be renamed something that conveys the fact
that it means `all other modes', not `all modes'.

3. Also, to understand what the choice of `level' means here, users need
to know about fontification levels.  At least a minimum of info about
that needs to be presented in the Customize (= doc string) help.

In GNU Emacs 24.0.50.1 (i386-mingw-nt5.1.2600)
 of 2010-08-16 on 3249CTO
Windowing system distributor `Microsoft Corp.', version 5.1.2600
configured using `configure --with-gcc (4.4) --no-opt --cflags
-Ic:/imagesupport/include'