Mercurial > emacs

--- a/lispref/modes.texi	Sat May 14 15:39:15 2005 +0000
+++ b/lispref/modes.texi	Sat May 14 16:15:15 2005 +0000
@@ -20,6 +20,7 @@
 @ref{Keymaps}, and @ref{Syntax Tables}.

 @menu
+* Hooks::              How to use hooks; how to write code that provides hooks.
 * Major Modes::        Defining major modes.
 * Minor Modes::        Defining minor modes.
 * Mode Line Format::   Customizing the text that appears in the mode line.
@@ -28,13 +29,153 @@
 * Font Lock Mode::     How modes can highlight text according to syntax.
 * Desktop Save Mode::  How modes can have buffer state saved between
                          Emacs sessions.
-* Hooks::              How to use hooks; how to write code that provides hooks.
 @end menu

+@node Hooks
+@section Hooks
+@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
+hook name ends in @samp{-hook}, that tells you it is normal.  We try to
+make all hooks normal, as much as possible, so that you can use them in
+a uniform way.
+
+  Every major mode function is supposed to run a normal 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
+buffer-local variable assignments already made by the mode.  Most
+minor modes also run a mode hook at their end.  But hooks are used in
+other contexts too.  For example, the hook @code{suspend-hook} runs
+just before Emacs suspends itself (@pxref{Suspending Emacs}).
+
+  The recommended way to add a hook function to a normal hook is by
+calling @code{add-hook} (see below).  The hook functions may be any of
+the valid kinds of functions that @code{funcall} accepts (@pxref{What
+Is a Function}).  Most normal hook variables are initially void;
+@code{add-hook} knows how to deal with this.  You can add hooks either
+globally or buffer-locally with @code{add-hook}.
+
+@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
+some way.  You can use @code{add-hook} to add a function to the list,
+but you must take care in writing the function.  (A few of these
+variables, notably those ending in @samp{-hooks}, are actually
+normal hooks which were named before we established the convention of
+using @samp{-hook} for them.)
+
+  If the variable's name ends in @samp{-function}, then its value
+is just a single function, not a list of functions.
+
+  Here's an example 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)
+@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}.
+
+@defun run-hooks &rest hookvars
+This function takes one or more normal hook variable names as
+arguments, and runs each hook in turn.  Each argument should be a
+symbol that is a normal 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.  (The former option is considered
+obsolete.)  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
+that isn't a function, its elements are called, consecutively.  All
+the hook functions are called with no arguments.
+@end defun
+
+@defun run-hook-with-args hook &rest args
+This function is the way to run an abnormal hook and always call all
+of the hook functions.  It calls each of the hook functions one by
+one, passing each of them the arguments @var{args}.
+@end defun
+
+@defun run-hook-with-args-until-failure hook &rest args
+This function is the way to run an abnormal hook until one of the hook
+functions fails.  It calls each of the hook functions, passing each of
+them the arguments @var{args}, until some hook function returns
+@code{nil}.  It then stops and returns @code{nil}.  If none of the
+hook functions return @code{nil}, 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 until a hook function
+succeeds.  It calls each of the hook functions, passing each of them
+the arguments @var{args}, until some hook function returns
+non-@code{nil}.  Then it stops, and returns whatever was returned by
+the last hook function that was called.  If all hook functions return
+@code{nil}, it returns @code{nil} as well.
+@end defun
+
+@defun add-hook hook function &optional append local
+This function is the handy way to add function @var{function} to hook
+variable @var{hook}.  You can use it for abnormal hooks as well as for
+normal hooks.  @var{function} can be any Lisp function that can accept
+the proper number of arguments for @var{hook}.  For example,
+
+@example
+(add-hook 'text-mode-hook 'my-text-hook-function)
+@end example
+
+@noindent
+adds @code{my-text-hook-function} to the hook called @code{text-mode-hook}.
+
+If @var{function} is already present in @var{hook} (comparing using
+@code{equal}), then @code{add-hook} does not add it a second time.
+
+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,
+@var{function} goes at the front of the hook list, so it will be
+executed first (barring another @code{add-hook} call).  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.
+
+@code{add-hook} can handle the cases where @var{hook} is void or its
+value is a single function; it sets or changes the value to a list of
+functions.
+
+If @var{local} is non-@code{nil}, that says to add @var{function} to
+the buffer-local hook list instead of to the global hook list.  If
+needed, this makes the hook buffer-local and adds @code{t} to the
+buffer-local value.  The latter acts as a flag to run the hook
+functions in the default value as well as in the local value.
+@end defun
+
+@defun remove-hook hook function &optional local
+This function removes @var{function} from the hook variable
+@var{hook}.  It compares @var{function} with elements of @var{hook}
+using @code{equal}, so it works for both symbols and lambda
+expressions.
+
+If @var{local} is non-@code{nil}, that says to remove @var{function}
+from the buffer-local hook list instead of from the global hook list.
+@end defun
+
 @node Major Modes
 @section Major Modes
 @cindex major mode
