bug#20613: Font locking is poorly documented

[Lars Ingebrigtsen <larsi@gnus.org>]

Dmitry Gutov <dgutov@yandex.ru> writes:

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

So it just changes the buffer and returns nil as the font to use?  Then
this doesn't seem like something that needs explaining in the font
locking part of the manual, at least.

I started futzing around with font locking recently (I've never looked
at it before), and the manual seemed to explain things pretty well
(although it didn't explain how to test stuff, which is why I added the
`font-lock-debug-fontify' command).

So is there anything else here that needs to be done, or can this bug
report be closed?

-- 
(domestic pets only, the antidote for overdose, milk.)
   bloggy blog: http://lars.ingebrigtsen.no