Subject: Re: bug#20613: Font locking is poorly documented

From: Dmitry Gutov <[email-masked]>
Date: Wed, 20 May 2015 04:00:57 +0300

On 05/20/2015 01:42 AM, Paul Eggert wrote:

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

The return value is documented in the docstring of font-lock-keywords.

This case is  (MATCHER . HIGHLIGHT), where HIGHLIGHT is MATCH-HIGHLIGHT. 
The expression is supposed to return the face to use, but here it 
returns nil, because it doesn't apply a face.

Unfortunately, using compose-region in it is pretty much undocumented 
behavior. But since we can anticipate in which context the expression is 
evaluated, it's still relatively safe WRT future changes in font-lock code.