-@cindex Fundamental mode

   Major modes specialize Emacs for editing particular kinds of text.
 Each buffer has only one major mode at a time.  For each major mode
@@ -44,6 +185,23 @@
 buffer, such as a local keymap.  The effect lasts until you switch
 to another major mode in the same buffer.

+@menu
+* Major Mode Basics::
+* Major Mode Conventions::  Coding conventions for keymaps, etc.
+* Example Major Modes::     Text mode and Lisp modes.
+* Auto Major Mode::         How Emacs chooses the major mode automatically.
+* Mode Help::               Finding out how to use a mode.
+* Derived Modes::           Defining a new major mode based on another major
+                              mode.
+* Generic Modes::           Defining a simple major mode that supports
+                              comment syntax and Font Lock mode.
+* Mode Hooks::              Hooks run at the end of major mode functions.
+@end menu
+
+@node Major Mode Basics
+@subsection Major Mode Basics
+@cindex Fundamental mode
+
   The least specialized major mode is called @dfn{Fundamental mode}.
 This mode has no mode-specific definitions or variable settings, so each
 Emacs command behaves in its default manner, and each option is in its
@@ -95,18 +253,6 @@
 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.
-* Auto Major Mode::         How Emacs chooses the major mode automatically.
-* Mode Help::               Finding out how to use a mode.
-* Derived Modes::           Defining a new major mode based on another major
-                              mode.
-* Generic Modes::           Defining a simple major mode that supports
-                              comment syntax and Font Lock mode.
-* Mode Hooks::              Hooks run at the end of major mode functions.
-@end menu
-
 @node Major Mode Conventions
 @subsection Major Mode Conventions

@@ -240,7 +386,7 @@
 in a variable named @code{@var{modename}-mode-abbrev-table}.  If the
 major mode command defines any abbrevs itself, it should pass @code{t}
 for the @var{system-flag} argument to @code{define-abbrev}.
-@xref{Abbrev Tables}.
+@xref{Defining Abbrevs}.

 @item
 The mode should specify how to do highlighting for Font Lock mode, by
@@ -326,8 +472,11 @@
 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}.  Otherwise, it is sufficient to add the element in the
-file that contains the mode definition.  @xref{Auto Major Mode}.
+@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}.

 @item
 In the comments that document the file, you should provide a sample
@@ -635,21 +784,28 @@

 @deffn Command normal-mode &optional find-file
 This function establishes the proper major mode and buffer-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, the file's local variables.
+bindings for the current buffer.  First it calls @code{set-auto-mode}
+(see below), then it runs @code{hack-local-variables} to parse, and
+bind or evaluate as appropriate, the file's local variables
+(@pxref{File Local Variables}).

 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 and in the @samp{-*-} line.  The variable
+it.  In this case, it may process local variables in the @samp{-*-}
+line or at the end of the file.  The variable
 @code{enable-local-variables} controls whether to do so.  @xref{File
-variables, , Local Variables in Files, emacs, The GNU Emacs Manual}, for
-the syntax of the local variables section of a file.
+Variables, , Local Variables in Files, emacs, The GNU Emacs Manual},
+for the syntax of the local variables section of a file.

 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.
+@code{normal-mode} unconditionally processes any file local variables.
+
+If @code{normal-mode} processes the local variables list and this list
+specifies a major mode, that mode overrides any mode chosen by
+@code{set-auto-mode}.  If neither @code{set-auto-mode} nor
+@code{hack-local-variables} specify a major mode, the buffer stays in
+the major mode determined by @code{default-major-mode} (see below).

 @cindex file mode specification error
 @code{normal-mode} uses @code{condition-case} around the call to the
@@ -657,16 +813,25 @@
 mode specification error},  followed by the original error message.
 @end deffn

