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

Previous Next

Full log

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.

Previous Next

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