Re: org-mode and mode hooks.

[Luc Teirlinck]

Richard Stallman wrote:

   I will add this to the documentation of font-lock-add-keywords.

   @strong{Warning:} major mode functions must not call
   @code{font-lock-add-keywords} under any circumstances, either directly
   or indirectly.  (This would lead to incorrect behavior for some minor
   modes.)  They should set up for Font Lock mode by setting
   @code{font-lock-keywords}.

Well, it depends on _how_ they call it indirectly.  For instance, if
the indirect call adds it to a mode hook everything is fine.  I
believe that it is better to apply the patch below to modes.texi.

(I could not reply earlier due to connection problems.)

===File ~/modes.texi-diff===================================
*** modes.texi  29 May 2005 10:42:38 -0500      1.112
--- modes.texi  06 Jun 2005 18:06:28 -0500      
***************
*** 2626,2632 ****
  
  You can use @code{font-lock-add-keywords} to add additional
  search-based fontification rules to a major mode, and
! @code{font-lock-remove-keywords} to removes rules.
  
  @defun font-lock-add-keywords mode keywords &optional append
  This function adds highlighting @var{keywords} for @var{mode}.  The
--- 2626,2634 ----
  
  You can use @code{font-lock-add-keywords} to add additional
  search-based fontification rules to a major mode, and
! @code{font-lock-remove-keywords} to remove rules.  These two functions
! are meant for user customization and for use in minor mode functions.
! Major mode functions should set @code{font-lock-keywords} instead.
  
  @defun font-lock-add-keywords mode keywords &optional append
  This function adds highlighting @var{keywords} for @var{mode}.  The
***************
*** 2657,2662 ****
--- 2659,2685 ----
  @samp{FIXME}, even in comments, and another to fontify the words
  @samp{and}, @samp{or} and @samp{not} as keywords.
  
+ The above example does @emph{not} add the fontification patterns to
+ major modes derived from C mode, as is usually desired.  To add them
+ to derived modes too, pass @code{nil} for mode and add the call to
+ @var{mode}'s mode hook.
+ 
+ For example:
+ 
+ @smallexample
+ (add-hook 'c-mode-hook
+  (lambda ()
+   (font-lock-add-keywords nil
+    '(("\\<\\(FIXME\\):" 1 font-lock-warning-face prepend)
+      ("\\<\\(and\\|or\\|not\\)\\>" .
+       font-lock-keyword-face)))))
+ @end smallexample
+ 
+ The above procedure may fail to add keywords to a derived mode if
+ @var{mode} or the derived mode do not yet follow the standard
+ conventions.  File a bug report if this happens, so that the offending
+ major mode can be corrected.
+ 
  Some modes have specialized support for additional patterns.  See the
  variables @code{c-font-lock-extra-types},
  @code{c++-font-lock-extra-types}, @code{objc-font-lock-extra-types}
***************
*** 2668,2682 ****
  in @code{font-lock-add-keywords}, @var{mode} should be a major mode
  command name or @code{nil}.  If @code{nil}, the highlighting
  @var{keywords} are immediately removed in the current buffer.
- @end defun
  
! @strong{Warning:} Only use a address@hidden @var{mode} argument when
! you use @code{font-lock-add-keywords} or
! @code{font-lock-remove-keywords} in your @file{.emacs} file.  When you
! use these functions from a Lisp program (such as a minor mode), we
! recommend that you use @code{nil} for @var{mode} (and place the call
! on a hook) to avoid subtle problems due to the details of the
! implementation.
  
  @node Other Font Lock Variables
  @subsection Other Font Lock Variables
--- 2691,2704 ----
  in @code{font-lock-add-keywords}, @var{mode} should be a major mode
  command name or @code{nil}.  If @code{nil}, the highlighting
  @var{keywords} are immediately removed in the current buffer.
  
! This function does @emph{not} remove the highlighting @var{keywords}
! from derived modes, as is usually desired.  To remove them from
! derived modes too, pass @code{nil} for mode and add the call to
! @var{mode}'s hook.  This may fail if @var{mode} or a derived mode do
! not yet follow the standard conventions.  File a bug report if this
! happens, so that the offending major mode can be corrected.
! @end defun
  
  @node Other Font Lock Variables
  @subsection Other Font Lock Variables
============================================================