bug#20613: Font locking is poorly documented

[Paul Eggert <eggert@cs.ucla.edu>]

I was recently urged to use font locking to support a feature in Emacs, 
and I must say that I am still confused about how it works even after 
reading the Elisp manual several times.  The manual has a lot of 
low-level discussion of mechanism, but it doesn't explain policy and 
since crucial features seem to be undocumented, I'm at a loss as to how 
to use it, or how to debug it when it's not working. I finally gave up 
and used Google and found cookbook stuff, but I have no idea how or why 
it works as well as it does, or why it fails when it does.  For example:

http://www.emacswiki.org/emacs/PrettyLambda

gives this example:

(defun  pretty-lambdas  ()
   (font-lock-add-keywords
    nil `(("(\\(lambda\\>\\)"
           (0 (progn  (compose-region (match-beginning 1) (match-end 1)
                                     ,(make-char 'greek-iso8859-7 107))
                     nil))))))

but I can't find documentation explaining why a progn is needed, or why 
it must return niil, or why one must use compose-region, or why one must 
use it with a single λ rather than just having a λ character there.

One small suggestion: add a section explaining how the above example works.