(font-lock-add-keywords): Doc fix. Comment change.

(font-lock-remove-keywords): Doc fix.
(font-lock-mode-major-mode): Compiler defvar.
(font-lock-set-defaults): Use `font-lock-mode-major-mode '.

diff --git a/lisp/font-lock.el b/lisp/font-lock.el
index d2507474f12a62190f83e48e1bb39384d0bd4c01..691f617cfb0643abd1bf45e5a1fa8c3e4b174384 100644 (file)
--- a/lisp/font-lock.el
+++ b/lisp/font-lock.el
@@ -683,9 +683,22 @@ For example:
 adds two fontification patterns for C mode, to fontify `FIXME:' words, even in
 comments, and to fontify `and', `or' and `not' words as keywords.
 
-When used from a Lisp program (such as a minor mode), it is recommended to
-use nil for MODE (and place the call on a hook) to avoid subtle problems
-due to details of the implementation.
+The above procedure will only add the keywords for C mode, not
+for modes derived from C mode.  To add them for derived modes too,
+pass nil for MODE and add the call to c-mode-hook.
+
+For example:
+
+ (add-hook 'c-mode-hook
+  (lambda ()
+   (font-lock-add-keywords 'c-mode
+    '((\"\\\\\\=<\\\\(FIXME\\\\):\" 1 font-lock-warning-face prepend)
+      (\"\\\\\\=<\\\\(and\\\\|or\\\\|not\\\\)\\\\\\=>\" .
+       font-lock-keyword-face)))))
+
+The above procedure may fail to add keywords to derived modes if
+some involved major mode does not follow the standard conventions.
+File a bug report if this happens, so the major mode can be corrected.
 
 Note that some modes have specialized support for additional patterns, e.g.,
 see the variables `c-font-lock-extra-types', `c++-font-lock-extra-types',
@@ -704,7 +717,8 @@ see the variables `c-font-lock-extra-types', `c++-font-lock-extra-types',
         (font-lock-update-removed-keyword-alist mode keywords append))
        (t
         ;; Otherwise set or add the keywords now.
-        ;; This is a no-op if it has been done already in this buffer.
+        ;; This is a no-op if it has been done already in this buffer
+        ;; for the correct major mode.
         (font-lock-set-defaults)
         (let ((was-compiled (eq (car font-lock-keywords) t)))
           ;; Bring back the user-level (uncompiled) keywords.
@@ -774,9 +788,11 @@ see the variables `c-font-lock-extra-types', `c++-font-lock-extra-types',
 MODE should be a symbol, the major mode command name, such as `c-mode'
 or nil.  If nil, highlighting keywords are removed for the current buffer.
 
-When used from a Lisp program (such as a minor mode), it is recommended to
-use nil for MODE (and place the call on a hook) to avoid subtle problems
-due to details of the implementation."
+To make the removal apply to modes derived from MODE as well,
+pass nil for MODE and add the call to MODE-hook.  This may fail
+for some derived modes if some involved major mode does not
+follow the standard conventions.  File a bug report if this
+happens, so the major mode can be corrected."
   (cond (mode
         ;; Remove one keyword at the time.
         (dolist (keyword keywords)
@@ -1571,12 +1587,14 @@ A LEVEL of nil is equal to a LEVEL of 0, a LEVEL of t is equal to
 
 (defvar font-lock-set-defaults nil)    ; Whether we have set up defaults.
 
+(defvar font-lock-mode-major-mode)
 (defun font-lock-set-defaults ()
   "Set fontification defaults appropriately for this mode.
 Sets various variables using `font-lock-defaults' (or, if nil, using
 `font-lock-defaults-alist') and `font-lock-maximum-decoration'."
-  ;; Set fontification defaults iff not previously set.
-  (unless font-lock-set-defaults
+  ;; Set fontification defaults iff not previously set for correct major mode.
+  (unless (and font-lock-set-defaults
+              (eq font-lock-mode-major-mode major-mode))
     (set (make-local-variable 'font-lock-set-defaults) t)
     (make-local-variable 'font-lock-fontified)
     (make-local-variable 'font-lock-multiline)