@end example
At the appropriate time, Emacs uses the @code{run-hooks} function to
-run particular hooks. This function calls the hook functions that have
-been added with @code{add-hook}.
+run particular hooks.
@defun run-hooks &rest hookvars
This function takes one or more normal hook variable names as
@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}.
@item
If you want to make the new mode the default for files with certain
recognizable names, add an element to @code{auto-mode-alist} to select
-the mode for those file names. If you define the mode command to
-autoload, you should add this element in the same file that calls
-@code{autoload}. If you use an autoload cookie for the mode command,
-you can also use an autoload cookie for the form that adds the element
-(@pxref{autoload cookie}). If you do not autoload the mode command,
-it is sufficient to add the element in the file that contains the mode
-definition. @xref{Auto Major Mode}.
+the mode for those file names (@pxref{Auto Major Mode}). If you
+define the mode command to autoload, you should add this element in
+the same file that calls @code{autoload}. If you use an autoload
+cookie for the mode command, you can also use an autoload cookie for
+the form that adds the element (@pxref{autoload cookie}). If you do
+not autoload the mode command, it is sufficient to add the element in
+the file that contains the mode definition.
@item
In the comments that document the file, you should provide a sample
@code{:syntax-table} keyword (see below). @code{define-derived-mode}
makes the parent mode's syntax-table the parent of
@code{@var{variant}-syntax-table}, unless the latter is already set
-and already has a parent different from @code{standard-syntax-table}.
+and already has a parent different from the standard syntax table.
@item
The new mode has its own abbrev table, kept in the variable
@item
The new mode has its own mode hook, @code{@var{variant}-hook}. It
runs this hook, after running the hooks of its ancestor modes, with
-@code{run-mode-hooks} (@pxref{Mode Hooks}).
+@code{run-mode-hooks}, as the last thing it does. @xref{Mode Hooks}.
@end itemize
In addition, you can specify how to override other aspects of
@var{parent} with @var{body}. The command @var{variant}
evaluates the forms in @var{body} after setting up all its usual
-overrides, just before running @code{@var{variant}-hook}.
+overrides, just before running the mode hooks.
You can also specify @code{nil} for @var{parent}. This gives the new
mode no parent. Then @code{define-derived-mode} behaves as described
are evaluated. The following keywords are currently supported:
@table @code
-@item :group
-If this is specified, it is the customization group for this mode.
-
@item :syntax-table
You can use this to explicitly specify a syntax table for the new
mode. If you specify a @code{nil} value, the new mode uses the same
-syntax table as @var{parent}, or @code{standard-syntax-table} if
+syntax table as @var{parent}, or the standard syntax table if
@var{parent} is @code{nil}. (Note that this does @emph{not} follow
the convention used for non-keyword arguments that a @code{nil} value
is equivalent with not specifying the argument.)
abbrev table as @var{parent}, or @code{fundamental-mode-abbrev-table}
if @var{parent} is @code{nil}. (Again, a @code{nil} value is
@emph{not} equivalent to not specifying this keyword.)
+
+@item :group
+If this is specified, the value should be the customization group for
+this mode. (Not all major modes have one.) Only the (still
+experimental and unadvertised) command @code{customize-mode} currently
+uses this. @code{define-derived-mode} does @emph{not} automatically
+define the specified customization group.
@end table
Here is a hypothetical example:
@node Mode Hooks
@subsection Mode Hooks
-The two last things a major mode function does is to run its mode
+ The two last things a major mode function should do is run its mode
hook and finally the mode independent normal hook
@code{after-change-major-mode-hook}. If the major mode is a derived
mode, that is if it calls another major mode (the parent mode) in its
mode's hook. Neither the parent's mode hook nor
@code{after-change-major-mode-hook} are run at the end of the actual
call to the parent mode. This applies recursively if the parent mode
-has itself a parent. That is, the mode hooks of all major modes called
-directly or indirectly by the major mode function are all run in
-sequence at the end, just before @code{after-change-major-mode-hook}.
-
-If you are customizing a major mode, rather than defining one, the
-above is all you need to know about the hooks run at the end of a
-major mode. This also applies if you use @code{define-derived-mode}
-to define a major mode, because that macro will automatically
-implement the above for you.
-
-Programmers wishing to define a major mode without using
-@code{define-derived-mode}, should make sure that their major mode
-follows the above conventions. @xref{Major Mode Conventions}, for how
-this should be accomplished. Below, we give some implementation
-details.
+has itself a parent. That is, the mode hooks of all major modes
+called directly or indirectly by the major mode function are all run
+in sequence at the end, just before
+@code{after-change-major-mode-hook}.
+
+ 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 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}.
+However, if a certain feature needs to be completely reliable,
+it should not use @code{after-change-major-mode-hook} as of yet.
+
+ When you defined a major mode using @code{define-derived-mode}, it
+automatically makes sure these conventions are followed. If you
+define a major mode ``from scratch'', not using
+@code{define-derived-mode}, make sure the major mode command follows
+these and other conventions. @xref{Major Mode Conventions}. You use
+these functions to do it properly.
@defun run-mode-hooks &rest hookvars
Major modes should run their mode hook using this function. It is
-similar to @code{run-hooks} (@pxref{Hooks}), but if run inside a
-@code{delay-mode-hooks} form, this function does not run any hooks.
-Instead, it arranges for @var{hookvars} to be run at a later call to
-the function. Otherwise, @code{run-mode-hooks} runs any delayed hooks
-in order, then @var{hookvars} and finally
+similar to @code{run-hooks} (@pxref{Hooks}), but it also runs
@code{after-change-major-mode-hook}.
+
+When the call to this function is dynamically inside a
+@code{delay-mode-hooks} form, this function does not run any hooks.
+Instead, it arranges for the next call to @code{run-mode-hooks} to run
+@var{hookvars}.
@end defun
@defmac delay-mode-hooks body...
This macro executes @var{body} like @code{progn}, but all calls to
@code{run-mode-hooks} inside @var{body} delay running their hooks.
They will be run by the first call to @code{run-mode-hooks} after exit
-from @code{delay-mode-hooks}.
+from @code{delay-mode-hooks}. This is the proper way for a major mode
+command to invoke its parent mode.
@end defmac
@defvar after-change-major-mode-hook
Every major mode function should run this normal hook at its very end.
It normally does not need to do so explicitly. Indeed, a major mode
function should normally run its mode hook with @code{run-mode-hooks}
-as the very last thing it does and @code{run-mode-hooks} runs
-@code{after-change-major-mode-hook} at its very end.
+as the very last thing it does, and the last thing
+@code{run-mode-hooks} does is run @code{after-change-major-mode-hook}.
@end defvar
@node Minor Modes
@item
Add an element to @code{minor-mode-alist} for each minor mode
-(@pxref{Mode Line Variables}), if you want to indicate the minor mode in
-the mode line. This element should be a list of the following form:
+(@pxref{Definition of minor-mode-alist}), if you want to indicate the
+minor mode in the mode line. This element should be a list of the
+following form:
@smallexample
(@var{mode-variable} @var{string})
invoking the mode command. Note in the variable's documentation string that
setting the variable other than via Custom may not take effect.
- Also mark the definition with an autoload cookie (@pxref{Autoload}),
+ Also mark the definition with an autoload cookie (@pxref{autoload cookie}),
and specify a @code{:require} so that customizing the variable will load
the library that defines the mode. This will copy suitable definitions
into @file{loaddefs.el} so that users can use @code{customize-option} to
Each minor mode can have its own keymap, which is active when the mode
is enabled. To set up a keymap for a minor mode, add an element to the
-alist @code{minor-mode-map-alist}. @xref{Active Keymaps}.
+alist @code{minor-mode-map-alist}. @xref{Definition of minor-mode-map-alist}.
@cindex @code{self-insert-command}, minor modes
One use of minor mode keymaps is to modify the behavior of certain
@item (:eval @var{form})
A list whose first element is the symbol @code{:eval} says to evaluate
-@var{form}, and use the result as a string to display.
+@var{form}, and use the result as a string to display. Make sure this
+evaluation cannot load any files, as doing so could cause infinite
+recursion.
@item (:propertize @var{elt} @var{props}@dots{})
A list whose first element is the symbol @code{:propertize} says to
@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
padding of the results of @var{rest}. The remaining elements
@var{rest} are processed recursively as mode-line constructs and
-concatenated together. Then the result is space filled (if
-@var{width} is positive) or truncated (to @minus{}@var{width} columns,
-if @var{width} is negative) on the right.
+concatenated together. When @var{width} is positive, the result is
+space filled on the right if its width is less than @var{width}. When
+@var{width} is negative, the result is truncated on the right to
+@minus{}@var{width} columns if its width exceeds @minus{}@var{width}.
For example, the usual way to show what percentage of a buffer is above
the top of the window is to use a list like this: @code{(-3 "%p")}.
@end defvar
@defvar minor-mode-alist
+@anchor{Definition of minor-mode-alist}
This variable holds an association list whose elements specify how the
mode line should indicate that a minor mode is active. Each element of
the @code{minor-mode-alist} should be a two-element list:
The following table lists the recognized @code{%}-constructs and what
they mean. In any construct except @samp{%%}, you can add a decimal
-integer after the @samp{%} to specify how many characters to display.
+integer after the @samp{%} to specify a minimum field width. If the
+width is less, the field is padded with spaces to the right.
@table @code
@item %b
Certain text properties are meaningful in the
mode line. The @code{face} property affects the appearance of text; the
-@code{help-echo} property associate help strings with the text, and
+@code{help-echo} property associates help strings with the text, and
@code{local-map} can make the text mouse-sensitive.
There are four ways to specify text properties for text in the mode
You can use the function @code{format-mode-line} to compute
the text that would appear in a mode line or header line
-based on certain mode-line specification.
+based on a certain mode-line specification.
@defun format-mode-line format &optional face window buffer
This function formats a line of text according to @var{format} as if
for which no @code{face} property is specified gets a default
value which is usually @var{face}. (If @var{face} is @code{t},
that stands for either @code{mode-line} if @var{window} is selected,
-otherwise @code{mode-line-inactive}.)
+otherwise @code{mode-line-inactive}. If @var{face} is @code{nil} or
+omitted, that stands for no face property.)
However, if @var{face} is an integer, the value has no text properties.
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.
resulting syntax table is stored in @code{font-lock-syntax-table}.
The fifth element, @var{syntax-begin}, specifies the value of
-@code{font-lock-beginning-of-syntax-function}.
+@code{font-lock-beginning-of-syntax-function}. We recommend setting
+this variable to @code{nil} and using @code{syntax-begin-function}
+instead.
All the remaining elements (if any) are collectively called
@var{other-vars}. Each of these elements should have the form
@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
@code{font-lock-defaults}.
@end defvar
-@c ???
-@c The docstring says that font-lock-syntax-table is semi-obsolete.
-@c How the alternative should be used is not clear. --lute
-
@defvar font-lock-beginning-of-syntax-function
If this variable is non-@code{nil}, it should be a function to move
point back to a position that is syntactically at ``top level'' and
be outside a syntactic block), or @code{beginning-of-defun} for
programming modes, or @code{backward-paragraph} for textual modes.
-If the value is @code{nil}, the beginning of the buffer is used as a
-position outside of a syntactic block. This cannot be wrong, but it
-can be slow.
+If the value is @code{nil}, Font Lock uses
+@code{syntax-begin-function} to move back outside of any comment,
+string, or sexp. This variable is semi-obsolete; we recommend setting
+@code{syntax-begin-function} instead.
Specify this variable using @var{syntax-begin} in
@code{font-lock-defaults}.