font-lock-refresh-defaults

[Drew Adams]

I just got a bug report for my library buff-menu+.el, which adds a few things to
buff-menu.el. The problem was that none of the faces were showing up (except
one), using the latest Emacs source code.

There is no such problem with Emacs 23.2 or with a build as late as 2009-09-11.
I see the problem starting with a build of 2010-05-23 (I have no builds between
those dates).

The buff-menu.el source library is identical (no changes), so the problem does
not come from that code.

The problem goes away if a call to `font-lock-refresh-defaults' is inserted:

(defun Buffer-menu-fontify-and-adjust-frame ()
  "Use for `buffer-menu-mode-hook'.  Fontify, fit and raise frame."
  (save-window-excursion
    (save-excursion
      (pop-to-buffer "*Buffer List*")
      (when (< emacs-major-version 21)
        (make-local-variable 'font-lock-defaults))
      (setq font-lock-defaults 
            '(buffer-menu-font-lock-keywords t))
      (when (fboundp 'font-lock-refresh-defaults)
        (font-lock-refresh-defaults)) ; WHY NEEDED NOW?
      (turn-on-font-lock)
      (when (and (fboundp 'fit-frame) (one-window-p t))
        (fit-frame))
      (raise-frame))))

OK, so Emacs has apparently changed something about font-locking, so now you
must refresh whenever you change the font-lock defaults.  (Whenever?  Or maybe
only sometimes when you change the defaults?)

Why?  And exactly when?  What changes must users make to their code?

Well, the doc string for the function gives a little guidance, but I looked in
the Emacs and Elisp manuals for more.  Nothing.  I looked in NEWS.  Nothing.

Why the silence about this change?  Why not help users by telling them (a) THAT
they may have to do something different to get the same behavior as before and
(b) WHY they now have to do something different.

Why no discussion in emacs-devel before the change - or even after it?
Searching the emacs-devel archives finds thread "Need help with search based
font-locking".  This function was added in the middle of that thread.  No
attention was brought to this change.  Nothing about how this means that you
might need to change your code, that this represents a general font-lock
behavior change.

Isn't some explanation of this feature the least one could expect from those who
make such changes?  We might like to understand WHY such a change in existing
code that uses font-locking is now necessary, and under what circumstances.