comparison lispref/modes.texi @ 25875:6a17c48b52ef

*** empty log message ***

25874:906a123add31

  If the new mode is similar to an old one, it is often unwise to modify
the old one to serve two purposes, since it may become harder to use and
maintain.  Instead, copy and rename an existing major mode definition
and alter the copy---or define a @dfn{derived mode} (@pxref{Derived
Modes}).  For example, Rmail Edit mode, which is in
@file{emacs/lisp/rmailedit.el}, is a major mode that is very similar to
Text mode except that it provides three additional commands.  Its
definition is distinct from that of Text mode, but was derived from it.

  Rmail Edit mode offers an example of changing the major mode
temporarily for a buffer, so it can be edited in a different way (with
ordinary Emacs commands rather than Rmail commands).  In such cases, the
temporary major mode usually provides a command to switch back to the

Editing}.

  The standard GNU Emacs Lisp library directory tree contains the code
for several major modes, in files such as @file{text-mode.el},
@file{texinfo.el}, @file{lisp-mode.el}, @file{c-mode.el}, and
@file{rmail.el}.  You can study these libraries to see how modes are
written.  Text mode is perhaps the simplest major mode aside from
Fundamental mode.  Rmail mode is a complicated and specialized mode.

@menu
* Major Mode Conventions::  Coding conventions for keymaps, etc.
* Example Major Modes::     Text mode and Lisp modes.

@code{make-variable-buffer-local}.  The latter function would make the
variable local to every buffer in which it is subsequently set, which
would affect buffers that do not use this mode.  It is undesirable for a
mode to have such global effects.  @xref{Buffer-Local Variables}.

It's OK to use @code{make-variable-buffer-local}, if you wish, for a
variable used only within a single Lisp package.

@item
@cindex mode hook
@cindex major mode hook
Each major mode should have a @dfn{mode hook} named

autoload, you should add this element in the same file that calls
@code{autoload}.  Otherwise, it is sufficient to add the element in the
file that contains the mode definition.  @xref{Auto Major Mode}.

@item
@cindex @file{.emacs} customization
In the documentation, you should provide a sample @code{autoload} form
and an example of how to add to @code{auto-mode-alist}, that users can
include in their @file{.emacs} files.

@item
@cindex mode loading
The top-level forms in the file defining the mode should be written so
that they may be evaluated more than once without adverse consequences.

  "Abbrev table used while in text mode.")