-@defun set-auto-mode
+@defun set-auto-mode &optional keep-mode-if-same
 @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}), on the
-@w{@samp{#!}} line (using @code{interpreter-mode-alist}), or on the
-file's local variables list.  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}.
+current buffer.  It bases its decision (in order of precedence) on
+the @w{@samp{-*-}} line, on the @w{@samp{#!}} line (using
+@code{interpreter-mode-alist}), on the text at the beginning of the
+buffer (using @code{magic-mode-alist}), and finally on the visited
+file name (using @code{auto-mode-alist}).  @xref{Choosing Modes, , How
+Major Modes are Chosen, emacs, The GNU Emacs Manual}.  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.
+If @code{enable-local-variables} is @code{nil}, @code{set-auto-mode}
+does not check the @w{@samp{-*-}} line for a mode tag either.
+
+If @var{keep-mode-if-same} is non-@code{nil}, this function does not
+call the mode command if the buffer is already in the proper major
+mode.  For instance, @code{set-visited-file-name} sets this to
+@code{t} to avoid killing buffer local variables that the user may
+have set.
 @end defun

 @defopt default-major-mode
@@ -674,8 +839,8 @@
 standard value is @code{fundamental-mode}.

 If the value of @code{default-major-mode} is @code{nil}, Emacs uses
-the (previously) current buffer's major mode for the major mode of a new
-buffer.  However, if that major mode symbol has a @code{mode-class}
+the (previously) current buffer's major mode as the default major mode
+of a new buffer.  However, if that major mode symbol has a @code{mode-class}
 property with value @code{special}, then it is not used for new buffers;
 Fundamental mode is used instead.  The modes that have this property are
 those such as Dired and Rmail that are useful only with text that has
@@ -684,28 +849,50 @@

 @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).
+@code{default-major-mode}; if that variable is @code{nil}, it uses the
+current buffer's major mode (if that is suitable).  As an exception,
+if @var{buffer}'s name is @samp{*scratch*}, it sets the mode to
+@code{initial-major-mode}.

 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
+@defopt initial-major-mode
 @cindex @samp{*scratch*}
 The value of this variable determines the major mode of the initial
 @samp{*scratch*} buffer.  The value should be a symbol that is a major
 mode command.  The default value is @code{lisp-interaction-mode}.
+@end defopt
+
+@defvar interpreter-mode-alist
+This variable specifies major modes to use for scripts that specify a
+command interpreter in a @samp{#!} line.  Its value is an alist with
+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}.
+@end defvar
+
+@defvar magic-mode-alist
+This variable's value is an alist with elements of the form
+@code{(@var{regexp} .  @var{function})}, where @var{regexp} is a
+regular expression and @var{function} is a function or @code{nil}.
+After visiting a file, @code{set-auto-mode} calls @var{function} if
+the text at the beginning of the buffer matches @var{regexp} and
+@var{function} is non-@code{nil}; if @var{function} is @code{nil},
+@code{auto-mode-alist} gets to decide the mode.
 @end defvar

 @defvar auto-mode-alist
 This variable contains an association list of file name patterns
-(regular expressions; @pxref{Regular Expressions}) and corresponding
-major mode commands.  Usually, the file name patterns test for suffixes,
-such as @samp{.el} and @samp{.c}, but this need not be the case.  An
-ordinary element of the alist looks like @code{(@var{regexp} .
-@var{mode-function})}.
+(regular expressions) and corresponding major mode commands.  Usually,
+the file name patterns test for suffixes, such as @samp{.el} and
+@samp{.c}, but this need not be the case.  An ordinary element of the
+alist looks like @code{(@var{regexp} .  @var{mode-function})}.

 For example,

@@ -724,9 +911,11 @@
 @end smallexample

 When you visit a file whose expanded file name (@pxref{File Name
-Expansion}) matches a @var{regexp}, @code{set-auto-mode} calls the
-corresponding @var{mode-function}.  This feature enables Emacs to select
-the proper major mode for most files.
+Expansion}), with version numbers and backup suffixes removed using
+@code{file-name-sans-versions} (@pxref{File Name Components}), matches
+a @var{regexp}, @code{set-auto-mode} calls the corresponding
+@var{mode-function}.  This feature enables Emacs to select the proper
+major mode for most files.

 If an element of @code{auto-mode-alist} has the form @code{(@var{regexp}
 @var{function} t)}, then after calling @var{function}, Emacs searches
