bug#20613: Font locking is poorly documented

bug#20613: Font locking is poorly documented

[Paul Eggert]

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.

bug#20613: Font locking is poorly documented

[Dmitry Gutov]

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.

bug#20613: Font locking is poorly documented

[Lars Ingebrigtsen]

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

bug#20613: Font locking is poorly documented

[Stefan Kangas]

Lars Ingebrigtsen <larsi@gnus.org> writes:

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

Since there have been no more comments within 21 weeks, I'm going to
assume that the answer is yes.  I'm consequently closing this bug now.

If my assumption is incorrect and this is still an issue, please
reopen the bug report.

Best regards,
Stefan Kangas