[Emacs-diffs] Changes to emacs/lispref/modes.texi

[Luc Teirlinck]

Index: emacs/lispref/modes.texi
diff -c emacs/lispref/modes.texi:1.102 emacs/lispref/modes.texi:1.103
*** emacs/lispref/modes.texi:1.102      Sat May 14 15:25:38 2005
--- emacs/lispref/modes.texi    Sat May 14 16:15:15 2005
***************
*** 20,25 ****
--- 20,26 ----
  @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,40 ****
  * 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 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
--- 29,181 ----
  * Font Lock Mode::     How modes can highlight text according to syntax.
  * Desktop Save Mode::  How modes can have buffer state saved between
                           Emacs sessions.
  @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 address@hidden 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 address@hidden 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
+ address@hidden  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 address@hidden, 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 address@hidden, 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 address@hidden, 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
  
    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,49 ****
--- 185,207 ----
  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,112 ****
  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
  
--- 253,258 ----
***************
*** 240,246 ****
  in a variable named @address@hidden  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}.
  
  @item
  The mode should specify how to do highlighting for Font Lock mode, by
--- 386,392 ----
  in a variable named @address@hidden  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{Defining Abbrevs}.
  
  @item
  The mode should specify how to do highlighting for Font Lock mode, by
***************
*** 326,333 ****
  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}.
  
  @item
  In the comments that document the file, you should provide a sample
--- 472,482 ----
  recognizable names, add an element to @code{auto-mode-alist} to select
  the mode for those file names.  If you define the mode command to
  autoload, you should add this element in the same file that calls
! @code{autoload}.  If you use an autoload cookie for the mode command,
! you can also use an autoload cookie for the form that adds the element
! (@pxref{autoload cookie}).  If you do not autoload the mode command,
! it is sufficient to add the element in the file that contains the mode
! definition.  @xref{Auto Major Mode}.
  
  @item
  In the comments that document the file, you should provide a sample
***************
*** 635,655 ****
  
  @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.
  
  If the @var{find-file} argument to @code{normal-mode} is address@hidden,
  @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
  @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.
  
  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.
  
  @cindex file mode specification error
  @code{normal-mode} uses @code{condition-case} around the call to the
--- 784,811 ----
  
  @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}
! (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 address@hidden,
  @code{normal-mode} assumes that the @code{find-file} function is calling
! 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.
  
  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 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,672 ****
  mode specification error},  followed by the original error message.
  @end deffn
  
! @defun set-auto-mode
  @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 @address@hidden
! line, on the visited file name (using @code{auto-mode-alist}), on the
! @address@hidden 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}.
  @end defun
  
  @defopt default-major-mode
--- 813,837 ----
  mode specification error},  followed by the original error message.
  @end deffn
  
! @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 bases its decision (in order of precedence) on
! the @address@hidden line, on the @address@hidden 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 @address@hidden line for a mode tag either.
! 
! If @var{keep-mode-if-same} is address@hidden, 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,681 ****
  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}
  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
--- 839,846 ----
  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 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,711 ****
  
  @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
  @samp{*scratch*} buffer.  The value should be a symbol that is a major
  mode command.  The default value is @code{lisp-interaction-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})}.
  
  For example,
  
--- 849,898 ----
  
  @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).  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
  
! @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 address@hidden; 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) 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,732 ****
  @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.
  
  If an element of @code{auto-mode-alist} has the form @code{(@var{regexp}
  @var{function} t)}, then after calling @var{function}, Emacs searches
--- 911,921 ----
  @end smallexample
  
  When you visit a file whose expanded file name (@pxref{File Name
! 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,773 ****
  @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
--- 944,949 ----
***************
*** 804,839 ****
    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 address@hidden
  This construct defines @var{variant} as a major mode command, using
! @var{name} as the string form of the mode name.
  
  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 @address@hidden
! @code{define-derived-mode} initializes this map to inherit from
! @address@hidden, if it is not already set.
  
  @item
  The new mode has its own syntax table, kept in the variable
! @address@hidden
! @code{define-derived-mode} initializes this variable by copying
! @address@hidden, if it is not already set.
  
  @item
  The new mode has its own abbrev table, kept in the variable
! @address@hidden
! @code{define-derived-mode} initializes this variable by copying
! @address@hidden, if it is not already set.
  
  @item
! The new mode has its own mode hook, @address@hidden,
! 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}.)
  @end itemize
  
  In addition, you can specify how to override other aspects of
--- 980,1017 ----
    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 address@hidden 
address@hidden
  This construct defines @var{variant} as a major mode command, using
! @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 sparse keymap, named
! @address@hidden  @code{define-derived-mode}
! makes the parent mode's keymap the parent of the new map, unless
! @address@hidden is already set and already has a parent.
  
  @item
  The new mode has its own syntax table, kept in the variable
! @address@hidden, 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
! @address@hidden, 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
! @address@hidden, unless you override this using the
! @code{:abbrev-table} keyword (see below).
  
  @item
! The new mode has its own mode hook, @address@hidden  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,849 ****
  evaluates the forms in @var{body} after setting up all its usual
  overrides, just before running @address@hidden
  
! 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.
  
  Here is a hypothetical example:
  
--- 1019,1056 ----
  evaluates the forms in @var{body} after setting up all its usual
  overrides, just before running @address@hidden
  
! 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,1300 ****
--- 1502,1520 ----
  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,1350 ****
  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
--- 1556,1561 ----
***************
*** 2813,2963 ****
  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 address@hidden 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 address@hidden 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
- address@hidden  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 address@hidden, 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 address@hidden, 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 address@hidden, 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
--- 3024,3031 ----