@@ -755,19 +944,6 @@
 @end smallexample
 @end defvar

-@defvar interpreter-mode-alist
-This variable specifies major modes to use for scripts that specify a
-command interpreter in a @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
-an interpreter which matches @var{interpreter}.  The value of
-@var{interpreter} is actually a regular expression.
-
-This variable is applicable only when the @code{auto-mode-alist} does
-not indicate which major mode to use.
-@end defvar
-
 @node Mode Help
 @subsection Getting Help about a Major Mode
 @cindex mode help
@@ -804,36 +980,38 @@
   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 docstring body@dots{}
+@defmac define-derived-mode variant parent name docstring keyword-args@dots{} body@dots{}
 This construct defines @var{variant} as a major mode command, using
-@var{name} as the string form of the mode name.
+@var{name} as the string form of the mode name.  @var{variant} and
+@var{parent} should be unquoted symbols.

 The new command @var{variant} is defined to call the function
 @var{parent}, then override certain aspects of that parent mode:

 @itemize @bullet
 @item
-The new mode has its own keymap, named @code{@var{variant}-map}.
-@code{define-derived-mode} initializes this map to inherit from
-@code{@var{parent}-map}, if it is not already set.
+The new mode has its own sparse keymap, named
+@code{@var{variant}-map}.  @code{define-derived-mode}
+makes the parent mode's keymap the parent of the new map, unless
+@code{@var{variant}-map} is already set and already has a parent.

 @item
 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.
+@code{@var{variant}-syntax-table}, unless you override this using the
+@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}.

 @item
 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.
+@code{@var{variant}-abbrev-table}, unless you override this using the
+@code{:abbrev-table} keyword (see below).

 @item
-The new mode has its own mode hook, @code{@var{variant}-hook},
-which it runs in standard fashion as the very last thing that it does.
-(The new mode also runs the mode hook of @var{parent} as part
-of calling @var{parent}.)
+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}.
 @end itemize

 In addition, you can specify how to override other aspects of
@@ -841,9 +1019,38 @@
 evaluates the forms in @var{body} after setting up all its usual
 overrides, just before running @code{@var{variant}-hook}.

-The argument @var{docstring} specifies the documentation string for the
-new mode.  If you omit @var{docstring}, @code{define-derived-mode}
-generates a documentation string.
+You can also specify @code{nil} for @var{parent}.  This gives the new
+mode no parent.  Then @code{define-derived-mode} behaves as described
+above, but, of course, omits all actions connected with @var{parent}.
+
+The argument @var{docstring} specifies the documentation string for
+the new mode.  @code{define-derived-mode} adds some general
+information about the mode's hook, followed by the mode's keymap, at
+the end of this docstring.  If you omit @var{docstring},
+@code{define-derived-mode} generates a documentation string.
+
+The @var{keyword-args} are pairs of keywords and values.  The values
+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
+@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.)
+
+@item :abbrev-table
+You can use this to explicitly specify an abbrev table for the new
+mode.  If you specify a @code{nil} value, the new mode uses the same
+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.)
+@end table

 Here is a hypothetical example:

@@ -1295,6 +1502,19 @@
 information displayed in the mode line relates to the enabled major and
 minor modes.

+@menu
+* Mode Line Basics::
+* Mode Line Data::        The data structure that controls the mode line.
+* Mode Line Variables::   Variables used in that data structure.
+* %-Constructs::          Putting information into a mode line.
+* Properties in Mode::    Using text properties in the mode line.
+* Header Lines::          Like a mode line, but at the top.
+* Emulating Mode Line::   Formatting text as the mode line would.
+@end menu
+
+@node Mode Line Basics
+@subsection Mode Line Basics
+
   @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}, so
@@ -1336,15 +1556,6 @@
 line at once; if the variables call for both, only the mode line
 actually appears.

-@menu
-* Mode Line Data::        The data structure that controls the mode line.
-* Mode Line Variables::   Variables used in that data structure.
-* %-Constructs::          Putting information into a mode line.
-* Properties in Mode::    Using text properties in the mode line.
-* Header Lines::          Like a mode line, but at the top.
-* Emulating Mode Line::   Formatting text as the mode line would.
-@end menu
-
 @node Mode Line Data
 @subsection The Data Structure of the Mode Line
 @cindex mode-line construct
