Subject: bug#20613: closed (Re: bug#20613: Font locking is poorly documented)

From: [email-masked] (GNU bug Tracking System)
Date: Thu, 16 Apr 2020 04:14:02 +0000

Your bug report

#20613: Font locking is poorly documented

which was filed against the emacs package, has been closed.

The explanation is attached below, along with your original report.
If you require more details, please reply to [email-masked].

-- 
20613: http://debbugs.gnu.org/cgi/bugreport.cgi?bug=20613
GNU Bug Tracking System
Contact [email-masked] with problems

Subject: Re: bug#20613: Font locking is poorly documented
From: Stefan Kangas <[email-masked]>
To: Lars Ingebrigtsen <[email-masked]>
Cc: Paul Eggert <[email-masked]>, [email-masked], Dmitry Gutov <[email-masked]>
Date: Thu, 16 Apr 2020 06:13:22 +0200
List-Id: <debbugs-submit.debbugs.gnu.org>

Lars Ingebrigtsen <[email-masked]> 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

Subject: Font locking is poorly documented
From: Paul Eggert <[email-masked]>
To: Emacs bug reports <[email-masked]>
Date: Tue, 19 May 2015 15:42:05 -0700
List-Id: <debbugs-submit.debbugs.gnu.org>

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.