GNU bug report logs - #20613
Font locking is poorly documented

Previous Next

To add a comment to this bug, you must first unarchive it, by sending
a message to control AT debbugs.gnu.org, with unarchive 20613 in the body.
You can then email your comments to 20613 AT debbugs.gnu.org in the normal way.

Toggle the display of automated, internal messages from the tracker.

Message #5 received at submit <at> debbugs.gnu.org (full text, mbox):

From: Paul Eggert <eggert <at> cs.ucla.edu>
To: Emacs bug reports <bug-gnu-emacs <at> gnu.org>
Subject: Font locking is poorly documented
Date: Tue, 19 May 2015 15:42:05 -0700

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.

Message #8 received at 20613 <at> debbugs.gnu.org (full text, mbox):

From: Dmitry Gutov <dgutov <at> yandex.ru>
To: Paul Eggert <eggert <at> cs.ucla.edu>, 20613 <at> debbugs.gnu.org
Subject: Re: bug#20613: Font locking is poorly documented
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.

Message #11 received at 20613 <at> debbugs.gnu.org (full text, mbox):

From: Lars Ingebrigtsen <larsi <at> gnus.org>
To: Dmitry Gutov <dgutov <at> yandex.ru>
Cc: 20613 <at> debbugs.gnu.org, Paul Eggert <eggert <at> cs.ucla.edu>
Subject: Re: bug#20613: Font locking is poorly documented
Date: Sun, 17 Nov 2019 07:20:43 +0100

Dmitry Gutov <dgutov <at> 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

Message #16 received at 20613-done <at> debbugs.gnu.org (full text, mbox):

From: Stefan Kangas <stefan <at> marxist.se>
To: Lars Ingebrigtsen <larsi <at> gnus.org>
Cc: Paul Eggert <eggert <at> cs.ucla.edu>, 20613-done <at> debbugs.gnu.org,
 Dmitry Gutov <dgutov <at> yandex.ru>
Subject: Re: bug#20613: Font locking is poorly documented
Date: Thu, 16 Apr 2020 06:13:22 +0200

Lars Ingebrigtsen <larsi <at> 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

Previous Next

GNU bug tracking system
Copyright (C) 1999 Darren O. Benham, 1997,2003 nCipher Corporation Ltd, 1994-97 Ian Jackson.