@@ -2813,151 +3024,8 @@
 and it should return the restored buffer.
 Here @var{desktop-buffer-misc} is the value returned by the function
 optionally bound to @code{desktop-save-buffer}.
-
 @end defvar

-@node Hooks
-@section Hooks
-@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
-hook name ends in @samp{-hook}, that tells you it is normal.  We try to
-make all hooks normal, as much as possible, so that you can use them in
-a uniform way.
-
-  Every major mode function is supposed to run a normal 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
-buffer-local variable assignments already made by the mode.  Most
-minor modes also run a mode hook at their end.  But hooks are used in
-other contexts too.  For example, the hook @code{suspend-hook} runs
-just before Emacs suspends itself (@pxref{Suspending Emacs}).
-
-  The recommended way to add a hook function to a normal hook is by
-calling @code{add-hook} (see below).  The hook functions may be any of
-the valid kinds of functions that @code{funcall} accepts (@pxref{What
-Is a Function}).  Most normal hook variables are initially void;
-@code{add-hook} knows how to deal with this.  You can add hooks either
-globally or buffer-locally with @code{add-hook}.
-
-@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
-some way.  You can use @code{add-hook} to add a function to the list,
-but you must take care in writing the function.  (A few of these
-variables, notably those ending in @samp{-hooks}, are actually
-normal hooks which were named before we established the convention of
-using @samp{-hook} for them.)
-
-  If the variable's name ends in @samp{-function}, then its value
-is just a single function, not a list of functions.
-
-  Here's an example 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)
-@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}.
-
-@defun run-hooks &rest hookvars
-This function takes one or more normal hook variable names as
-arguments, and runs each hook in turn.  Each argument should be a
-symbol that is a normal 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.  (The former option is considered
-obsolete.)  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
-that isn't a function, its elements are called, consecutively.  All
-the hook functions are called with no arguments.
-@end defun
-
-@defun run-hook-with-args hook &rest args
-This function is the way to run an abnormal hook and always call all
-of the hook functions.  It calls each of the hook functions one by
-one, passing each of them the arguments @var{args}.
-@end defun
-
-@defun run-hook-with-args-until-failure hook &rest args
-This function is the way to run an abnormal hook until one of the hook
-functions fails.  It calls each of the hook functions, passing each of
-them the arguments @var{args}, until some hook function returns
-@code{nil}.  It then stops and returns @code{nil}.  If none of the
-hook functions return @code{nil}, 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 until a hook function
-succeeds.  It calls each of the hook functions, passing each of them
-the arguments @var{args}, until some hook function returns
-non-@code{nil}.  Then it stops, and returns whatever was returned by
-the last hook function that was called.  If all hook functions return
-@code{nil}, it returns @code{nil} as well.
-@end defun
-
-@defun add-hook hook function &optional append local
-This function is the handy way to add function @var{function} to hook
-variable @var{hook}.  You can use it for abnormal hooks as well as for
-normal hooks.  @var{function} can be any Lisp function that can accept
-the proper number of arguments for @var{hook}.  For example,
-
-@example
-(add-hook 'text-mode-hook 'my-text-hook-function)
-@end example
-
-@noindent
-adds @code{my-text-hook-function} to the hook called @code{text-mode-hook}.
-
-If @var{function} is already present in @var{hook} (comparing using
-@code{equal}), then @code{add-hook} does not add it a second time.
-
-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,
-@var{function} goes at the front of the hook list, so it will be
-executed first (barring another @code{add-hook} call).  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.
-
-@code{add-hook} can handle the cases where @var{hook} is void or its
-value is a single function; it sets or changes the value to a list of
-functions.
-
-If @var{local} is non-@code{nil}, that says to add @var{function} to
-the buffer-local hook list instead of to the global hook list.  If
-needed, this makes the hook buffer-local and adds @code{t} to the
-buffer-local value.  The latter acts as a flag to run the hook
-functions in the default value as well as in the local value.
-@end defun
-
-@defun remove-hook hook function &optional local
-This function removes @var{function} from the hook variable
-@var{hook}.  It compares @var{function} with elements of @var{hook}
-using @code{equal}, so it works for both symbols and lambda
-expressions.
-
-If @var{local} is non-@code{nil}, that says to remove @var{function}
-from the buffer-local hook list instead of from the global hook list.
-@end defun
-
 @ignore
    arch-tag: 4c7bff41-36e6-4da6-9e7f-9b9289e27c8e
 @end ignore