[Emacs-diffs] Changes to emacs/lispref/modes.texi

[Richard M . Stallman]

Index: emacs/lispref/modes.texi
diff -c emacs/lispref/modes.texi:1.112 emacs/lispref/modes.texi:1.113
*** emacs/lispref/modes.texi:1.112      Sun May 29 15:58:27 2005
--- emacs/lispref/modes.texi    Wed Jun  8 15:32:01 2005
***************
*** 1650,1662 ****
  @var{value}.  (This feature is new as of Emacs 22.1.)
  
  @item (@var{symbol} @var{then} @var{else})
! A list whose first element is a symbol that is not a keyword specifies a
! conditional.  Its meaning depends on the value of @var{symbol}.  If the
! value is address@hidden, the second element, @var{then}, is processed
! recursively as a mode-line element.  But if the value of @var{symbol} is
! @code{nil}, the third element, @var{else}, is processed recursively.
! You may omit @var{else}; then the mode-line element displays nothing if
! the value of @var{symbol} is @code{nil}.
  
  @item (@var{width} @address@hidden)
  A list whose first element is an integer specifies truncation or
--- 1650,1662 ----
  @var{value}.  (This feature is new as of Emacs 22.1.)
  
  @item (@var{symbol} @var{then} @var{else})
! A list whose first element is a symbol that is not a keyword specifies
! a conditional.  Its meaning depends on the value of @var{symbol}.  If
! @var{symbol} has a address@hidden value, the second element,
! @var{then}, is processed recursively as a mode-line element.
! Otherwise, the third element, @var{else}, is processed recursively.
! You may omit @var{else}; then the mode-line element displays nothing
! if the value of @var{symbol} is @code{nil} or void.
  
  @item (@var{width} @address@hidden)
  A list whose first element is an integer specifies truncation or
***************
*** 2319,2324 ****
--- 2319,2325 ----
  @menu
  * Font Lock Basics::            Overview of customizing Font Lock.
  * Search-based Fontification::  Fontification based on regexps.
+ * Customizing Keywords::        Customizing search-based fontification.
  * Other Font Lock Variables::   Additional customization facilities.
  * Levels of Font Lock::         Each mode can define alternative levels
                                    so that the user can select more or less.
***************
*** 2624,2642 ****
  @code{font-lock-keywords} should be case-insensitive.
  @end defvar
  
! 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
! argument @var{keywords} should be a list with the same format as the
! variable @code{font-lock-keywords}.  @var{mode} should be a symbol,
! the major mode command name, such as @code{c-mode}.  When Font Lock
! mode is turned on in @var{mode}, it adds @var{keywords} to
! @code{font-lock-keywords}.  @var{mode} can also be @code{nil}; the
! highlighting @var{keywords} are immediately added to
! @code{font-lock-keywords} in the current buffer in that case.
  
  By default, @var{keywords} are added at the beginning of
  @code{font-lock-keywords}.  If the optional argument @var{append} is
--- 2625,2651 ----
  @code{font-lock-keywords} should be case-insensitive.
  @end defvar
  
! @node Customizing Keywords
! @subsection Customizing Search-Based Fontification
! 
!   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 the current buffer
! or for major mode @var{mode}.  The argument @var{keywords} should be a
! list with the same format as the variable @code{font-lock-keywords}.
! 
! If @var{mode} is a symbol which is a major mode command name, such as
! @code{c-mode}, the effect is that enabling Font Lock mode in
! @var{mode} will add @var{keywords} to @code{font-lock-keywords}.
! Calling with a address@hidden value of @var{mode} is correct only in
! your @file{~/.emacs} file.
! 
! If @var{mode} is @code{nil}, this function adds @var{keywords} to
! @code{font-lock-keywords} in the current buffer.  This way of calling
! @code{font-lock-add-keywords} is usually used in mode hook functions.
  
  By default, @var{keywords} are added at the beginning of
  @code{font-lock-keywords}.  If the optional argument @var{append} is
***************
*** 2645,2651 ****
  address@hidden value, they are added at the end of
  @code{font-lock-keywords}.
  
! For example:
  
  @smallexample
  (font-lock-add-keywords 'c-mode
--- 2654,2682 ----
  address@hidden value, they are added at the end of
  @code{font-lock-keywords}.
  
! Some modes provide specialized support you can use in additional
! highlighting patterns.  See the variables
! @code{c-font-lock-extra-types}, @code{c++-font-lock-extra-types},
! @code{objc-font-lock-extra-types} and
! @code{java-font-lock-extra-types}, for example.
! 
! @strong{Warning:} major mode functions must not call
! @code{font-lock-add-keywords} under any circumstances, either directly
! or indirectly, except through their mode hooks.  (Doing so would lead
! to incorrect behavior for some minor modes.)  They should set up their
! rules for search-based fontification by setting
! @code{font-lock-keywords}.
! @end defun
! 
! @defun font-lock-remove-keywords mode keywords
! This function removes @var{keywords} from @code{font-lock-keywords}
! for the current buffer or for major mode @var{mode}.  As in
! @code{font-lock-add-keywords}, @var{mode} should be a major mode
! command name or @code{nil}.  All the caveats and requirments for
! @code{font-lock-add-keywords} apply here too.
! @end defun
! 
!   For example, this code
  
  @smallexample
  (font-lock-add-keywords 'c-mode
***************
*** 2653,2682 ****
     ("\\<\\(and\\|or\\|not\\)\\>" . font-lock-keyword-face)))
  @end smallexample
  
  adds two fontification patterns for C mode: one to fontify the word
  @samp{FIXME}, even in comments, and another to fontify the words
  @samp{and}, @samp{or} and @samp{not} as keywords.
  
! 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}
! and @code{java-font-lock-extra-types}, for example.
! @end defun
! 
! @defun font-lock-remove-keywords mode keywords
! This function removes highlighting @var{keywords} for @var{mode}.  As
! 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
--- 2684,2706 ----
     ("\\<\\(and\\|or\\|not\\)\\>" . font-lock-keyword-face)))
  @end smallexample
  
+ @noindent
  adds two fontification patterns for C mode: one to fontify the word
  @samp{FIXME}, even in comments, and another to fontify the words
  @samp{and}, @samp{or} and @samp{not} as keywords.
  
! @noindent
! That example affects only C mode proper.  To add the same patterns to
! C mode @emph{and} all modes derived from it, do this instead:
  
! @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
  
  @node Other Font Lock Variables
  @subsection Other Font Lock Variables