xemacs-beta: man/lispref/modes.texi comparison

comparison man/lispref/modes.texi @ 0:376386a54a3c r19-14

Import from CVS: tag r19-14

author	cvs
date	Mon, 13 Aug 2007 08:45:50 +0200
parents
children	558f606b08ae

comparison

equal deleted inserted replaced

--1:000000000000
+:376386a54a3c
+@c -*-texinfo-*-
+@c This is part of the XEmacs Lisp Reference Manual.
+@c Copyright (C) 1990, 1991, 1992, 1993, 1994 Free Software Foundation, Inc.
+@c See the file lispref.texi for copying conditions.
+@setfilename ../../info/modes.info
+@node Modes, Documentation, Scrollbars, Top
+@chapter Major and Minor Modes
+@cindex mode
+A @dfn{mode} is a set of definitions that customize XEmacs and can be
+turned on and off while you edit.  There are two varieties of modes:
+@dfn{major modes}, which are mutually exclusive and used for editing
+particular kinds of text, and @dfn{minor modes}, which provide features
+that users can enable individually.
+This chapter describes how to write both major and minor modes, how to
+indicate them in the modeline, and how they run hooks supplied by the
+user.  For related topics such as keymaps and syntax tables, see
+@ref{Keymaps}, and @ref{Syntax Tables}.
+@menu
+* Major Modes::        Defining major modes.
+* Minor Modes::        Defining minor modes.
+* Modeline Format::    Customizing the text that appears in the modeline.
+* 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 XEmacs for editing particular kinds of text.
+Each buffer has only one major mode at a time.
+The least specialized major mode is called @dfn{Fundamental mode}.
+This mode has no mode-specific definitions or variable settings, so each
+XEmacs command behaves in its default manner, and each option is in its
+default state.  All other major modes redefine various keys and options.
+For example, Lisp Interaction mode provides special key bindings for
+@key{LFD} (@code{eval-print-last-sexp}), @key{TAB}
+(@code{lisp-indent-line}), and other keys.
+When you need to write several editing commands to help you perform a
+specialized editing task, creating a new major mode is usually a good
+idea.  In practice, writing a major mode is easy (in contrast to
+writing a minor mode, which is often difficult).
+If the new mode is similar to an old one, it is often unwise to modify
+the old one to serve two purposes, since it may become harder to use and
+maintain.  Instead, copy and rename an existing major mode definition
+and alter the copy---or define a @dfn{derived mode} (@pxref{Derived
+Modes}).  For example, Rmail Edit mode, which is in
+@file{emacs/lisp/rmailedit.el}, is a major mode that is very similar to
+Text mode except that it provides three additional commands.  Its
+definition is distinct from that of Text mode, but was derived from it.
+Rmail Edit mode is an example of a case where one piece of text is put
+temporarily into a different major mode so it can be edited in a
+different way (with ordinary XEmacs commands rather than Rmail).  In such
+cases, the temporary major mode usually has a command to switch back to
+the buffer's usual mode (Rmail mode, in this case).  You might be
+tempted to present the temporary redefinitions inside a recursive edit
+and restore the usual ones when the user exits; but this is a bad idea
+because it constrains the user's options when it is done in more than
+one buffer: recursive edits must be exited most-recently-entered first.
+Using alternative major modes avoids this limitation.  @xref{Recursive
+Editing}.
+The standard XEmacs Lisp library directory contains the code for
+several major modes, in files including @file{text-mode.el},
+@file{texinfo.el}, @file{lisp-mode.el}, @file{c-mode.el}, and
+@file{rmail.el}.  You can look at these libraries to see how modes are
+written.  Text mode is perhaps the simplest major mode aside from
+Fundamental mode.  Rmail mode is a complicated and specialized mode.
+@menu
+* Major Mode Conventions::  Coding conventions for keymaps, etc.
+* Example Major Modes::     Text mode and Lisp modes.
+* Auto Major Mode::         How XEmacs 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.
+@end menu
+@node Major Mode Conventions
+@subsection Major Mode Conventions
+The code for existing major modes follows various coding conventions,
+including conventions for local keymap and syntax table initialization,
+global names, and hooks.  Please follow these conventions when you
+define a new major mode:
+@itemize @bullet
+@item
+Define a command whose name ends in @samp{-mode}, with no arguments,
+that switches to the new mode in the current buffer.  This command
+should set up the keymap, syntax table, and local variables in an
+existing buffer without changing the buffer's text.
+@item
+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.
+The documentation string may include the special documentation
+substrings, @samp{\[@var{command}]}, @samp{\@{@var{keymap}@}}, and
+@samp{\<@var{keymap}>}, that enable the documentation to adapt
+automatically to the user's own key bindings.  @xref{Keys in
+Documentation}.
+@item
+The major mode command should start by calling
+@code{kill-all-local-variables}.  This is what gets rid of the local
+variables of the major mode previously in effect.
+@item
+The major mode command should set the variable @code{major-mode} to the
+major mode command symbol.  This is how @code{describe-mode} discovers
+which documentation to print.
+@item
+The major mode command should set the variable @code{mode-name} to the
+``pretty'' name of the mode, as a string.  This appears in the mode
+line.
+@item
+@cindex functions in modes
+Since all global names are in the same name space, all the global
+variables, constants, and functions that are part of the mode should
+have names that start with the major mode name (or with an abbreviation
+of it if the name is long).  @xref{Style Tips}.
+@item
+@cindex keymaps in modes
+The major mode should usually have its own keymap, which is used as the
+local keymap in all buffers in that mode.  The major mode function
+should call @code{use-local-map} to install this local map.
+@xref{Active Keymaps}, for more information.
+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.
+@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}.  @xref{Syntax
+Tables}.
+@item
+@cindex abbrev tables in modes
+The mode may have its own abbrev table or may share one with other
+related modes.  If it has its own abbrev table, it should store this in
+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
+@code{make-local-variable} in the major mode command, not
+@code{make-variable-buffer-local}.  The latter function would make the
+variable local to every buffer in which it is subsequently set, which
+would affect buffers that do not use this mode.  It is undesirable for a
+mode to have such global effects.  @xref{Buffer-Local Variables}.
+It's ok to use @code{make-variable-buffer-local}, if you wish, for a
+variable used only within a single Lisp package.
+@item
+@cindex mode hook
+@cindex major mode hook
+Each major mode should have a @dfn{mode hook} named
+@code{@var{modename}-mode-hook}.  The major mode command should run that
+hook, with @code{run-hooks}, as the very last thing it
+does. @xref{Hooks}.
+@item
+The major mode command may also run the hooks of some more basic modes.
+For example, @code{indented-text-mode} runs @code{text-mode-hook} as
+well as @code{indented-text-mode-hook}.  It may run these other hooks
+immediately before the mode's own hook (that is, after everything else),
+or it may run them earlier.
+@item
+If something special should be done if the user switches a buffer from
+this mode to any other major mode, the mode can set a local value for
+@code{change-major-mode-hook}.
+@item
+If this mode is appropriate only for specially-prepared text, then the
+major mode command symbol should have a property named @code{mode-class}
+with value @code{special}, put on as follows:
+@cindex @code{mode-class} property
+@cindex @code{special}
+@example
+(put 'funny-mode 'mode-class 'special)
+@end example
+@noindent
+This tells XEmacs that new buffers created while the current buffer has
+Funny mode should not inherit Funny mode.  Modes such as Dired, Rmail,
+and Buffer List use this feature.
+@item
+If you want to make the new mode the default for files with certain
+recognizable names, add an element to @code{auto-mode-alist} to select
+the mode for those file names.  If you define the mode command to
+autoload, you should add this element in the same file that calls
+@code{autoload}.  Otherwise, it is sufficient to add the element in the
+file that contains the mode definition.  @xref{Auto Major Mode}.
+@item
+@cindex @file{.emacs} customization
+In the documentation, you should provide a sample @code{autoload} form
+and an example of how to add to @code{auto-mode-alist}, that users can
+include in their @file{.emacs} files.
+@item
+@cindex mode loading
+The top-level forms in the file defining the mode should be written so
+that they may be evaluated more than once without adverse consequences.
+Even if you never load the file more than once, someone else will.
+@end itemize
+@defvar change-major-mode-hook
+This normal hook is run by @code{kill-all-local-variables} before it
+does anything else.  This gives major modes a way to arrange for
+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.  @xref{Hooks}.
+@end defvar
+@node Example Major Modes
+@subsection Major Mode Examples
+Text mode is perhaps the simplest mode besides Fundamental mode.
+Here are excerpts from  @file{text-mode.el} that illustrate many of
+the conventions listed above:
+@smallexample
+@group
+;; @r{Create mode-specific tables.}
+(defvar text-mode-syntax-table nil
+"Syntax table used while in text mode.")
+@end group
+@group
+(if text-mode-syntax-table
+()              ; @r{Do not change the table if it is already set up.}
+(setq text-mode-syntax-table (make-syntax-table))
+(modify-syntax-entry ?\" ".   " text-mode-syntax-table)
+(modify-syntax-entry ?\\ ".   " text-mode-syntax-table)
+(modify-syntax-entry ?' "w   " text-mode-syntax-table))
+@end group
+@group
+(defvar text-mode-abbrev-table nil
+"Abbrev table used while in text mode.")
+(define-abbrev-table 'text-mode-abbrev-table ())
+@end group
+@group
+(defvar text-mode-map nil)   ; @r{Create a mode-specific keymap.}
+(if text-mode-map
+()              ; @r{Do not change the keymap if it is already set up.}
+(setq text-mode-map (make-sparse-keymap))
+(define-key text-mode-map "\t" 'tab-to-tab-stop)
+(define-key text-mode-map "\es" 'center-line)
+(define-key text-mode-map "\eS" 'center-paragraph))
+@end group
+@end smallexample
+Here is the complete major mode function definition for Text mode:
+@smallexample
+@group
+(defun text-mode ()
+"Major mode for editing text intended for humans to read.
+Special commands: \\@{text-mode-map@}
+@end group
+@group
+Turning on text-mode runs the hook `text-mode-hook'."
+(interactive)
+(kill-all-local-variables)
+@end group
+@group
+(use-local-map text-mode-map)     ; @r{This provides the local keymap.}
+(setq mode-name "Text")           ; @r{This name goes into the modeline.}
+(setq major-mode 'text-mode)      ; @r{This is how @code{describe-mode}}
+;   @r{finds the doc string to print.}
+(setq local-abbrev-table text-mode-abbrev-table)
+(set-syntax-table text-mode-syntax-table)
+(run-hooks 'text-mode-hook))      ; @r{Finally, this permits the user to}
+;   @r{customize the mode with a hook.}
+@end group
+@end smallexample
+@cindex @file{lisp-mode.el}
+The three Lisp modes (Lisp mode, Emacs Lisp mode, and Lisp
+Interaction mode) have more features than Text mode and the code is
+correspondingly more complicated.  Here are excerpts from
+@file{lisp-mode.el} that illustrate how these modes are written.
+@cindex syntax table example
+@smallexample
+@group
+;; @r{Create mode-specific table variables.}
+(defvar lisp-mode-syntax-table nil "")
+(defvar emacs-lisp-mode-syntax-table nil "")
+(defvar lisp-mode-abbrev-table nil "")
+@end group
+@group
+(if (not emacs-lisp-mode-syntax-table) ; @r{Do not change the table}
+;   @r{if it is already set.}
+(let ((i 0))
+(setq emacs-lisp-mode-syntax-table (make-syntax-table))
+@end group
+@group
+;; @r{Set syntax of chars up to 0 to class of chars that are}
+;;   @r{part of symbol names but not words.}
+;;   @r{(The number 0 is @code{48} in the @sc{ASCII} character set.)}
+(while (< i ?0)
+(modify-syntax-entry i "_   " emacs-lisp-mode-syntax-table)
+(setq i (1+ i)))
+@dots{}
+@end group
+@group
+;; @r{Set the syntax for other characters.}
+(modify-syntax-entry ?  "    " emacs-lisp-mode-syntax-table)
+(modify-syntax-entry ?\t "    " emacs-lisp-mode-syntax-table)
+@dots{}
+@end group
+@group
+(modify-syntax-entry ?\( "()  " emacs-lisp-mode-syntax-table)
+(modify-syntax-entry ?\) ")(  " emacs-lisp-mode-syntax-table)
+@dots{}))
+;; @r{Create an abbrev table for lisp-mode.}
+(define-abbrev-table 'lisp-mode-abbrev-table ())
+@end group
+@end smallexample
+Much code is shared among the three Lisp modes.  The following
+function sets various variables; it is called by each of the major Lisp
+mode functions:
+@smallexample
+@group
+(defun lisp-mode-variables (lisp-syntax)
+;; @r{The @code{lisp-syntax} argument is @code{nil} in Emacs Lisp mode,}
+;;   @r{and @code{t} in the other two Lisp modes.}
+(cond (lisp-syntax
+(if (not lisp-mode-syntax-table)
+;; @r{The Emacs Lisp mode syntax table always exists, but}
+;;   @r{the Lisp Mode syntax table is created the first time a}
+;;   @r{mode that needs it is called.  This is to save space.}
+@end group
+@group
+(progn (setq lisp-mode-syntax-table
+(copy-syntax-table emacs-lisp-mode-syntax-table))
+;; @r{Change some entries for Lisp mode.}
+(modify-syntax-entry ?\| "\"   "
+lisp-mode-syntax-table)
+(modify-syntax-entry ?\[ "_   "
+lisp-mode-syntax-table)
+(modify-syntax-entry ?\] "_   "
+lisp-mode-syntax-table)))
+@end group
+@group
+(set-syntax-table lisp-mode-syntax-table)))
+(setq local-abbrev-table lisp-mode-abbrev-table)
+@dots{})
+@end group
+@end smallexample
+Functions such as @code{forward-paragraph} use the value of the
+@code{paragraph-start} variable.  Since Lisp code is different from
+ordinary text, the @code{paragraph-start} variable needs to be set
+specially to handle Lisp.  Also, comments are indented in a special
+fashion in Lisp and the Lisp modes need their own mode-specific
+@code{comment-indent-function}.  The code to set these variables is the
+rest of @code{lisp-mode-variables}.
+@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
+@group
+(make-local-variable 'comment-indent-function)
+(setq comment-indent-function 'lisp-comment-indent))
+@end group
+@end smallexample
+Each of the different Lisp modes has a slightly different keymap.  For
+example, Lisp mode binds @kbd{C-c C-l} to @code{run-lisp}, but the other
+Lisp modes do not.  However, all Lisp modes have some commands in
+common.  The following function adds these common commands to a given
+keymap.
+@smallexample
+@group
+(defun lisp-mode-commands (map)
+(define-key map "\e\C-q" 'indent-sexp)
+(define-key map "\177" 'backward-delete-char-untabify)
+(define-key map "\t" 'lisp-indent-line))
+@end group
+@end smallexample
+Here is an example of using @code{lisp-mode-commands} to initialize a
+keymap, as part of the code for Emacs Lisp mode.  First we declare a
+variable with @code{defvar} to hold the mode-specific keymap.  When this
+@code{defvar} executes, it sets the variable to @code{nil} if it was
+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.
+@smallexample
+@group
+(defvar emacs-lisp-mode-map () "")
+(if emacs-lisp-mode-map
+()
+(setq emacs-lisp-mode-map (make-sparse-keymap))
+(define-key emacs-lisp-mode-map "\e\C-x" 'eval-defun)
+(lisp-mode-commands emacs-lisp-mode-map))
+@end group
+@end smallexample
+Finally, here is the complete major mode function definition for
+Emacs Lisp mode.
+@smallexample
+@group
+(defun emacs-lisp-mode ()
+"Major mode for editing Lisp code to run in XEmacs.
+Commands:
+Delete converts tabs to spaces as it moves back.
+Blank lines separate paragraphs.  Semicolons start comments.
+\\@{emacs-lisp-mode-map@}
+@end group
+@group
+Entry to this mode runs the hook `emacs-lisp-mode-hook'."
+(interactive)
+(kill-all-local-variables)
+(use-local-map emacs-lisp-mode-map)    ; @r{This provides the local keymap.}
+(set-syntax-table emacs-lisp-mode-syntax-table)
+@end group
+@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 modeline.}
+(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 smallexample
+@node Auto Major Mode
+@subsection How XEmacs Chooses a Major Mode
+Based on information in the file name or in the file itself, XEmacs
+automatically selects a major mode for the new buffer when a file is
+visited.
+@deffn Command fundamental-mode
+Fundamental mode is a major mode that is not specialized for anything
+in particular.  Other major modes are defined in effect by comparison
+with this one---their definitions say what to change, starting from
+Fundamental mode.  The @code{fundamental-mode} function does @emph{not}
+run any hooks; you're not supposed to customize it.  (If you want Emacs
+to behave differently in Fundamental mode, change the @emph{global}
+state of Emacs.)
+@end deffn
+@deffn Command normal-mode &optional find-file
+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
+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
+@code{enable-local-variables} controls whether to do so.
+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 XEmacs
+Reference 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
+major mode function, so errors are caught and reported as a @samp{File
+mode specification error},  followed by the original error message.
+@end deffn
+@defopt enable-local-variables
+This variable controls processing of local variables lists in files
+being visited.  A value of @code{t} means process the local variables
+lists unconditionally; @code{nil} means ignore them; anything else means
+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
+unconditionally; @code{nil} means ignore them; anything else means ask
+the user what to do for each file.  The default value is @code{maybe}.
+@end defopt
+@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 @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
+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 XEmacs Reference Manual}.
+@end defun
+@defopt default-major-mode
+This variable holds the default major mode for new buffers.  The
+standard value is @code{fundamental-mode}.
+If the value of @code{default-major-mode} is @code{nil}, XEmacs uses
+the (previously) current buffer's major mode for the major mode of a new
+buffer.  However, if the 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
+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
+@samp{*scratch*} buffer.  The value should be a symbol that is a major
+mode command name.  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 functions.  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,
+@smallexample
+@group
+(("^/tmp/fol/" . text-mode)
+("\\.texinfo\\'" . texinfo-mode)
+("\\.texi\\'" . texinfo-mode)
+@end group
+@group
+("\\.el\\'" . emacs-lisp-mode)
+("\\.c\\'" . c-mode)
+("\\.h\\'" . c-mode)
+@dots{})
+@end group
+@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 XEmacs 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}, XEmacs searches
+@code{auto-mode-alist} again for a match against the portion of the file
+name that did not match before.
+This match-again feature is useful for uncompression packages: an entry
+of the form @code{("\\.gz\\'" . @var{function})} can uncompress the file
+and then put the uncompressed file in the proper mode according to the
+name sans @samp{.gz}.
+Here is an example of how to prepend several pattern pairs to
+@code{auto-mode-alist}.  (You might use this sort of expression in your
+@file{.emacs} file.)
+@smallexample
+@group
+(setq auto-mode-alist
+(append
+;; @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
+@end defvar
+@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
+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 @code{auto-mode-alist} does
+not indicate which major mode to use.
+@end defvar
+@defun hack-local-variables &optional force
+This function parses, and binds or evaluates as appropriate, any local
+variables for the current buffer.
+The handling of @code{enable-local-variables} documented for
+@code{normal-mode} actually takes place here.  The argument @var{force}
+usually comes from the argument @var{find-file} given to
+@code{normal-mode}.
+@end defun
+@node Mode Help
+@subsection Getting Help about a Major Mode
+@cindex mode help
+@cindex help for major mode
+@cindex documentation for major mode
+The @code{describe-mode} function is used to provide information
+about major modes.  It is normally called with @kbd{C-h m}.  The
+@code{describe-mode} function uses the value of @code{major-mode},
+which is why every major mode function needs to set the
+@code{major-mode} variable.
+@deffn Command describe-mode
+This function displays the documentation of the current major mode.
+The @code{describe-mode} function calls the @code{documentation}
+function using the value of @code{major-mode} as an argument.  Thus, it
+displays the documentation string of the major mode function.
+(@xref{Accessing Documentation}.)
+@end deffn
+@defvar major-mode
+This variable holds the symbol for the current buffer's major mode.
+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 the function as the documentation of the major
+mode.
+@end defvar
+@node Derived Modes
+@subsection Defining Derived Modes
+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{}
+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 @code{@var{variant}-map}.
+@code{define-derived-mode} initializes this map to inherit from
+@code{@var{parent}-map}, if it is not already set.
+@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.
+@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.
+@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}.)
+@end itemize
+In addition, you can specify how to override other aspects of
+@var{parent} with @var{body}.  The command @var{variant}
+evaluates the forms in @var{body} after setting up all its usual
+overrides, just before running @code{@var{variant}-hook}.
+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:
+@example
+(define-derived-mode hypertext-mode
+text-mode "Hypertext"
+"Major mode for hypertext.
+\\@{hypertext-mode-map@}"
+(setq case-fold-search nil))
+(define-key hypertext-mode-map
+[down-mouse-3] 'do-hyper-link)
+@end example
+@end defmac
+@node Minor Modes
+@section Minor Modes
+@cindex minor mode
+A @dfn{minor mode} provides features that users may enable or disable
+independently of the choice of major mode.  Minor modes can be enabled
+individually or in combination.  Minor modes would be better named
+``Generally available, optional feature modes'' except that such a name is
+unwieldy.
+A minor mode is not usually a modification of single major mode.  For
+example, Auto Fill mode may be used in any major mode that permits text
+insertion.  To be general, a minor mode must be effectively independent
+of the things major modes do.
+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.  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 XEmacs.  Minor mode
+keymaps make this easier than it used to be.
+@menu
+* Minor Mode Conventions::      Tips for writing a minor mode.
+* Keymaps and Minor Modes::     How a minor mode can have its own keymap.
+@end menu
+@node Minor Mode Conventions
+@subsection Conventions for Writing Minor Modes
+@cindex minor mode conventions
+@cindex conventions for writing minor modes
+There are conventions for writing minor modes just as there are for
+major modes.  Several of the major mode conventions apply to minor
+modes as well: those regarding the name of the mode initialization
+function, the names of global symbols, and the use of keymaps and
+other tables.
+In addition, there are several conventions that are specific to
+minor modes.
+@itemize @bullet
+@item
+@cindex mode variable
+Make a variable whose name ends in @samp{-mode} to represent the minor
+mode.  Its value should enable or disable the mode (@code{nil} to
+disable; anything else to enable.)  We call this the @dfn{mode
+variable}.
+This variable is used in conjunction with the @code{minor-mode-alist} to
+display the minor mode name in the modeline.  It can also enable
+or disable a minor mode keymap.  Individual commands or hooks can also
+check the variable's value.
+If you want the minor mode to be enabled separately in each buffer,
+make the variable buffer-local.
+@item
+Define a command whose name is the same as the mode variable.
+Its job is to enable and disable the mode by setting the variable.
+The command should accept one optional argument.  If the argument is
+@code{nil}, it should toggle the mode (turn it on if it is off, and off
+if it is on).  Otherwise, it should turn the mode on if the argument is
+a positive integer, a symbol other than @code{nil} or @code{-}, or a
+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{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 transient-mark-mode
+(if (null arg) (not transient-mark-mode)
+(> (prefix-numeric-value arg) 0)))
+@end group
+@end smallexample
+@item
+Add an element to @code{minor-mode-alist} for each minor mode
+(@pxref{Modeline Variables}).  This element should be a list of the
+following form:
+@smallexample
+(@var{mode-variable} @var{string})
+@end smallexample
+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 modeline.  These strings must be short so
+that there is room for several of them at once.
+When you add an element to @code{minor-mode-alist}, use @code{assq} to
+check for an existing element, to avoid duplication.  For example:
+@smallexample
+@group
+(or (assq 'leif-mode minor-mode-alist)
+(setq minor-mode-alist
+(cons '(leif-mode " Leif") minor-mode-alist)))
+@end group
+@end smallexample
+@end itemize
+@node Keymaps and Minor Modes
+@subsection Keymaps and Minor Modes
+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
+self-inserting characters so that they do something else as well as
+self-insert.  In general, this is the only way to do that, since the
+facilities for customizing @code{self-insert-command} are limited to
+special cases (designed for abbrevs and Auto Fill mode).  (Do not try
+substituting your own definition of @code{self-insert-command} for the
+standard one.  The editor command loop handles this function specially.)
+@node Modeline Format
+@section Modeline Format
+@cindex modeline
+Each Emacs window (aside from minibuffer windows) includes a modeline,
+which displays status information about the buffer displayed in the
+window.  The modeline contains information about the buffer, such as its
+name, associated file, depth of recursive editing, and the major and
+minor modes.
+This section describes how the contents of the modeline are
+controlled.  It is in the chapter on modes because much of the
+information displayed in the modeline relates to the enabled major and
+minor modes.
+@code{modeline-format} is a buffer-local variable that holds a
+template used to display the modeline of the current buffer.  All
+windows for the same buffer use the same @code{modeline-format} and
+their modelines appear the same (except for scrolling percentages and
+line numbers).
+The modeline 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{modeline-format} (@pxref{Modeline
+Variables}), you may want to force an update of the modeline so as to
+display the new information.
+@c Emacs 19 feature
+@defun redraw-modeline &optional all
+Force redisplay of the current buffer's modeline.  If @var{all} is
+non-@code{nil}, then force redisplay of all modelines.
+@end defun
+The modeline is usually displayed in inverse video.  This
+is controlled using the @code{modeline} face.  @xref{Faces}.
+@menu
+* Modeline Data::         The data structure that controls the modeline.
+* Modeline Variables::    Variables used in that data structure.
+* %-Constructs::          Putting information into a modeline.
+@end menu
+@node Modeline Data
+@subsection The Data Structure of the Modeline
+@cindex modeline construct
+The modeline contents are controlled by a data structure of lists,
+strings, symbols, and numbers kept in the buffer-local variable
+@code{mode-line-format}.  The data structure is called a @dfn{modeline
+construct}, and it is built in recursive fashion out of simpler modeline
+constructs.  The same data structure is used for constructing
+frame titles (@pxref{Frame Titles}).
+@defvar modeline-format
+The value of this variable is a modeline construct with overall
+responsibility for the modeline format.  The value of this variable
+controls which other variables are used to form the modeline text, and
+where they appear.
+@end defvar
+A modeline construct may be as simple as a fixed string of text, but
+it usually specifies how to use other variables to construct the text.
+Many of these variables are themselves defined to have modeline
+constructs as their values.
+The default value of @code{modeline-format} incorporates the values
+of variables such as @code{mode-name} and @code{minor-mode-alist}.
+Because of this, very few modes need to alter @code{modeline-format}.
+For most purposes, it is sufficient to alter the variables referenced by
+@code{modeline-format}.
+A modeline 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 modeline
+@item @var{string}
+A string as a modeline construct is displayed verbatim in the mode line
+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 modeline construct stands for its value.  The value of
+@var{symbol} is used as a modeline 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
+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 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, @var{then}, is processed recursively as a modeline
+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
+padding of the results of @var{rest}.  The remaining elements
+@var{rest} are processed recursively as modeline constructs and
+concatenated together.  Then the result is space filled (if
+@var{width} is positive) or truncated (to @minus{}@var{width} columns,
+if @var{width} is negative) on the right.
+For example, the usual way to show what percentage of a buffer is above
+the top of the window is to use a list like this: @code{(-3 "%p")}.
+@end table
+If you do alter @code{modeline-format} itself, the new value should
+use the same variables that appear in the default value (@pxref{Modeline
+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{modeline-format}
+Here is an example of a @code{modeline-format} that might be
+useful for @code{shell-mode}, since it contains the hostname and default
+directory.
+@example
+@group
+(setq modeline-format
+(list ""
+'modeline-modified
+"%b--"
+@end group
+(getenv "HOST")      ; @r{One element is not constant.}
+":"
+'default-directory
+"   "
+'global-mode-string
+"   %[("
+'mode-name
+'modeline-process
+'minor-mode-alist
+"%n"
+")%]----"
+@group
+'(line-number-mode "L%l--")
+'(-3 . "%p")
+"-%-"))
+@end group
+@end example
+@node Modeline Variables
+@subsection Variables Used in the Modeline
+This section describes variables incorporated by the
+standard value of @code{modeline-format} into the text of the mode
+line.  There is nothing inherently special about these variables; any
+other variables could have the same effects on the modeline if
+@code{modeline-format} were changed to use them.
+@defvar modeline-modified
+This variable holds the value of the modeline construct that displays
+whether the current buffer is modified.
+The default value of @code{modeline-modified} is @code{("--%1*%1+-")}.
+This means that the modeline 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 modeline.
+@end defvar
+@defvar modeline-buffer-identification
+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'' XEmacs.
+@end defvar
+@defvar global-mode-string
+This variable holds a modeline spec that appears in the mode line by
+default, just after the buffer name.  The command @code{display-time}
+sets @code{global-mode-string} to refer to the variable
+@code{display-time-string}, which holds a string containing the time and
+load information.
+The @samp{%M} construct substitutes the value of
+@code{global-mode-string}, but this is obsolete, since the variable is
+included directly in the modeline.
+@end defvar
+@defvar mode-name
+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 modeline.
+@end defvar
+@defvar minor-mode-alist
+This variable holds an association list whose elements specify how the
+modeline should indicate that a minor mode is active.  Each element of
+the @code{minor-mode-alist} should be a two-element list:
+@example
+(@var{minor-mode-variable} @var{modeline-string})
+@end example
+More generally, @var{modeline-string} can be any mode line spec.  It
+appears in the mode line when the value of @var{minor-mode-variable} is
+non-@code{nil}, and not otherwise.  These strings should begin with
+spaces so that they don't run together.  Conventionally, the
+@var{minor-mode-variable} for a specific mode is set to a non-@code{nil}
+value when that minor mode is activated.
+The default value of @code{minor-mode-alist} is:
+@example
+@group
+minor-mode-alist
+@result{} ((vc-mode vc-mode)
+(abbrev-mode " Abbrev")
+(overwrite-mode overwrite-mode)
+(auto-fill-function " Fill")
+(defining-kbd-macro " Def")
+(isearch-mode isearch-mode))
+@end group
+@end example
+@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
+@defvar modeline-process
+This buffer-local variable contains the modeline information on process
+status in modes used for communicating with subprocesses.  It is
+displayed immediately following the major mode name, with no intervening
+space.  For example, its value in the @samp{*shell*} buffer is
+@code{(":@: %s")}, which allows the shell to display its status along
+with the major mode as: @samp{(Shell:@: run)}.  Normally this variable
+is @code{nil}.
+@end defvar
+@defvar default-modeline-format
+This variable holds the default @code{modeline-format} for buffers
+that do not override it.  This is the same as @code{(default-value
+'modeline-format)}.
+The default value of @code{default-modeline-format} is:
+@example
+@group
+(""
+modeline-modified
+modeline-buffer-identification
+"   "
+global-mode-string
+"   %[("
+mode-name
+@end group
+@group
+modeline-process
+minor-mode-alist
+"%n"
+")%]----"
+(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 ModeLine
+The following table lists the recognized @code{%}-constructs and what
+they mean.  In any construct except @samp{%%}, you can add a decimal
+integer after the @samp{%} to specify how many characters to display.
+@table @code
+@item %b
+The current buffer name, obtained with the @code{buffer-name} function.
+@xref{Buffer Names}.
+@item %f
+The visited file name, obtained with the @code{buffer-file-name}
+function.  @xref{Buffer File Name}.
+@item %F
+The 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 (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}.
+@c The following two may only apply in XEmacs.
+@item %l
+the current line number.
+@item %S
+the name of the selected frame; this is only meaningful under the
+X Window System.  @xref{Frame Name}.
+@item %t
+Whether the visited file is a text file or a binary file.  (This is a
+meaningful distinction only on certain operating systems.)
+@item %p
+The percentage of the buffer text above the @strong{top} of window, or
+@samp{Top}, @samp{Bottom} or @samp{All}.
+@item %P
+The percentage of the buffer text that is above the @strong{bottom} of
+the window (which includes the text visible in the window, as well as
+the text above the top), plus @samp{Top} if the top of the buffer is
+visible on screen; or @samp{Bottom} or @samp{All}.
+@item %n
+@samp{Narrow} when narrowing is in effect; nothing otherwise (see
+@code{narrow-to-region} in @ref{Narrowing}).
+@item %[
+An indication of the depth of recursive editing levels (not counting
+minibuffer levels): one @samp{[} for each editing level.
+@xref{Recursive Editing}.
+@item %]
+One @samp{]} for each recursive editing level (not counting minibuffer
+levels).
+@item %%
+The character @samp{%}---this is how to include a literal @samp{%} in a
+string in which @code{%}-constructs are allowed.
+@item %-
+Dashes sufficient to fill the remainder of the modeline.
+@end table
+The following two @code{%}-constructs are still supported, but they are
+obsolete, since you can get the same results with the variables
+@code{mode-name} and @code{global-mode-string}.
+@table @code
+@item %m
+The value of @code{mode-name}.
+@item %M
+The value of @code{global-mode-string}.  Currently, only
+@code{display-time} modifies the value of @code{global-mode-string}.
+@end table
+@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.  XEmacs
+provides hooks for the sake of customization.  Most often, hooks are set
+up in the @file{.emacs} file, but Lisp programs can set them also.
+@xref{Standard Hooks}, for a list of standard hook variables.
+Most of the hooks in XEmacs are @dfn{normal hooks}.  These variables
+contain lists of functions to be called with no arguments.  The reason
+most hooks are normal hooks is so that you can use them in a uniform
+way.  You can usually tell when a hook is a normal hook, because its
+name ends in @samp{-hook}.
+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.
+As for abnormal hooks, those whose names end in @samp{-function} have
+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.
+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 XEmacs suspends itself (@pxref{Suspending XEmacs}).
+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)
+@end example
+The next example shows how to use a hook to customize the way XEmacs
+formats C code.  (People often have strong personal preferences for one
+format or another.)  Here the hook function is an anonymous lambda
+expression.
+@cindex lambda expression in hook
+@example
+@group
+(add-hook 'c-mode-hook
+(function (lambda ()
+(setq c-indent-level 4
+c-argdecl-indent 0
+c-label-offset -4
+@end group
+@group
+c-continued-statement-indent 0
+c-brace-offset 0
+comment-column 40))))
+(setq c++-mode-hook c-mode-hook)
+@end group
+@end example
+The final example shows how the appearance of the modeline can be
+modified for a particular class of buffers only.
+@example
+@group
+(add-hook 'text-mode-hook
+(function (lambda ()
+(setq modeline-format
+'(modeline-modified
+"Emacs: %14b"
+"  "
+@end group
+@group
+default-directory
+" "
+global-mode-string
+"%[("
+mode-name
+minor-mode-alist
+"%n"
+modeline-process
+") %]---"
+(-3 . "%p")
+"-%-")))))
+@end group
+@end example
+At the appropriate time, XEmacs uses the @code{run-hooks} function to
+run particular hooks.  This function calls the hook functions you have
+added with @code{add-hooks}.
+@defun run-hooks &rest hookvar
+This function takes one or more hook variable names as arguments, and
+runs each hook in turn.  Each @var{hookvar} argument should be a symbol
+that is a hook variable.  These arguments are processed in the order
+specified.
+If a hook variable has a non-@code{nil} value, that value may be a
+function or a list of functions.  If the value is a function (either a
+lambda expression or a symbol with a function definition), it is
+called.  If it is a list, the elements are called, in order.
+The hook functions are called with no arguments.
+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 local
+This function is the handy way to add function @var{function} to hook
+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)
+@end example
+@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,
+@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.
+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 &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

Mercurial > hg > xemacs-beta

comparison man/lispref/modes.texi @ 0:376386a54a3c r19-14