existing buffer without changing the buffer's text.
@item
-Write a documentation string for this command which describes the
+Write a documentation string for this command that describes the
special commands available in this mode. @kbd{C-h m}
(@code{describe-mode}) in your mode will display this string.
This keymap should be kept in a global variable named
@code{@var{modename}-mode-map}. Normally the library that defines the
-mode sets this variable. Use @code{defvar} to set the variable, so that
-it is not reinitialized if it already has a value. (Such
-reinitialization could discard customizations made by the user.)
+mode sets this variable.
+
+@xref{Tips for Defining}, for advice about how to write the code to set
+up the mode's keymap variable.
@item
@cindex syntax tables in modes
The mode may have its own syntax table or may share one with other
related modes. If it has its own syntax table, it should store this in
-a variable named @code{@var{modename}-mode-syntax-table}. The reasons
-for this are the same as for using a keymap variable. @xref{Syntax
+a variable named @code{@var{modename}-mode-syntax-table}. @xref{Syntax
Tables}.
@item
a variable named @code{@var{modename}-mode-abbrev-table}. @xref{Abbrev
Tables}.
+@item
+Use @code{defvar} to set mode-related variables, so that they are not
+reinitialized if they already have a value. (Such reinitialization
+could discard customizations made by the user.)
+
@item
@cindex buffer-local variables in modes
To make a buffer-local binding for an Emacs customization variable, use
@item
@cindex mode loading
-The top level forms in the file defining the mode should be written so
+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.
Even if you never load the file more than once, someone else will.
@end itemize
something special to be done if the user switches to a different major
mode. For best results, make this variable buffer-local, so that it
will disappear after doing its job and will not interfere with the
-subsequent major mode.
+subsequent major mode. @xref{Hooks}.
@end defvar
@node Example Major Modes
@smallexample
@group
(make-local-variable 'paragraph-start)
+ ;; @r{Having @samp{^} is not clean, but @code{page-delimiter}}
+ ;; @r{has them too, and removing those is a pain.}
(setq paragraph-start (concat "^$\\|" page-delimiter))
@dots{}
@end group
void. Then we set up the keymap if the variable is @code{nil}.
This code avoids changing the keymap or the variable if it is already
-set up. This lets the user customize the keymap if he or she so
-wishes.
+set up. This lets the user customize the keymap.
@smallexample
@group
(setq major-mode 'emacs-lisp-mode) ; @r{This is how @code{describe-mode}}
; @r{finds out what to describe.}
(setq mode-name "Emacs-Lisp") ; @r{This goes into the mode line.}
- (lisp-mode-variables nil) ; @r{This define various variables.}
+ (lisp-mode-variables nil) ; @r{This defines various variables.}
(run-hooks 'emacs-lisp-mode-hook)) ; @r{This permits the user to use a}
; @r{hook to customize the mode.}
@end group
@end deffn
@deffn Command normal-mode &optional find-file
- This function establishes the proper major mode and local variable
+This function establishes the proper major mode and local variable
bindings for the current buffer. First it calls @code{set-auto-mode},
then it runs @code{hack-local-variables} to parse, and bind or
evaluate as appropriate, any local variables.
- If the @var{find-file} argument to @code{normal-mode} is
+If the @var{find-file} argument to @code{normal-mode} is
non-@code{nil}, @code{normal-mode} assumes that the @code{find-file}
function is calling it. In this case, it may process a local variables
-list at the end of the file. The variable @code{enable-local-variables}
-controls whether to do so.
+list at the end of the file and in the @samp{-*-} line. The variable
+@code{enable-local-variables} controls whether to do so.
- If you run @code{normal-mode} interactively, the argument
+If you run @code{normal-mode} interactively, the argument
@var{find-file} is normally @code{nil}. In this case,
@code{normal-mode} unconditionally processes any local variables list.
@xref{File variables, , Local Variables in Files, emacs, The GNU Emacs
Manual}, for the syntax of the local variables section of a file.
@cindex file mode specification error
- @code{normal-mode} uses @code{condition-case} around the call to the
+@code{normal-mode} uses @code{condition-case} around the call to the
major mode function, so errors are caught and reported as a @samp{File
mode specification error}, followed by the original error message.
@end deffn
ask the user what to do for each file. The default value is @code{t}.
@end defopt
+@defvar ignored-local-variables
+This variable holds a list of variables that should not be
+set by a local variables list. Any value specified
+for one of these variables is ignored.
+@end defvar
+
+In addition to this list, any variable whose name has a non-@code{nil}
+@code{risky-local-variable} property is also ignored.
+
@defopt enable-local-eval
This variable controls processing of @samp{Eval:} in local variables
lists in files being visited. A value of @code{t} means process them
@cindex visited file mode
This function selects the major mode that is appropriate for the
current buffer. It may base its decision on the value of the @w{@samp{-*-}}
-line, on the visited file name (using @code{auto-mode-alist}), or on the
-value of a local variable). However, this function does not look for
+line, on the visited file name (using @code{auto-mode-alist}), on the
+@w{@samp{#!}} line (using @code{interpreter-mode-alist}), or on the
+value of a local variable. However, this function does not look for
the @samp{mode:} local variable near the end of a file; the
@code{hack-local-variables} function does that. @xref{Choosing Modes, ,
How Major Modes are Chosen, emacs, The GNU Emacs Manual}.
been specially prepared.
@end defopt
+@defun set-buffer-major-mode buffer
+This function sets the major mode of @var{buffer} to the value of
+@code{default-major-mode}. If that variable is @code{nil}, it uses
+the current buffer's major mode (if that is suitable).
+
+The low-level primitives for creating buffers do not use this function,
+but medium-level commands such as @code{switch-to-buffer} and
+@code{find-file-noselect} use it whenever they create buffers.
+@end defun
+
@defvar initial-major-mode
@cindex @samp{*scratch*}
The value of this variable determines the major mode of the initial
@smallexample
@group
(("^/tmp/fol/" . text-mode)
- ("\\.texinfo$" . texinfo-mode)
- ("\\.texi$" . texinfo-mode)
+ ("\\.texinfo\\'" . texinfo-mode)
+ ("\\.texi\\'" . texinfo-mode)
@end group
@group
- ("\\.el$" . emacs-lisp-mode)
- ("\\.c$" . c-mode)
- ("\\.h$" . c-mode)
+ ("\\.el\\'" . emacs-lisp-mode)
+ ("\\.c\\'" . c-mode)
+ ("\\.h\\'" . c-mode)
@dots{})
@end group
@end smallexample
@group
(setq auto-mode-alist
(append
- ;; @r{Filename starts with a dot.}
- '(("/\\.[^/]*$" . fundamental-mode)
- ;; @r{Filename has no dot.}
- ("[^\\./]*$" . fundamental-mode)
- ("\\.C$" . c++-mode))
+ ;; @r{File name starts with a dot.}
+ '(("/\\.[^/]*\\'" . fundamental-mode)
+ ;; @r{File name has no dot.}
+ ("[^\\./]*\\'" . fundamental-mode)
+ ;; @r{File name ends in @samp{.C}.}
+ ("\\.C\\'" . c++-mode))
auto-mode-alist))
@end group
@end smallexample
@defvar interpreter-mode-alist
This variable specifes major modes to use for scripts that specify a
-command interpreter in an @samp{!#} line. Its value is a list of
+command interpreter in an @samp{#!} line. Its value is a list of
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
@var{interpreter}.
-This variable is applicable only when the file name doesn't indicate
-which major mode to use.
+This variable is applicable only when the @code{auto-mode-alist} does
+not indicate which major mode to use.
@end defvar
@defun hack-local-variables &optional force
The handling of @code{enable-local-variables} documented for
@code{normal-mode} actually takes place here. The argument @var{force}
-reflects the argument @var{find-file} given to @code{normal-mode}.
+usually comes from the argument @var{find-file} given to
+@code{normal-mode}.
@end defun
@node Mode Help
@defvar major-mode
This variable holds the symbol for the current buffer's major mode.
-This symbol should have a function definition which is the command to
+This symbol should have a function definition that is the command to
switch to that major mode. The @code{describe-mode} function uses the
-documentation string of this symbol as the documentation of the major
+documentation string of the function as the documentation of the major
mode.
@end defvar
It's often useful to define a new major mode in terms of an existing
one. An easy way to do this is to use @code{define-derived-mode}.
-@defmac define-derived-mode variant parent name doc body@dots{}
+@defmac define-derived-mode variant parent name docstring body@dots{}
This construct defines @var{variant} as a major mode command, using
-@var{name} as the string form of the mode which.
+@var{name} as the string form of the mode name.
-The definition of the command is to call the function @var{parent}, then
-override certain aspects of that parent mode:
+The new command @var{variant} is defined to call the function
+@var{parent}, then override certain aspects of that parent mode:
@itemize @bullet
@item
@code{@var{parent}-map}, if it is not already set.
@item
-The new mode has its own syntax table, taken from the variable
+The new mode has its own syntax table, kept in the variable
@code{@var{variant}-syntax-table}.
@code{define-derived-mode} initializes this variable by copying
@code{@var{parent}-syntax-table}, if it is not already set.
@item
-The new mode has its own abbrev table, taken from the variable
+The new mode has its own abbrev table, kept in the variable
@code{@var{variant}-abbrev-table}.
@code{define-derived-mode} initializes this variable by copying
@code{@var{parent}-abbrev-table}, if it is not already set.
@end itemize
In addition, you can specify how to override other aspects of
-@var{parent-mode} with @var{body}. The command @var{variant}
+@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}.
A minor mode is often much more difficult to implement than a major
mode. One reason is that you should be able to activate and deactivate
-minor modes in any order.
-
-and restore the environment of the major mode to the state it was in
-before the minor mode was activated.
+minor modes in any order. A minor mode should be able to have its
+desired effect regardless of the major mode and regardless of the other
+minor modes in effect.
Often the biggest problem in implementing a minor mode is finding a
way to insert the necessary hook into the rest of Emacs. Minor mode
-keymaps make this easier in Emacs 19 than it used to be.
+keymaps make this easier than it used to be.
@menu
* Minor Mode Conventions:: Tips for writing a minor mode.
list whose @sc{car} is such an integer or symbol; it should turn the
mode off otherwise.
-Here is an example taken from the definition of @code{overwrite-mode}.
-It shows the use of @code{overwrite-mode} as a variable which enables or
-disables the mode's behavior.
+Here is an example taken from the definition of @code{transient-mark-mode}.
+It shows the use of @code{transient-mark-mode} as a variable that enables or
+disables the mode's behavior, and also shows the proper way to toggle,
+enable or disable the minor mode based on the raw prefix argument value.
@smallexample
@group
-(setq overwrite-mode
- (if (null arg) (not overwrite-mode)
+(setq transient-mark-mode
+ (if (null arg) (not transient-mark-mode)
(> (prefix-numeric-value arg) 0)))
@end group
@end smallexample
(@var{mode-variable} @var{string})
@end smallexample
-Here @var{mode-variable} is the variable that controls enablement of the
+Here @var{mode-variable} is the variable that controls enabling of the
minor mode, and @var{string} is a short string, starting with a space,
to represent the mode in the mode line. These strings must be short so
that there is room for several of them at once.
@node Keymaps and Minor Modes
@subsection Keymaps and Minor Modes
-As of Emacs version 19, each minor mode can have its own keymap which is
-active when the mode is enabled. @xref{Active Keymaps}. To set up a
-keymap for a minor mode, add an element to the alist
-@code{minor-mode-map-alist}.
+ 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}.
@cindex @code{self-insert-command}, minor modes
One use of minor mode keymaps is to modify the behavior of certain
substituting your own definition of @code{self-insert-command} for the
standard one. The editor command loop handles this function specially.)
-@defvar minor-mode-map-alist
-This variable is an alist of elements that look like this:
-
-@example
-(@var{variable} . @var{keymap})
-@end example
-
-@noindent
-where @var{variable} is the variable which indicates whether the minor
-mode is enabled, and @var{keymap} is the keymap. The keymap
-@var{keymap} is active whenever @var{variable} has a non-@code{nil}
-value.
-
-Note that elements of @code{minor-mode-map-alist} do not have the same
-structure as elements of @code{minor-mode-alist}. The map must be the
-@sc{cdr} of the element; a list with the map as the second element will
-not do.
-
-What's more, the keymap itself must appear in the @sc{cdr}. It does not
-work to store a variable in the @sc{cdr} and make the map the value of
-that variable.
-
-When more than one minor mode keymap is active, their order of priority
-is the order of @code{minor-mode-map-alist}. But you should design
-minor modes so that they don't interfere with each other. If you do
-this properly, the order will not matter.
-@end defvar
-
@node Mode Line Format
@section Mode Line Format
@cindex mode line
- Each Emacs window (aside from minibuffer windows) includes a mode line
+ Each Emacs window (aside from minibuffer windows) includes a mode line,
which displays status information about the buffer displayed in the
-window. The mode line contains information about the buffer such as its
+window. The mode line contains information about the buffer, such as its
name, associated file, depth of recursive editing, and the major and
-minor modes of the buffer.
+minor modes.
This section describes how the contents of the mode line are
controlled. It is in the chapter on modes because much of the
@code{mode-line-format} is a buffer-local variable that holds a
template used to display the mode line of the current buffer. All
-windows for the same buffer use the same @code{mode-line-format} and the
-mode lines will appear the same (except for scrolling percentages and
+windows for the same buffer use the same @code{mode-line-format} and
+their mode lines appear the same (except for scrolling percentages and
line numbers).
The mode line of a window is normally updated whenever a different
buffer is shown in the window, or when the buffer's modified-status
changes from @code{nil} to @code{t} or vice-versa. If you modify any of
-the variables referenced by @code{mode-line-format}, you may want to
-force an update of the mode line so as to display the new information.
+the variables referenced by @code{mode-line-format} (@pxref{Mode Line
+Variables}), you may want to force an update of the mode line so as to
+display the new information.
@c Emacs 19 feature
@defun force-mode-line-update
@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
+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.
+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
For most purposes, it is sufficient to alter the variables referenced by
@code{mode-line-format}.
- A mode line construct may be a list, cons cell, symbol, or string. If
-the value is a list, each element may be a list, a cons cell, a symbol,
-or a string.
+ A mode line construct may be a list, a symbol, or a string. If the
+value is a list, each element may be a list, a symbol, or a string.
@table @code
@cindex percent symbol in mode line
@item @var{string}
A string as a mode line construct is displayed verbatim in the mode line
-except for @dfn{@code{%}-constructs}. Decimal digits after the @code{%}
+except for @dfn{@code{%}-constructs}. Decimal digits after the @samp{%}
specify the field width for space filling on the right (i.e., the data
is left justified). @xref{%-Constructs}.
@item @var{symbol}
A symbol as a mode line construct stands for its value. The value of
-@var{symbol} is used in place of @var{symbol} unless @var{symbol} is
-@code{t} or @code{nil}, or is void, in which case @var{symbol} is
-ignored.
+@var{symbol} is used as a mode line construct, in place of @var{symbol}.
+However, the symbols @code{t} and @code{nil} are ignored; so is any
+symbol whose value is void.
There is one exception: if the value of @var{symbol} is a string, it is
-processed verbatim in that the @code{%}-constructs are not recognized.
+displayed verbatim: the @code{%}-constructs are not recognized.
@item (@var{string} @var{rest}@dots{}) @r{or} (@var{list} @var{rest}@dots{})
-A list whose first element is a string or list, means to concatenate all
-the elements. This is the most common form of mode line construct.
+A list whose first element is a string or list means to process all the
+elements recursively and concatenate the results. This is the most
+common form of mode line construct.
@item (@var{symbol} @var{then} @var{else})
A list whose first element is a symbol is a conditional. Its meaning
depends on the value of @var{symbol}. If the value is non-@code{nil},
-the second element of the list (@var{then}) is processed recursively as
-a mode line element. But if the value of @var{symbol} is @code{nil},
-the third element of the list (if there is one) is processed
-recursively.
+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} @var{rest}@dots{})
A list whose first element is an integer specifies truncation or
if @var{width} is negative) on the right.
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")}.
+the top of the window is to use a list like this: @code{(-3 "%p")}.
@end table
If you do alter @code{mode-line-format} itself, the new value should
-use all the same variables that are used by the default value, rather
-than duplicating their contents or displaying the information in another
-fashion. This way, customizations made by the user, by libraries (such
-as @code{display-time}) and by major modes via changes to those
-variables remain effective.
+use the same variables that appear in the default value (@pxref{Mode
+Line Variables}), rather than duplicating their contents or displaying
+the information in another fashion. This way, customizations made by
+the user or by Lisp programs (such as @code{display-time} and major
+modes) via changes to those variables remain effective.
@cindex Shell mode @code{mode-line-format}
Here is an example of a @code{mode-line-format} that might be
-useful for @code{shell-mode} since it contains the hostname and default
+useful for @code{shell-mode}, since it contains the hostname and default
directory.
@example
'default-directory
" "
'global-mode-string
- " %[(" 'mode-name
+ " %[("
+ 'mode-name
+ 'mode-line-process
'minor-mode-alist
"%n"
- 'mode-line-process
")%]----"
@group
- (line-number-mode "L%l--")
+ '(line-number-mode "L%l--")
'(-3 . "%p")
"-%-"))
@end group
@code{mode-line-format} were changed to use them.
@defvar mode-line-modified
- This variable holds the value of the mode-line construct that displays
+This variable holds the value of the mode-line construct that displays
whether the current buffer is modified.
- The default value of @code{mode-line-modified} is
-@code{("--%1*%1*-")}. This means that the mode line displays
-@samp{--**-} if the buffer is modified, @samp{-----} if the buffer is
-not modified, and @samp{--%%-} if the buffer is read only.
+The default value of @code{mode-line-modified} is @code{("--%1*%1+-")}.
+This means that the mode line displays @samp{--**-} if the buffer is
+modified, @samp{-----} if the buffer is not modified, @samp{--%%-} if
+the buffer is read only, and @samp{--%*--} if the buffer is read only
+and modified.
Changing this variable does not force an update of the mode line.
@end defvar
@defvar mode-line-buffer-identification
- This variable identifies the buffer being displayed in the window.
-Its default value is @samp{Emacs: %17b}, which means that it displays
-@samp{Emacs:} followed by the buffer name. You may want to change this
-in modes such as Rmail that do not behave like a ``normal'' Emacs.
+This variable identifies the buffer being displayed in the window. Its
+default value is @code{("%F: %17b")}, which means that it usually
+displays @samp{Emacs:} followed by seventeen characters of the buffer
+name. (In a terminal frame, it displays the frame name instead of
+@samp{Emacs}; this has the effect of showing the frame number.) You may
+want to change this in modes such as Rmail that do not behave like a
+``normal'' Emacs.
@end defvar
@defvar global-mode-string
@end defvar
@defvar mode-name
- This buffer-local variable holds the ``pretty'' name of the current
+This buffer-local variable holds the ``pretty'' name of the current
buffer's major mode. Each major mode should set this variable so that the
mode name will appear in the mode line.
@end defvar
@defvar minor-mode-alist
- This variable holds an association list whose elements specify how the
+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:
@example
@group
minor-mode-alist
-@result{} ((abbrev-mode " Abbrev")
- (overwrite-mode " Ovwrt")
+@result{} ((vc-mode vc-mode)
+ (abbrev-mode " Abbrev")
+ (overwrite-mode overwrite-mode)
(auto-fill-function " Fill")
- (defining-kbd-macro " Def"))
+ (defining-kbd-macro " Def")
+ (isearch-mode isearch-mode))
@end group
@end example
-@noindent
-(In earlier Emacs versions, @code{auto-fill-function} was called
-@code{auto-fill-hook}.)
-
- @code{minor-mode-alist} is not buffer-local. The variables mentioned
+@code{minor-mode-alist} is not buffer-local. The variables mentioned
in the alist should be buffer-local if the minor mode can be enabled
separately in each buffer.
@end defvar
@end defvar
@defvar default-mode-line-format
- This variable holds the default @code{mode-line-format} for buffers
+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)}.
- The default value of @code{default-mode-line-format} is:
+The default value of @code{default-mode-line-format} is:
@example
@group
mode-name
@end group
@group
+ mode-line-process
minor-mode-alist
"%n"
- mode-line-process
")%]----"
+ (line-number-mode "L%l--")
(-3 . "%p")
"-%-")
@end group
@end example
@end defvar
+@defvar vc-mode
+The variable @code{vc-mode}, 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.
+they mean. In any construct except @samp{%%}, you can add a decimal
+integer after the @samp{%} to specify how many characters to display.
@table @code
@item %b
The visited file name, obtained with the @code{buffer-file-name}
function. @xref{Buffer File Name}.
+@item %F
+The name of the selected frame.
+
+@item %c
+The current column number of point.
+
+@item %l
+The current line number of point.
+
@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}.
@item %+
-@samp{*} if the buffer is modified, and otherwise @samp{-}.
+@samp{*} if the buffer is modified (see @code{buffer-modified-p}); @*
+@samp{%} if the buffer is read only (see @code{buffer-read-only}); @*
+@samp{-} otherwise. This differs from @samp{%*} only for a modified
+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 percent of the buffer above the @strong{top} of window, or
+The percentage of the buffer text above the @strong{top} of window, or
@samp{Top}, @samp{Bottom} or @samp{All}.
@item %P
@code{add-hook} knows how to deal with this.
As for abnormal hooks, those whose names end in @samp{-function} have
-a value which is a single function. Those whose names end in
-@samp{-hooks} have a value which is a list of functions. Any hook which
+a value that is a single function. Those whose names end in
+@samp{-hooks} have a value that is a list of functions. Any hook that
is abnormal is abnormal because a normal hook won't do the job; either
the functions are called with arguments, or their values are meaningful.
The name shows you that the hook is abnormal and that you should look at
its documentation string to see how to use it properly.
- Most major modes run hooks as the last step of initialization. This
-makes it easy for a user to customize the behavior of the mode, by
-overriding the local variable assignments already made by the mode. But
-hooks are used in other contexts too. For example, the hook
-@code{suspend-hook} runs just before Emacs suspends itself
-(@pxref{Suspending Emacs}).
+ Major mode functions are supposed to run a hook called the @dfn{mode
+hook} as the last step of initialization. This makes it easy for a user
+to customize the behavior of the mode, by overriding the local variable
+assignments already made by the mode. But hooks are used in other
+contexts too. For example, the hook @code{suspend-hook} runs just
+before Emacs suspends itself (@pxref{Suspending Emacs}).
- Here's an expression you can put in your @file{.emacs} file to turn on
-Auto Fill mode when in Lisp Interaction mode:
+ Here's an expression that uses a mode hook to turn on Auto Fill mode
+when in Lisp Interaction mode:
@example
(add-hook 'lisp-interaction-mode-hook 'turn-on-auto-fill)
(setq c++-mode-hook c-mode-hook)
@end group
-@end example
-
- Finally, here is an example of how to use the Text mode hook to
-provide a customized mode line for buffers in Text mode, displaying the
-default directory in addition to the standard components of the
-mode line. (This may cause the mode line to run out of space if you
-have very long file names or display the time and load.)
-
-@example
-@group
-(add-hook 'text-mode-hook
- (function (lambda ()
- (setq mode-line-format
- '(mode-line-modified
- "Emacs: %14b"
- " "
-@end group
- default-directory
- " "
- global-mode-string
- "%[("
- mode-name
- minor-mode-alist
-@group
- "%n"
- mode-line-process
- ") %]---"
- (-3 . "%p")
- "-%-")))))
-@end group
@end example
At the appropriate time, Emacs uses the @code{run-hooks} function to
-run particular hooks. This function calls the hook functions you have
-added with @code{add-hooks}.
+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
called. If it is a list, the elements are called, in order.
The hook functions are called with no arguments.
-For example, here's how @code{emacs-lisp-hooks} runs its mode hook:
+For example, here's how @code{emacs-lisp-mode} runs its mode hook:
@example
(run-hooks 'emacs-lisp-mode-hook)
@end example
@end defun
-@defun add-hook hook function &optional append
+@defun add-hook hook function &optional append local
This function is the handy way to add function @var{function} to hook
-variable @var{hook}. For example,
+variable @var{hook}. The argument @var{function} may be any valid Lisp
+function with the proper number of arguments. For example,
@example
(add-hook 'text-mode-hook 'my-text-hook-function)
@noindent
adds @code{my-text-hook-function} to the hook called @code{text-mode-hook}.
+You can use @code{add-hook} for abnormal hooks as well as for normal
+hooks.
+
It is best to design your hook functions so that the order in which they
are executed does not matter. Any dependence on the order is ``asking
for trouble.'' However, the order is predictable: normally,
If the optional argument @var{append} is non-@code{nil}, the new hook
function goes at the end of the hook list and will be executed last.
+
+If @var{local} is non-@code{nil}, that says to make the new hook
+function local to the current buffer. Before you can do this, you must
+make the hook itself buffer-local by calling @code{make-local-hook}
+(@strong{not} @code{make-local-variable}). If the hook itself is not
+buffer-local, then the value of @var{local} makes no difference---the
+hook function is always global.
@end defun
-@defun remove-hook hook function
+@defun remove-hook hook function &optional local
This function removes @var{function} from the hook variable @var{hook}.
+
+If @var{local} is non-@code{nil}, that says to remove @var{function}
+from the local hook list instead of from the global hook list. If the
+hook itself is not buffer-local, then the value of @var{local} makes no
+difference.
+@end defun
+
+@defun make-local-hook hook
+This function makes the hook variable @code{hook} local to the current
+buffer. When a hook variable is local, it can have 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 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}.
+
+Do not use @code{make-local-variable} directly for hook variables; it is
+not sufficient.
@end defun