@c -*-texinfo-*-
@c This is part of the GNU Emacs Lisp Reference Manual.
-@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998, 1999,
+@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998, 1999, 2002,
@c 2003, 2004, 2005 Free Software Foundation, Inc.
@c See the file elisp.texi for copying conditions.
@setfilename ../info/modes
@item
The mode should specify how Imenu should find the definitions or
sections of a buffer, by setting up a buffer-local value for the
-variable @code{imenu-generic-expression}, for the pair of variables
+variable @code{imenu-generic-expression}, for the two variables
@code{imenu-prev-index-position-function} and
@code{imenu-extract-index-name-function}, or for the variable
@code{imenu-create-index-function} (@pxref{Imenu}).
command (called the @dfn{parent mode}) and then alter some of its
settings. A mode that does this is called a @dfn{derived mode}. The
recommended way to define one is to use @code{define-derived-mode},
-but this is not required. Such a mode should use
-@code{delay-mode-hooks} around its entire body (including the call to
-the parent mode command) @emph{except} for the final call to
-@code{run-mode-hooks}, which runs the derived mode's hook. (Using
+but this is not required. Such a mode should call the parent mode
+command inside a @code{delay-mode-hooks} form. (Using
@code{define-derived-mode} does this automatically.) @xref{Derived
Modes}, and @ref{Mode Hooks}.
elements of the form @code{(@var{interpreter} . @var{mode})}; for
example, @code{("perl" . perl-mode)} is one element present by
default. The element says to use mode @var{mode} if the file
-specifies an interpreter which matches @var{interpreter}. The value
-of @var{interpreter} is actually a regular expression. @xref{Regular
-Expressions}.
+specifies an interpreter which matches @var{interpreter}.
@end defvar
@defvar magic-mode-alist
These conventions are new in Emacs 22, and some major modes
implemented by users do not follow them yet. So if you put a function
onto @code{after-change-major-mode-hook}, keep in mind that some modes
-will fail to run it. If user complains about that, you can respond,
+will fail to run it. If a user complains about that, you can respond,
``That major mode fails to follow Emacs conventions, and that's why it
fails to work. Please fix the major mode.'' In most cases, that is
good enough, so go ahead and use @code{after-change-major-mode-hook}.
mode, with @var{doc} as its documentation string. It also defines a
variable named @var{mode}, which is set to @code{t} or @code{nil} by
enabling or disabling the mode. The variable is initialized to
-@var{init-value}.
+@var{init-value}. Except in unusual circumstances (see below), this
+value must be @code{nil}.
The string @var{lighter} says what to display in the mode line
when the mode is enabled; if it is @code{nil}, the mode is not displayed
This is equivalent to specifying @var{keymap} positionally.
@end table
-Any other keyword arguments are passed passed directly to the
+Any other keyword arguments are passed directly to the
@code{defcustom} generated for the variable @var{mode}.
The command named @var{mode} first performs the standard actions such
variable @code{@var{mode}-hook}.
@end defmac
+ The initial value must be @code{nil} except in cases where (1) the
+mode is preloaded in Emacs, or (2) it is painless to for loading to
+enable the mode even though the user did not request it. For
+instance, if the mode has no effect unless something else is enabled,
+and will always be loaded by that time, enabling it by default is
+harmless. But these are unusual circumstances. Normally, the
+initial value must be @code{nil}.
+
@findex easy-mmode-define-minor-mode
The name @code{easy-mmode-define-minor-mode} is an alias
for this macro.
gobbles all preceding whitespace except the last.
See the command \\[hungry-electric-delete]."
;; The initial value.
- :initial-value nil
+ :init-value nil
;; The indicator for the mode line.
:lighter " Hungry"
;; The minor mode bindings.
The mode line can display various faces, if the strings that control
it have the @code{face} property. @xref{Properties in Mode}. In
addition, the face @code{mode-line} is used as a default for the whole
-mode line (@pxref{Standard Faces}).
+mode line (@pxref{Standard Faces,,, emacs, The GNU Emacs Manual}).
@table @code
@cindex percent symbol in mode line
@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 non-@code{nil}, 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}.
+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 non-@code{nil} 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} @var{rest}@dots{})
A list whose first element is an integer specifies truncation or
@item %F
The title (only on a window system) or the name of the selected frame.
-@xref{Window Frame Parameters}.
+@xref{Basic Parameters}.
@item %i
The size of the accessible part of the current buffer; basically
It creates the submenu @var{menu-title} specified by @var{sub-alist}.
The default value of @code{imenu-create-index-function} is
-@code{imenu-default-create-index-function}. This function uses
-@code{imenu-prev-index-position-function} and
+@code{imenu-default-create-index-function}. This function calls the
+value of @code{imenu-prev-index-position-function} and the value of
@code{imenu-extract-index-name-function} to produce the index alist.
However, if either of these two variables is @code{nil}, the default
function uses @code{imenu-generic-expression} instead.
@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.
@end example
If you use @code{regexp-opt} to produce the regular expression
-@var{matcher}, then you can use @code{regexp-opt-depth} (@pxref{Regexp
+@var{matcher}, you can use @code{regexp-opt-depth} (@pxref{Regexp
Functions}) to calculate the value for @var{subexp}.
@item (@var{matcher} . @var{facespec})
@code{font-lock-keywords} should be case-insensitive.
@end defvar
-You can use @code{font-lock-add-keywords} to add additional
+@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 @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.
+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 non-@code{nil} 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
non-@code{nil} value, they are added at the end of
@code{font-lock-keywords}.
-For example:
+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},
+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
("\\<\\(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.
-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
+@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:
-@strong{Warning:} Only use a non-@code{nil} @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.
+@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