(define-abbrev-table 'text-mode-abbrev-table ())
@end group

@group
(defvar text-mode-map nil)   ; @r{Create a mode-specific keymap.}

(if text-mode-map
    ()              ; @r{Do not change the keymap if it is already set up.}
  (setq text-mode-map (make-sparse-keymap))
  (define-key text-mode-map "\t" 'indent-relative)
  (define-key text-mode-map "\es" 'center-line)
  (define-key text-mode-map "\eS" 'center-paragraph))
@end group
@end smallexample

@group
  (make-local-variable 'paragraph-start)
  (setq paragraph-start (concat "[ \t]*$\\|" page-delimiter))
  (make-local-variable 'paragraph-separate)
  (setq paragraph-separate paragraph-start)
@end group
@group
  (setq mode-name "Text")
  (setq major-mode 'text-mode)
  (run-hooks 'text-mode-hook))      ; @r{Finally, this permits the user to}

  @dots{}
@end group
@group
  (make-local-variable 'comment-indent-function)
  (setq comment-indent-function 'lisp-comment-indent))
@end group
@end smallexample

  Each of the different Lisp modes has a slightly different keymap.  For
example, Lisp mode binds @kbd{C-c C-z} to @code{run-lisp}, but the other

@var{function} t)} can uncompress the file and then put the uncompressed
file in the proper mode according to the name sans @samp{.gz}.

Here is an example of how to prepend several pattern pairs to
@code{auto-mode-alist}.  (You might use this sort of expression in your
@file{.emacs} file.)

@smallexample
@group
(setq auto-mode-alist
  (append 

When you add an element to @code{minor-mode-alist}, use @code{assq} to
check for an existing element, to avoid duplication.  For example:

@smallexample
@group
(or (assq 'leif-mode minor-mode-alist)
    (setq minor-mode-alist
          (cons '(leif-mode " Leif") minor-mode-alist)))
@end group
@end smallexample
@end itemize

  You can also use @code{add-to-list} to add an element to this list
just once (@pxref{Setting Variables}).

  Global minor modes distributed with Emacs should if possible support
enabling and disabling via Custom (@pxref{Customization}).  To do this,
the first step is to define the mode variable with @code{defcustom}, and
specify @code{:type boolean}.

@node Mode Line Data
@subsection The Data Structure of the Mode Line
@cindex mode line construct

  The mode line contents are controlled by a data structure of lists,
strings, symbols, and numbers kept in the buffer-local variable
@code{mode-line-format}.  The data structure is called a @dfn{mode line
construct}, and it is built in recursive fashion out of simpler mode line
constructs.  The same data structure is used for constructing
frame titles (@pxref{Frame Titles}).

@defvar mode-line-format
The value of this variable is a mode line construct with overall
responsibility for the mode line format.  The value of this variable
controls which other variables are used to form the mode line text, and

This buffer-local variable contains the mode line information on process
status in modes used for communicating with subprocesses.  It is
displayed immediately following the major mode name, with no intervening
space.  For example, its value in the @samp{*shell*} buffer is
@code{(":%s")}, which allows the shell to display its status along
with the major mode as: @samp{(Shell:@: run)}.  Normally this variable
is @code{nil}.
@end defvar

@defvar default-mode-line-format
This variable holds the default @code{mode-line-format} for buffers
that do not override it.  This is the same as @code{(default-value
'mode-line-format)}.

@end group
 "   "
 global-mode-string
@group
 "   %[("
 (:eval (mode-line-mode-name))
 mode-line-process
 minor-mode-alist 
 "%n" 
 ")%]--"

 "-%-")
@end group
@end example
@end defvar

@defvar vc-mode
The variable @code{vc-mode}, buffer-local in each buffer, records
whether the buffer's visited file is maintained with version control,
and, if so, which kind.  Its value is @code{nil} for no version control,
or a string that appears in the mode line.
@end defvar

@node %-Constructs
@subsection @code{%}-Constructs in the Mode Line

  The following table lists the recognized @code{%}-constructs and what
they mean.  In any construct except @samp{%%}, you can add a decimal

@table @code
@item %b
The current buffer name, obtained with the @code{buffer-name} function.
@xref{Buffer Names}.

@item %f
The visited file name, obtained with the @code{buffer-file-name}
function.  @xref{Buffer File Name}.

@item %F
The title (only on a window system) or the name of the selected frame.
@xref{Window Frame Parameters}.

@item %c
The current column number of point.

@item %l
The current line number of point, counting within the accessible portion
of the buffer.

@item %*
@samp{%} if the buffer is read only (see @code{buffer-read-only}); @*
@samp{*} if the buffer is modified (see @code{buffer-modified-p}); @*
@samp{-} otherwise.  @xref{Buffer Modification}.

read-only buffer.  @xref{Buffer Modification}.

@item %&
@samp{*} if the buffer is modified, and @samp{-} otherwise.

@item %s
The status of the subprocess belonging to the current buffer, obtained with
@code{process-status}.  @xref{Process Information}.

@item %t
Whether the visited file is a text file or a binary file.  (This is a
meaningful distinction only on certain operating systems.)

@item %p
The percentage of the buffer text above the @strong{top} of window, or
@samp{Top}, @samp{Bottom} or @samp{All}.

@item %P
The percentage of the buffer text that is above the @strong{bottom} of
the window (which includes the text visible in the window, as well as
the text above the top), plus @samp{Top} if the top of the buffer is
visible on screen; or @samp{Bottom} or @samp{All}.

@item %n
@samp{Narrow} when narrowing is in effect; nothing otherwise (see
@code{narrow-to-region} in @ref{Narrowing}).

@item %[
An indication of the depth of recursive editing levels (not counting
minibuffer levels): one @samp{[} for each editing level.
@xref{Recursive Editing}.

@item %]
One @samp{]} for each recursive editing level (not counting minibuffer
levels).

@item %%
The character @samp{%}---this is how to include a literal @samp{%} in a
string in which @code{%}-constructs are allowed.

@item %-
Dashes sufficient to fill the remainder of the mode line.
@end table

The following two @code{%}-constructs are still supported, but they are
obsolete, since you can get the same results with the variables
@code{mode-name} and @code{global-mode-string}.

@code{local-map} property.
@end enumerate

  You use the @code{local-map} property to specify a keymap.  Like any
keymap, it can bind character keys and function keys; but that has no
effect, since is impossible to move point into the mode line, This
keymap can only take real effect for mouse clicks.

@node Header Lines
@subsection Window Header Lines
@cindex header line (of a window)

@cindex Imenu
  @dfn{Imenu} is a feature that lets users select a definition or
section in the buffer, from a menu which lists all of them, to go
directly to that location in the buffer.  Imenu works by constructing a
buffer index which lists the names and buffer positions of the
definitions, or portions of the buffer, so the user can pick one of them
to move to.  This section explains how to customize Imenu for a major
mode.

  The usual and simplest way is to set the variable
@code{imenu-generic-expression}:

@defvar imenu-generic-expression

@var{menu-title} is @code{nil}, the matches for this element go directly
in the top level of the buffer index.

The second item in the list, @var{regexp}, is a regular expression
(@pxref{Regular Expressions}); anything in the buffer that it matches is
considered a definition, to mention in the buffer index.  The third
item, @var{subexp}, indicates which subexpression in @var{regexp}
matches the definition's name.

An element can also look like this:

@example
(@var{menu-title} @var{regexp} @var{index} @var{function} @var{arguments}@dots{})
@end example

Each match for this element creates a special index item which, if
selected by the user, calls @var{function} with arguments
@var{item-name}, the buffer position, and @var{arguments}.

For Emacs Lisp mode, @var{pattern} could look like this:

@c should probably use imenu-syntax-alist and \\sw rather than [-A-Za-z0-9+]
@example

  Another way to customize Imenu for a major mode is to set the
variables @code{imenu-prev-index-position-function} and
@code{imenu-extract-index-name-function}:

@defvar imenu-prev-index-position-function
If this variable is non-@code{nil}, its value should be a function for
finding the next definition to mention in the buffer index, moving
backwards in the file.

The function should leave point at the place to be connected to the
index item; it should return @code{nil} if it doesn't find another item.

Setting this variable makes it buffer-local in the current buffer.
@end defvar

@defvar imenu-extract-index-name-function

Setting this variable makes it buffer-local in the current buffer.
@end defvar

  The last way to customize Imenu for a major mode is to set the
variables @code{imenu-create-index-function}:

@defvar imenu-create-index-function
This variable specifies the function to use for creating a buffer index.
The function should take no arguments, and return an index for the
current buffer.  It is called within @code{save-excursion}, so where it

@cindex Font Lock Mode

  @dfn{Font Lock mode} is a feature that automatically attaches
@code{face} properties to certain parts of the buffer based on their
syntactic role.  How it parses the buffer depends on the major mode;
most major modes define syntactic criteria for which faces to use, in
which contexts.  This section explains how to customize Font Lock for a
particular language---in other words, for a particular major mode.

  Font Lock mode finds text to highlight in two ways: through syntactic
parsing based on the syntax table, and through searching (usually for
regular expressions).  Syntactic fontification happens first; it finds
comments and string constants, and highlights them using
@code{font-lock-comment-face} and @code{font-lock-string-face}
(@pxref{Faces for Font Lock}); search-based fontification follows.

@menu
* Font Lock Basics::
* Search-based Fontification::
* Other Font Lock Variables::

 @var{syntax-alist} @var{syntax-begin} @var{other-vars}@dots{})
@end example

The first element, @var{keywords}, indirectly specifies the value of
@code{font-lock-keywords}.  It can be a symbol, a variable whose value
is list to use for @code{font-lock-keywords}.  It can also be a list of
several such symbols, one for each possible level of fontification.  The
first symbol specifies how to do level 1 fontification, the second
symbol how to do level 2, and so on.

The second element, @var{keywords-only}, specifies the value of the

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} (see below).

Any further elements @var{other-vars} are of the form
@code{(@var{variable} . @var{value})}.  This kind of element means to
make @var{variable} buffer-local and then set it to @var{value}.  This
is used to set other variables that affect fontification.
@end defvar

@node Search-based Fontification
@subsection Search-based Fontification

@cindex hooks

  A @dfn{hook} is a variable where you can store a function or functions
to be called on a particular occasion by an existing program.  Emacs
provides hooks for the sake of customization.  Most often, hooks are set
up in the @file{.emacs} file, but Lisp programs can set them also.
@xref{Standard Hooks}, for a list of standard hook variables.

@cindex normal hook
  Most of the hooks in Emacs are @dfn{normal hooks}.  These variables
contain lists of functions to be called with no arguments.  When the

a Function}).  Most normal hook variables are initially void;
@code{add-hook} knows how to deal with this.

@cindex abnormal hook
  If the hook variable's name does not end with @samp{-hook}, that
indicates it is probably an @dfn{abnormal hook}; you should look at its
documentation to see how to use the hook properly.

  If the variable's name ends in @samp{-functions} or @samp{-hooks},
then the value is a list of functions, but it is abnormal in that either
these functions are called with arguments or their values are used in

  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}.

@defun run-hooks &rest hookvar
This function takes one or more hook variable names as arguments, and
runs each hook in turn.  Each @var{hookvar} argument should be a symbol
that is a hook variable.  These arguments are processed in the order
specified.

If a hook variable has a non-@code{nil} value, that value may be a
function or a list of functions.  If the value is a function (either a
lambda expression or a symbol with a function definition), it is called.
If it is a list, the elements are called, in order.  The hook functions

@defun run-hook-with-args-until-failure hook &rest args
This function is the way to run an abnormal hook which passes arguments
to the hook functions, and stops as soon as any hook function fails.  It
calls each of the hook functions, passing each of them the arguments
@var{args}, until some hook function returns @code{nil}.  Then it stops,
and returns @code{nil} if some hook function did, and otherwise
returns a non-@code{nil} value.
@end defun

@defun run-hook-with-args-until-success hook &rest args
This function is the way to run an abnormal hook which passes arguments
to the hook functions, and stops as soon as any hook function succeeds.

This function makes the hook variable @code{hook} buffer-local in the
current buffer.  When a hook variable is buffer-local, it can have
buffer-local and global hook functions, and @code{run-hooks} runs all of
them.

This function works by making @code{t} an element of the buffer-local
value.  That serves as a flag to use the hook functions in the default
value of the hook variable as well as those in the buffer-local value.
Since @code{run-hooks} understands this flag, @code{make-local-hook}
works with all normal hooks.  It works for only some non-normal
hooks---those whose callers have been updated to understand this meaning
of @code{t}.

25875:6a17c48b52ef

  If the new mode is similar to an old one, it is often unwise to modify
the old one to serve two purposes, since it may become harder to use and
maintain.  Instead, copy and rename an existing major mode definition
and alter the copy---or define a @dfn{derived mode} (@pxref{Derived
Modes}).  For example, Rmail Edit mode, which is in
@file{emacs/lisp/mail/rmailedit.el}, is a major mode that is very similar to
Text mode except that it provides two additional commands.  Its
definition is distinct from that of Text mode, but uses that of Text mode.

  Rmail Edit mode offers an example of changing the major mode
temporarily for a buffer, so it can be edited in a different way (with
ordinary Emacs commands rather than Rmail commands).  In such cases, the
temporary major mode usually provides a command to switch back to the

Editing}.

  The standard GNU Emacs Lisp library directory tree contains the code
for several major modes, in files such as @file{text-mode.el},
@file{texinfo.el}, @file{lisp-mode.el}, @file{c-mode.el}, and
@file{rmail.el}.  They are found in various subdirectories of the
@file{lisp} directory.  You can study these libraries to see how modes
are written.  Text mode is perhaps the simplest major mode aside from
Fundamental mode.  Rmail mode is a complicated and specialized mode.

@menu
* Major Mode Conventions::  Coding conventions for keymaps, etc.
* Example Major Modes::     Text mode and Lisp modes.

@code{make-variable-buffer-local}.  The latter function would make the
variable local to every buffer in which it is subsequently set, which
would affect buffers that do not use this mode.  It is undesirable for a
mode to have such global effects.  @xref{Buffer-Local Variables}.

With rare exceptions, the only reasonable way to use use
@code{make-variable-buffer-local} in a Lisp package is for a variable
which is used only within that package.  Using it on a variable used by
other packages would interfere with them.

@item
@cindex mode hook
@cindex major mode hook
Each major mode should have a @dfn{mode hook} named

autoload, you should add this element in the same file that calls
@code{autoload}.  Otherwise, it is sufficient to add the element in the
file that contains the mode definition.  @xref{Auto Major Mode}.

@item
In the documentation, you should provide a sample @code{autoload} form
and an example of how to add to @code{auto-mode-alist}, that users can
include in their init files (@pxref{Init File}).

@item
@cindex mode loading
The top-level forms in the file defining the mode should be written so
that they may be evaluated more than once without adverse consequences.

  "Abbrev table used while in text mode.")
(define-abbrev-table 'text-mode-abbrev-table ())
@end group

@group
(defvar text-mode-map nil    ; @r{Create a mode-specific keymap.}
  "Keymap for Text mode.
Many other modes, such as Mail mode, Outline mode and Indented Text mode,
inherit all the commands defined in this map.")

(if text-mode-map
    ()              ; @r{Do not change the keymap if it is already set up.}
  (setq text-mode-map (make-sparse-keymap))
  (define-key text-mode-map "\e\t" 'ispell-complete-word)
  (define-key text-mode-map "\t" 'indent-relative)
  (define-key text-mode-map "\es" 'center-line)
  (define-key text-mode-map "\eS" 'center-paragraph))
@end group
@end smallexample

@group
  (make-local-variable 'paragraph-start)
  (setq paragraph-start (concat "[ \t]*$\\|" page-delimiter))
  (make-local-variable 'paragraph-separate)
  (setq paragraph-separate paragraph-start)
  (make-local-variable 'indent-line-function)
  (setq indent-line-function 'indent-relative-maybe)
@end group
@group
  (setq mode-name "Text")
  (setq major-mode 'text-mode)
  (run-hooks 'text-mode-hook))      ; @r{Finally, this permits the user to}

  @dots{}
@end group
@group
  (make-local-variable 'comment-indent-function)
  (setq comment-indent-function 'lisp-comment-indent))
  @dots{}
@end group
@end smallexample

  Each of the different Lisp modes has a slightly different keymap.  For
example, Lisp mode binds @kbd{C-c C-z} to @code{run-lisp}, but the other

@var{function} t)} can uncompress the file and then put the uncompressed
file in the proper mode according to the name sans @samp{.gz}.

Here is an example of how to prepend several pattern pairs to
@code{auto-mode-alist}.  (You might use this sort of expression in your
init file.)

@smallexample
@group
(setq auto-mode-alist
  (append 

When you add an element to @code{minor-mode-alist}, use @code{assq} to
check for an existing element, to avoid duplication.  For example:

@smallexample
@group
(unless (assq 'leif-mode minor-mode-alist)
  (setq minor-mode-alist
        (cons '(leif-mode " Leif") minor-mode-alist)))
@end group
@end smallexample

@noindent
or like this, using @code{add-to-list} (@pxref{Setting Variables}):

@smallexample
@group
(add-to-list 'minor-mode-alist '(leif-mode " Leif"))
@end group
@end smallexample
@end itemize

  Global minor modes distributed with Emacs should if possible support
enabling and disabling via Custom (@pxref{Customization}).  To do this,
the first step is to define the mode variable with @code{defcustom}, and
specify @code{:type boolean}.

@node Mode Line Data
@subsection The Data Structure of the Mode Line
@cindex mode line construct

  The mode line contents are controlled by a data structure of lists,
strings, symbols, and numbers kept in buffer-local variables.  The data
structure is called a @dfn{mode line construct}, and it is built in
recursive fashion out of simpler mode line constructs.  The same data
structure is used for constructing frame titles (@pxref{Frame Titles})
and header lines (@pxref{Header Lines}).

@defvar mode-line-format
The value of this variable is a mode line construct with overall
responsibility for the mode line format.  The value of this variable
controls which other variables are used to form the mode line text, and

This buffer-local variable contains the mode line information on process
status in modes used for communicating with subprocesses.  It is
displayed immediately following the major mode name, with no intervening
space.  For example, its value in the @samp{*shell*} buffer is
@code{(":%s")}, which allows the shell to display its status along
with the major mode as: @samp{(Shell:run)}.  Normally this variable
is @code{nil}.
@end defvar

  Some variables are used by @code{minor-mode-alist} to display
a string for various minor modes when enabled.  This is a typical
example:

@defvar vc-mode
The variable @code{vc-mode}, buffer-local in each buffer, records
whether the buffer's visited file is maintained with version control,
and, if so, which kind.  Its value is a string that appears in the mode
line, or @code{nil} for no version control.
@end defvar

  The variable @code{default-mode-line-format} is where
@code{mode-line-format} usually gets its value:

@defvar default-mode-line-format
This variable holds the default @code{mode-line-format} for buffers
that do not override it.  This is the same as @code{(default-value
'mode-line-format)}.

@end group
 "   "
 global-mode-string
@group
 "   %[("
 ;; @r{@code{mode-line-mode-name} is a function}
 ;; @r{that copies the mode name and adds text
 ;; @r{properties to make it mouse-sensitive.}
 (:eval (mode-line-mode-name))
 mode-line-process
 minor-mode-alist 
 "%n" 
 ")%]--"

 "-%-")
@end group
@end example
@end defvar

@node %-Constructs
@subsection @code{%}-Constructs in the Mode Line

  The following table lists the recognized @code{%}-constructs and what
they mean.  In any construct except @samp{%%}, you can add a decimal

@table @code
@item %b
The current buffer name, obtained with the @code{buffer-name} function.
@xref{Buffer Names}.

@item %c
The current column number of point.

@item %f
The visited file name, obtained with the @code{buffer-file-name}
function.  @xref{Buffer File Name}.

@item %F
The title (only on a window system) or the name of the selected frame.
@xref{Window Frame Parameters}.

@item %l
The current line number of point, counting within the accessible portion
of the buffer.

@item %n
@samp{Narrow} when narrowing is in effect; nothing otherwise (see
@code{narrow-to-region} in @ref{Narrowing}).

@item %p
The percentage of the buffer text above the @strong{top} of window, or
@samp{Top}, @samp{Bottom} or @samp{All}.  Note that the default
mode-line specification truncates this to three characters.

@item %P
The percentage of the buffer text that is above the @strong{bottom} of
the window (which includes the text visible in the window, as well as
the text above the top), plus @samp{Top} if the top of the buffer is
visible on screen; or @samp{Bottom} or @samp{All}.

@item %s
The status of the subprocess belonging to the current buffer, obtained with
@code{process-status}.  @xref{Process Information}.

@item %t
Whether the visited file is a text file or a binary file.  This is a
meaningful distinction only on certain operating systems (@pxref{MS-DOS
File Types}).

@item %*
@samp{%} if the buffer is read only (see @code{buffer-read-only}); @*
@samp{*} if the buffer is modified (see @code{buffer-modified-p}); @*
@samp{-} otherwise.  @xref{Buffer Modification}.

read-only buffer.  @xref{Buffer Modification}.

@item %&
@samp{*} if the buffer is modified, and @samp{-} otherwise.

@item %[
An indication of the depth of recursive editing levels (not counting
minibuffer levels): one @samp{[} for each editing level.
@xref{Recursive Editing}.

@item %]
One @samp{]} for each recursive editing level (not counting minibuffer
levels).

@item %-
Dashes sufficient to fill the remainder of the mode line.

@item %%
The character @samp{%}---this is how to include a literal @samp{%} in a
string in which @code{%}-constructs are allowed.
@end table

The following two @code{%}-constructs are still supported, but they are
obsolete, since you can get the same results with the variables
@code{mode-name} and @code{global-mode-string}.

@code{local-map} property.
@end enumerate

  You use the @code{local-map} property to specify a keymap.  Like any
keymap, it can bind character keys and function keys; but that has no
effect, since it is impossible to move point into the mode line.  This
keymap can only take real effect for mouse clicks.

@node Header Lines
@subsection Window Header Lines
@cindex header line (of a window)

@cindex Imenu
  @dfn{Imenu} is a feature that lets users select a definition or
section in the buffer, from a menu which lists all of them, to go
directly to that location in the buffer.  Imenu works by constructing a
buffer index which lists the names and buffer positions of the
definitions, or other named portions of the buffer; then the user can
choose one of them and move point to it.  This section explains how to
customize how Imenu finds the definitions or buffer portions for a
particular major mode.

  The usual and simplest way is to set the variable
@code{imenu-generic-expression}:

@defvar imenu-generic-expression

@var{menu-title} is @code{nil}, the matches for this element go directly
in the top level of the buffer index.

The second item in the list, @var{regexp}, is a regular expression
(@pxref{Regular Expressions}); anything in the buffer that it matches is
considered a definition, something to mention in the buffer index.  The
third item, @var{subexp}, indicates which subexpression in @var{regexp}
matches the definition's name.

An element can also look like this:

@example
(@var{menu-title} @var{regexp} @var{index} @var{function} @var{arguments}@dots{})
@end example

Each match for this element creates a special index item which, if
selected by the user, calls @var{function} with arguments consisting of
the item name, the buffer position, and @var{arguments}.

For Emacs Lisp mode, @var{pattern} could look like this:

@c should probably use imenu-syntax-alist and \\sw rather than [-A-Za-z0-9+]
@example

  Another way to customize Imenu for a major mode is to set the
variables @code{imenu-prev-index-position-function} and
@code{imenu-extract-index-name-function}:

@defvar imenu-prev-index-position-function
If this variable is non-@code{nil}, its value should be a funtion that
finds the next ``definition'' to put in the buffer index, scanning
backward in the buffer from point.  It should return @code{nil} if it
doesn't find another ``definition'' before point.  Otherwise it shuould
leave point at the place it finds a ``definition,'' and return any
non-@code{nil} value.

Setting this variable makes it buffer-local in the current buffer.
@end defvar

@defvar imenu-extract-index-name-function

Setting this variable makes it buffer-local in the current buffer.
@end defvar

  The last way to customize Imenu for a major mode is to set the
variable @code{imenu-create-index-function}:

@defvar imenu-create-index-function
This variable specifies the function to use for creating a buffer index.
The function should take no arguments, and return an index for the
current buffer.  It is called within @code{save-excursion}, so where it

@cindex Font Lock Mode

  @dfn{Font Lock mode} is a feature that automatically attaches
@code{face} properties to certain parts of the buffer based on their
syntactic role.  How it parses the buffer depends on the major mode;
most major modes define syntactic criteria for which faces to use in
which contexts.  This section explains how to customize Font Lock for a
particular major mode.

  Font Lock mode finds text to highlight in two ways: through syntactic
parsing based on the syntax table, and through searching (usually for
regular expressions).  Syntactic fontification happens first; it finds
comments and string constants, and highlights them using
@code{font-lock-comment-face} and @code{font-lock-string-face}
(@pxref{Faces for Font Lock}).  Search-based fontification follows.

@menu
* Font Lock Basics::
* Search-based Fontification::
* Other Font Lock Variables::

 @var{syntax-alist} @var{syntax-begin} @var{other-vars}@dots{})
@end example

The first element, @var{keywords}, indirectly specifies the value of
@code{font-lock-keywords}.  It can be a symbol, a variable whose value
is the list to use for @code{font-lock-keywords}.  It can also be a list of
several such symbols, one for each possible level of fontification.  The
first symbol specifies how to do level 1 fontification, the second
symbol how to do level 2, and so on.

The second element, @var{keywords-only}, specifies the value of the

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} (see below).

All the remaining elements (if any) are collectively called
@var{other-vars}.  Each of these elements should have the form
@code{(@var{variable} . @var{value})}---which means, make @var{variable}
buffer-local and then set it to @var{value}.  You can use these
@var{other-vars} to set other variables that affect fontification,
aside from those you can control with the first five elements.
@end defvar

@node Search-based Fontification
@subsection Search-based Fontification

@cindex hooks

  A @dfn{hook} is a variable where you can store a function or functions
to be called on a particular occasion by an existing program.  Emacs
provides hooks for the sake of customization.  Most often, hooks are set
up in the init file (@pxref{Init File}), but Lisp programs can set them also.
@xref{Standard Hooks}, for a list of standard hook variables.

@cindex normal hook
  Most of the hooks in Emacs are @dfn{normal hooks}.  These variables
contain lists of functions to be called with no arguments.  When the

a Function}).  Most normal hook variables are initially void;
@code{add-hook} knows how to deal with this.

@cindex abnormal hook
  If the hook variable's name does not end with @samp{-hook}, that
indicates it is probably an @dfn{abnormal hook}.  Then you should look at its
documentation to see how to use the hook properly.

  If the variable's name ends in @samp{-functions} or @samp{-hooks},
then the value is a list of functions, but it is abnormal in that either
these functions are called with arguments or their values are used in

  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}.

@defun run-hooks &rest hookvars
This function takes one or more hook variable names as arguments, and
runs each hook in turn.  Each argument should be a symbol that is a hook
variable.  These arguments are processed in the order specified.

If a hook variable has a non-@code{nil} value, that value may be a
function or a list of functions.  If the value is a function (either a
lambda expression or a symbol with a function definition), it is called.
If it is a list, the elements are called, in order.  The hook functions

@defun run-hook-with-args-until-failure hook &rest args
This function is the way to run an abnormal hook which passes arguments
to the hook functions, and stops as soon as any hook function fails.  It
calls each of the hook functions, passing each of them the arguments
@var{args}, until some hook function returns @code{nil}.  Then it stops,
and returns @code{nil} if some hook function returned @code{nil}.
Otherwise it returns a non-@code{nil} value.
@end defun

@defun run-hook-with-args-until-success hook &rest args
This function is the way to run an abnormal hook which passes arguments
to the hook functions, and stops as soon as any hook function succeeds.

This function makes the hook variable @code{hook} buffer-local in the
current buffer.  When a hook variable is buffer-local, it can have
buffer-local and global hook functions, and @code{run-hooks} runs all of
them.

This function works by adding @code{t} as an element of the buffer-local
value.  That serves as a flag to use the hook functions listed in the default
value of the hook variable, as well as those listed in the buffer-local value.
Since @code{run-hooks} understands this flag, @code{make-local-hook}
works with all normal hooks.  It works for only some non-normal
hooks---those whose callers have been updated to understand this meaning
of @code{t}.