2 @c This is part of the SXEmacs Lisp Reference Manual.
3 @c Copyright (C) 1990, 1991, 1992, 1993, 1994 Free Software Foundation, Inc.
4 @c Copyright (C) 2005 Sebastian Freundt <hroptatyr@sxemacs.org>
5 @c See the file lispref.texi for copying conditions.
6 @setfilename ../../info/modes.info
8 @node Modes, Documentation, Drag and Drop, Top
9 @chapter Major and Minor Modes
12 A @dfn{mode} is a set of definitions that customize SXEmacs and can be
13 turned on and off while you edit. There are two varieties of modes:
14 @dfn{major modes}, which are mutually exclusive and used for editing
15 particular kinds of text, and @dfn{minor modes}, which provide features
16 that users can enable individually.
18 This chapter describes how to write both major and minor modes, how to
19 indicate them in the modeline, and how they run hooks supplied by the
20 user. For related topics such as keymaps and syntax tables, see
21 @ref{Keymaps}, and @ref{Syntax Tables}.
24 * Major Modes:: Defining major modes.
25 * Minor Modes:: Defining minor modes.
26 * Modeline Format:: Customizing the text that appears in the modeline.
27 * Hooks:: How to use hooks; how to write code that provides hooks.
34 @cindex Fundamental mode
36 Major modes specialize SXEmacs for editing particular kinds of text.
37 Each buffer has only one major mode at a time. For each major mode
38 there is a function to switch to that mode in the current buffer; its
39 name should end in @samp{-mode}. These functions work by setting
40 buffer-local variable bindings and other data associated with the
41 buffer, such as a local keymap. The effect lasts until you switch
42 to another major mode in the same buffer.
44 The least specialized major mode is called @dfn{Fundamental mode}.
45 This mode has no mode-specific definitions or variable settings, so each
46 SXEmacs command behaves in its default manner, and each option is in its
47 default state. All other major modes redefine various keys and options.
48 For example, Lisp Interaction mode provides special key bindings for
49 @key{LFD} (@code{eval-print-last-sexp}), @key{TAB}
50 (@code{lisp-indent-line}), and other keys.
52 When you need to write several editing commands to help you perform a
53 specialized editing task, creating a new major mode is usually a good
54 idea. In practice, writing a major mode is easy (in contrast to
55 writing a minor mode, which is often difficult).
57 If the new mode is similar to an old one, it is often unwise to modify
58 the old one to serve two purposes, since it may become harder to use and
59 maintain. Instead, copy and rename an existing major mode definition
60 and alter the copy---or define a @dfn{derived mode} (@pxref{Derived
62 @ignore @c does not exist here
63 For example, Rmail Edit mode, which is in
64 @file{lisp/rmailedit.el}, is a major mode that is very similar to
65 Text mode except that it provides three additional commands. Its
66 definition is distinct from that of Text mode, but was derived from it.
69 Even if the new mode is not an obvious derivative of any other mode,
70 it is convenient to use @code{define-derived-mode} with a @code{nil}
71 parent argument, since it automatically enforces the most important
72 coding conventions for you.
74 Rmail Edit mode is an example of a case where one piece of text is put
75 temporarily into a different major mode so it can be edited in a
76 different way (with ordinary SXEmacs commands rather than Rmail). In such
77 cases, the temporary major mode usually has a command to switch back to
78 the buffer's usual mode (Rmail mode, in this case). You might be
79 tempted to present the temporary redefinitions inside a recursive edit
80 and restore the usual ones when the user exits; but this is a bad idea
81 because it constrains the user's options when it is done in more than
82 one buffer: recursive edits must be exited most-recently-entered first.
83 Using alternative major modes avoids this limitation. @xref{Recursive
86 The standard SXEmacs Lisp library directory contains the code for
87 several major modes, in files including @file{text-mode.el},
88 @file{texinfo.el}, @file{lisp-mode.el}, @file{c-mode.el}, and
89 @file{rmail.el}. You can look at these libraries to see how modes are
90 written. Text mode is perhaps the simplest major mode aside from
91 Fundamental mode. Rmail mode is a complicated and specialized mode.
94 * Major Mode Conventions:: Coding conventions for keymaps, etc.
95 * Example Major Modes:: Text mode and Lisp modes.
96 * Auto Major Mode:: How SXEmacs chooses the major mode automatically.
97 * Mode Help:: Finding out how to use a mode.
98 * Derived Modes:: Defining a new major mode based on another major
103 @node Major Mode Conventions
104 @subsection Major Mode Conventions
106 The code for existing major modes follows various coding conventions,
107 including conventions for local keymap and syntax table initialization,
108 global names, and hooks. Please follow these conventions when you
109 define a new major mode:
113 Define a command whose name ends in @samp{-mode}, with no arguments,
114 that switches to the new mode in the current buffer. This command
115 should set up the keymap, syntax table, and local variables in an
116 existing buffer without changing the buffer's text.
119 Write a documentation string for this command that describes the
120 special commands available in this mode. @kbd{C-h m}
121 (@code{describe-mode}) in your mode will display this string.
123 The documentation string may include the special documentation
124 substrings, @samp{\[@var{command}]}, @samp{\@{@var{keymap}@}}, and
125 @samp{\<@var{keymap}>}, that enable the documentation to adapt
126 automatically to the user's own key bindings. @xref{Keys in
130 The major mode command should start by calling
131 @code{kill-all-local-variables}. This is what gets rid of the local
132 variables of the major mode previously in effect.
135 The major mode command should set the variable @code{major-mode} to the
136 major mode command symbol. This is how @code{describe-mode} discovers
137 which documentation to print.
140 The major mode command should set the variable @code{mode-name} to the
141 ``pretty'' name of the mode, as a string. This appears in the mode
145 @cindex functions in modes
146 Since all global names are in the same name space, all the global
147 variables, constants, and functions that are part of the mode should
148 have names that start with the major mode name (or with an abbreviation
149 of it if the name is long). @xref{Style Tips}.
152 @cindex keymaps in modes
153 The major mode should usually have its own keymap, which is used as the
154 local keymap in all buffers in that mode. The major mode function
155 should call @code{use-local-map} to install this local map.
156 @xref{Active Keymaps}, for more information.
158 This keymap should be kept in a global variable named
159 @code{@var{modename}-mode-map}. Normally the library that defines the
160 mode sets this variable.
163 @cindex syntax tables in modes
164 The mode may have its own syntax table or may share one with other
165 related modes. If it has its own syntax table, it should store this in
166 a variable named @code{@var{modename}-mode-syntax-table}. @xref{Syntax
170 @cindex abbrev tables in modes
171 The mode may have its own abbrev table or may share one with other
172 related modes. If it has its own abbrev table, it should store this in
173 a variable named @code{@var{modename}-mode-abbrev-table}. @xref{Abbrev
177 Use @code{defvar} to set mode-related variables, so that they are not
178 reinitialized if they already have a value. (Such reinitialization
179 could discard customizations made by the user.)
182 @cindex buffer-local variables in modes
183 To make a buffer-local binding for a SXEmacs customization variable, use
184 @code{make-local-variable} in the major mode command, not
185 @code{make-variable-buffer-local}. The latter function would make the
186 variable local to every buffer in which it is subsequently set, which
187 would affect buffers that do not use this mode. It is undesirable for a
188 mode to have such global effects. @xref{Buffer-Local Variables}.
190 It's ok to use @code{make-variable-buffer-local}, if you wish, for a
191 variable used only within a single Lisp package.
195 @cindex major mode hook
196 Each major mode should have a @dfn{mode hook} named
197 @code{@var{modename}-mode-hook}. The major mode command should run that
198 hook, with @code{run-hooks}, as the very last thing it
202 The major mode command may also run the hooks of some more basic modes.
203 For example, @code{indented-text-mode} runs @code{text-mode-hook} as
204 well as @code{indented-text-mode-hook}. It may run these other hooks
205 immediately before the mode's own hook (that is, after everything else),
206 or it may run them earlier.
209 The major mode command may start by calling some other major mode
210 command (called the @dfn{parent mode}) and then alter some of its
211 settings. A mode that does this is called a @dfn{derived mode}. The
212 recommended way to define one is to use @code{define-derived-mode},
213 but this is not required. Such a mode should use
214 @code{delay-mode-hooks} around its entire body, including the call to
215 the parent mode command and the final call to @code{run-mode-hooks}.
216 (Using @code{define-derived-mode} does this automatically.)
219 If something special should be done if the user switches a buffer from
220 this mode to any other major mode, the mode can set a local value for
221 @code{change-major-mode-hook}.
224 If this mode is appropriate only for specially-prepared text, then the
225 major mode command symbol should have a property named @code{mode-class}
226 with value @code{special}, put on as follows:
228 @cindex @code{mode-class} property
229 @cindex @code{special}
231 (put 'funny-mode 'mode-class 'special)
235 This tells SXEmacs that new buffers created while the current buffer has
236 Funny mode should not inherit Funny mode. Modes such as Dired, Rmail,
237 and Buffer List use this feature.
240 If you want to make the new mode the default for files with certain
241 recognizable names, add an element to @code{auto-mode-alist} to select
242 the mode for those file names. If you define the mode command to
243 autoload, you should add this element in the same file that calls
244 @code{autoload}. Otherwise, it is sufficient to add the element in the
245 file that contains the mode definition. @xref{Auto Major Mode}.
248 @cindex @file{init.el} customization
249 In the documentation, you should provide a sample @code{autoload} form
250 and an example of how to add to @code{auto-mode-alist}, that users can
251 include in their @file{init.el} files.
255 The top-level forms in the file defining the mode should be written so
256 that they may be evaluated more than once without adverse consequences.
257 Even if you never load the file more than once, someone else will.
260 @defvar change-major-mode-hook
261 This normal hook is run by @code{kill-all-local-variables} before it
262 does anything else. This gives major modes a way to arrange for
263 something special to be done if the user switches to a different major
264 mode. For best results, make this variable buffer-local, so that it
265 will disappear after doing its job and will not interfere with the
266 subsequent major mode. @xref{Hooks}.
270 @node Example Major Modes
271 @subsection Major Mode Examples
273 Text mode is perhaps the simplest mode besides Fundamental mode.
274 Here are excerpts from @file{text-mode.el} that illustrate many of
275 the conventions listed above:
279 ;; @r{Create mode-specific tables.}
280 (defvar text-mode-syntax-table nil
281 "Syntax table used while in text mode.")
285 (if text-mode-syntax-table
286 () ; @r{Do not change the table if it is already set up.}
287 (setq text-mode-syntax-table (make-syntax-table))
288 (modify-syntax-entry ?\" ". " text-mode-syntax-table)
289 (modify-syntax-entry ?\\ ". " text-mode-syntax-table)
290 (modify-syntax-entry ?' "w " text-mode-syntax-table))
294 (defvar text-mode-abbrev-table nil
295 "Abbrev table used while in text mode.")
296 (define-abbrev-table 'text-mode-abbrev-table ())
300 (defvar text-mode-map nil) ; @r{Create a mode-specific keymap.}
303 () ; @r{Do not change the keymap if it is already set up.}
304 (setq text-mode-map (make-sparse-keymap))
305 (define-key text-mode-map "\t" 'tab-to-tab-stop)
306 (define-key text-mode-map "\es" 'center-line)
307 (define-key text-mode-map "\eS" 'center-paragraph))
311 Here is the complete major mode function definition for Text mode:
316 "Major mode for editing text intended for humans to read.
317 Special commands: \\@{text-mode-map@}
320 Turning on text-mode runs the hook `text-mode-hook'."
322 (kill-all-local-variables)
325 (use-local-map text-mode-map) ; @r{This provides the local keymap.}
326 (setq mode-name "Text") ; @r{This name goes into the modeline.}
327 (setq major-mode 'text-mode) ; @r{This is how @code{describe-mode}}
328 ; @r{finds the doc string to print.}
329 (setq local-abbrev-table text-mode-abbrev-table)
330 (set-syntax-table text-mode-syntax-table)
331 (run-hooks 'text-mode-hook)) ; @r{Finally, this permits the user to}
332 ; @r{customize the mode with a hook.}
336 @cindex @file{lisp-mode.el}
337 The three Lisp modes (Lisp mode, Emacs Lisp mode, and Lisp
338 Interaction mode) have more features than Text mode and the code is
339 correspondingly more complicated. Here are excerpts from
340 @file{lisp-mode.el} that illustrate how these modes are written.
342 @cindex syntax table example
345 ;; @r{Create mode-specific table variables.}
346 (defvar lisp-mode-syntax-table nil "")
347 (defvar emacs-lisp-mode-syntax-table nil "")
348 (defvar lisp-mode-abbrev-table nil "")
352 (if (not emacs-lisp-mode-syntax-table) ; @r{Do not change the table}
353 ; @r{if it is already set.}
355 (setq emacs-lisp-mode-syntax-table (make-syntax-table))
359 ;; @r{Set syntax of chars up to 0 to class of chars that are}
360 ;; @r{part of symbol names but not words.}
361 ;; @r{(The number 0 is @code{48} in the @sc{ascii} character set.)}
363 (modify-syntax-entry i "_ " emacs-lisp-mode-syntax-table)
368 ;; @r{Set the syntax for other characters.}
369 (modify-syntax-entry ? " " emacs-lisp-mode-syntax-table)
370 (modify-syntax-entry ?\t " " emacs-lisp-mode-syntax-table)
374 (modify-syntax-entry ?\( "() " emacs-lisp-mode-syntax-table)
375 (modify-syntax-entry ?\) ")( " emacs-lisp-mode-syntax-table)
377 ;; @r{Create an abbrev table for lisp-mode.}
378 (define-abbrev-table 'lisp-mode-abbrev-table ())
382 Much code is shared among the three Lisp modes. The following
383 function sets various variables; it is called by each of the major Lisp
388 (defun lisp-mode-variables (lisp-syntax)
389 ;; @r{The @code{lisp-syntax} argument is @code{nil} in Emacs Lisp mode,}
390 ;; @r{and @code{t} in the other two Lisp modes.}
392 (if (not lisp-mode-syntax-table)
393 ;; @r{The Emacs Lisp mode syntax table always exists, but}
394 ;; @r{the Lisp Mode syntax table is created the first time a}
395 ;; @r{mode that needs it is called. This is to save space.}
398 (progn (setq lisp-mode-syntax-table
399 (copy-syntax-table emacs-lisp-mode-syntax-table))
400 ;; @r{Change some entries for Lisp mode.}
401 (modify-syntax-entry ?\| "\" "
402 lisp-mode-syntax-table)
403 (modify-syntax-entry ?\[ "_ "
404 lisp-mode-syntax-table)
405 (modify-syntax-entry ?\] "_ "
406 lisp-mode-syntax-table)))
409 (set-syntax-table lisp-mode-syntax-table)))
410 (setq local-abbrev-table lisp-mode-abbrev-table)
415 Functions such as @code{forward-paragraph} use the value of the
416 @code{paragraph-start} variable. Since Lisp code is different from
417 ordinary text, the @code{paragraph-start} variable needs to be set
418 specially to handle Lisp. Also, comments are indented in a special
419 fashion in Lisp and the Lisp modes need their own mode-specific
420 @code{comment-indent-function}. The code to set these variables is the
421 rest of @code{lisp-mode-variables}.
425 (make-local-variable 'paragraph-start)
426 ;; @r{Having @samp{^} is not clean, but @code{page-delimiter}}
427 ;; @r{has them too, and removing those is a pain.}
428 (setq paragraph-start (concat "^$\\|" page-delimiter))
432 (make-local-variable 'comment-indent-function)
433 (setq comment-indent-function 'lisp-comment-indent))
437 Each of the different Lisp modes has a slightly different keymap. For
438 example, Lisp mode binds @kbd{C-c C-l} to @code{run-lisp}, but the other
439 Lisp modes do not. However, all Lisp modes have some commands in
440 common. The following function adds these common commands to a given
445 (defun lisp-mode-commands (map)
446 (define-key map "\e\C-q" 'indent-sexp)
447 (define-key map "\177" 'backward-delete-char-untabify)
448 (define-key map "\t" 'lisp-indent-line))
452 Here is an example of using @code{lisp-mode-commands} to initialize a
453 keymap, as part of the code for Emacs Lisp mode. First we declare a
454 variable with @code{defvar} to hold the mode-specific keymap. When this
455 @code{defvar} executes, it sets the variable to @code{nil} if it was
456 void. Then we set up the keymap if the variable is @code{nil}.
458 This code avoids changing the keymap or the variable if it is already
459 set up. This lets the user customize the keymap.
463 (defvar emacs-lisp-mode-map () "")
464 (if emacs-lisp-mode-map
466 (setq emacs-lisp-mode-map (make-sparse-keymap))
467 (define-key emacs-lisp-mode-map "\e\C-x" 'eval-defun)
468 (lisp-mode-commands emacs-lisp-mode-map))
472 Finally, here is the complete major mode function definition for
477 (defun emacs-lisp-mode ()
478 "Major mode for editing Lisp code to run in SXEmacs.
480 Delete converts tabs to spaces as it moves back.
481 Blank lines separate paragraphs. Semicolons start comments.
482 \\@{emacs-lisp-mode-map@}
485 Entry to this mode runs the hook `emacs-lisp-mode-hook'."
487 (kill-all-local-variables)
488 (use-local-map emacs-lisp-mode-map) ; @r{This provides the local keymap.}
489 (set-syntax-table emacs-lisp-mode-syntax-table)
492 (setq major-mode 'emacs-lisp-mode) ; @r{This is how @code{describe-mode}}
493 ; @r{finds out what to describe.}
494 (setq mode-name "Emacs-Lisp") ; @r{This goes into the modeline.}
495 (lisp-mode-variables nil) ; @r{This defines various variables.}
496 (run-hooks 'emacs-lisp-mode-hook)) ; @r{This permits the user to use a}
497 ; @r{hook to customize the mode.}
502 @node Auto Major Mode
503 @subsection How SXEmacs Chooses a Major Mode
505 Based on information in the file name or in the file itself, SXEmacs
506 automatically selects a major mode for the new buffer when a file is
509 @deffn Command fundamental-mode
510 Fundamental mode is a major mode that is not specialized for anything
511 in particular. Other major modes are defined in effect by comparison
512 with this one---their definitions say what to change, starting from
513 Fundamental mode. The @code{fundamental-mode} function does @emph{not}
514 run any hooks; you're not supposed to customize it.
516 If you want SXEmacs to behave differently in Fundamental mode, change
517 the @emph{global} state of SXEmacs.
520 @deffn Command normal-mode &optional find-file
521 This function establishes the proper major mode and local variable
522 bindings for the current buffer. First it calls @code{set-auto-mode},
523 then it runs @code{hack-local-variables} to parse, and bind or
524 evaluate as appropriate, any local variables.
526 If the @var{find-file} argument to @code{normal-mode} is
527 non-@code{nil}, @code{normal-mode} assumes that the @code{find-file}
528 function is calling it. In this case, it may process a local variables
529 list at the end of the file and in the @samp{-*-} line. The variable
530 @code{enable-local-variables} controls whether to do so.
532 If you run @code{normal-mode} interactively, the argument
533 @var{find-file} is normally @code{nil}. In this case,
534 @code{normal-mode} unconditionally processes any local variables list.
535 @xref{File variables, , Local Variables in Files, sxemacs, The SXEmacs
536 Reference Manual}, for the syntax of the local variables section of a file.
538 @cindex file mode specification error
539 @code{normal-mode} uses @code{condition-case} around the call to the
540 major mode function, so errors are caught and reported as a @samp{File
541 mode specification error}, followed by the original error message.
544 @defopt enable-local-variables
545 This variable controls processing of local variables lists in files
546 being visited. A value of @code{t} means process the local variables
547 lists unconditionally; @code{nil} means ignore them; anything else means
548 ask the user what to do for each file. The default value is @code{t}.
551 @defvar ignored-local-variables
552 This variable holds a list of variables that should not be
553 set by a local variables list. Any value specified
554 for one of these variables is ignored.
557 In addition to this list, any variable whose name has a non-@code{nil}
558 @code{risky-local-variable} property is also ignored.
560 @defopt enable-local-eval
561 This variable controls processing of @samp{Eval:} in local variables
562 lists in files being visited. A value of @code{t} means process them
563 unconditionally; @code{nil} means ignore them; anything else means ask
564 the user what to do for each file. The default value is @code{maybe}.
568 @cindex visited file mode
569 This function selects the major mode that is appropriate for the
570 current buffer. It may base its decision on the value of the @w{@samp{-*-}}
571 line, on the visited file name (using @code{auto-mode-alist}), or on the
572 value of a local variable. However, this function does not look for
573 the @samp{mode:} local variable near the end of a file; the
574 @code{hack-local-variables} function does that. @xref{Choosing Modes, ,
575 How Major Modes are Chosen, sxemacs, The SXEmacs Lisp Reference Manual}.
578 @defopt default-major-mode
579 This variable holds the default major mode for new buffers. The
580 standard value is @code{fundamental-mode}.
582 If the value of @code{default-major-mode} is @code{nil}, SXEmacs uses
583 the (previously) current buffer's major mode for the major mode of a new
584 buffer. However, if the major mode symbol has a @code{mode-class}
585 property with value @code{special}, then it is not used for new buffers;
586 Fundamental mode is used instead. The modes that have this property are
587 those such as Dired and Rmail that are useful only with text that has
588 been specially prepared.
591 @defun set-buffer-major-mode buffer
592 This function sets the major mode of @var{buffer} to the value of
593 @code{default-major-mode}. If that variable is @code{nil}, it uses
594 the current buffer's major mode (if that is suitable).
596 The low-level primitives for creating buffers do not use this function,
597 but medium-level commands such as @code{switch-to-buffer} and
598 @code{find-file-noselect} use it whenever they create buffers.
601 @defvar initial-major-mode
602 @cindex @samp{*scratch*}
603 The value of this variable determines the major mode of the initial
604 @samp{*scratch*} buffer. The value should be a symbol that is a major
605 mode command name. The default value is @code{lisp-interaction-mode}.
608 @defvar auto-mode-alist
609 This variable contains an association list of file name patterns
610 (regular expressions; @pxref{Regular Expressions}) and corresponding
611 major mode functions. Usually, the file name patterns test for
612 suffixes, such as @samp{.el} and @samp{.c}, but this need not be the
613 case. An ordinary element of the alist looks like @code{(@var{regexp} .
614 @var{mode-function})}.
620 (("^/tmp/fol/" . text-mode)
621 ("\\.texinfo\\'" . texinfo-mode)
622 ("\\.texi\\'" . texinfo-mode)
625 ("\\.el\\'" . emacs-lisp-mode)
632 When you visit a file whose expanded file name (@pxref{File Name
633 Expansion}) matches a @var{regexp}, @code{set-auto-mode} calls the
634 corresponding @var{mode-function}. This feature enables SXEmacs to
635 select the proper major mode for most files.
637 If an element of @code{auto-mode-alist} has the form @code{(@var{regexp}
638 @var{function} t)}, then after calling @var{function}, SXEmacs searches
639 @code{auto-mode-alist} again for a match against the portion of the file
640 name that did not match before.
642 This match-again feature is useful for uncompression packages: an entry
643 of the form @code{("\\.gz\\'" . @var{function})} can uncompress the file
644 and then put the uncompressed file in the proper mode according to the
645 name sans @samp{.gz}.
647 Here is an example of how to prepend several pattern pairs to
648 @code{auto-mode-alist}. (You might use this sort of expression in your
649 @file{init.el} file.)
653 (setq auto-mode-alist
655 ;; @r{File name starts with a dot.}
656 '(("/\\.[^/]*\\'" . fundamental-mode)
657 ;; @r{File name has no dot.}
658 ("[^\\./]*\\'" . fundamental-mode)
659 ;; @r{File name ends in @samp{.C}.}
660 ("\\.C\\'" . c++-mode))
666 @defvar interpreter-mode-alist
667 This variable specifies major modes to use for scripts that specify a
668 command interpreter in an @samp{#!} line. Its value is a list of
669 elements of the form @code{(@var{interpreter} . @var{mode})}; for
670 example, @code{("perl" . perl-mode)} is one element present by default.
671 The element says to use mode @var{mode} if the file specifies
674 This variable is applicable only when the @code{auto-mode-alist} does
675 not indicate which major mode to use.
678 @defun hack-local-variables &optional force
679 This function parses, and binds or evaluates as appropriate, any local
680 variables for the current buffer.
682 The handling of @code{enable-local-variables} documented for
683 @code{normal-mode} actually takes place here. The argument @var{force}
684 usually comes from the argument @var{find-file} given to
690 @subsection Getting Help about a Major Mode
692 @cindex help for major mode
693 @cindex documentation for major mode
695 The @code{describe-mode} function is used to provide information
696 about major modes. It is normally called with @kbd{C-h m}. The
697 @code{describe-mode} function uses the value of @code{major-mode},
698 which is why every major mode function needs to set the
699 @code{major-mode} variable.
701 @deffn Command describe-mode
702 This function displays the documentation of the current major mode.
704 The @code{describe-mode} function calls the @code{documentation}
705 function using the value of @code{major-mode} as an argument. Thus, it
706 displays the documentation string of the major mode function.
707 (@xref{Accessing Documentation}.)
711 This variable holds the symbol for the current buffer's major mode.
712 This symbol should have a function definition that is the command to
713 switch to that major mode. The @code{describe-mode} function uses the
714 documentation string of the function as the documentation of the major
720 @subsection Defining Derived Modes
722 It's often useful to define a new major mode in terms of an existing
723 one. An easy way to do this is to use @code{define-derived-mode}.
725 @defmac define-derived-mode variant parent name docstring body@dots{}
726 This construct defines @var{variant} as a major mode command, using
727 @var{name} as the string form of the mode name.
729 The new command @var{variant} is defined to call the function
730 @var{parent}, then override certain aspects of that parent mode:
734 The new mode has its own keymap, named @code{@var{variant}-map}.
735 @code{define-derived-mode} initializes this map to inherit from
736 @code{@var{parent}-map}, if it is not already set.
739 The new mode has its own syntax table, kept in the variable
740 @code{@var{variant}-syntax-table}.
741 @code{define-derived-mode} initializes this variable by copying
742 @code{@var{parent}-syntax-table}, if it is not already set.
745 The new mode has its own abbrev table, kept in the variable
746 @code{@var{variant}-abbrev-table}.
747 @code{define-derived-mode} initializes this variable by copying
748 @code{@var{parent}-abbrev-table}, if it is not already set.
751 The new mode has its own mode hook, @code{@var{variant}-hook},
752 which it runs in standard fashion as the very last thing that it does.
753 (The new mode also runs the mode hook of @var{parent} as part
754 of calling @var{parent}.)
757 In addition, you can specify how to override other aspects of
758 @var{parent} with @var{body}. The command @var{variant}
759 evaluates the forms in @var{body} after setting up all its usual
760 overrides, just before running @code{@var{variant}-hook}.
762 The argument @var{docstring} specifies the documentation string for the
763 new mode. If you omit @var{docstring}, @code{define-derived-mode}
764 generates a documentation string.
766 Here is a hypothetical example:
769 (define-derived-mode hypertext-mode
770 text-mode "Hypertext"
771 "Major mode for hypertext.
772 \\@{hypertext-mode-map@}"
773 (setq case-fold-search nil))
775 (define-key hypertext-mode-map
776 [down-mouse-3] 'do-hyper-link)
779 Do not write an @code{interactive} spec in the definition;
780 @code{define-derived-mode} does that automatically.
788 A @dfn{minor mode} provides features that users may enable or disable
789 independently of the choice of major mode. Minor modes can be enabled
790 individually or in combination. Minor modes would be better named
791 ``Generally available, optional feature modes'' except that such a name is
794 A minor mode is not usually a modification of single major mode. For
795 example, Auto Fill mode may be used in any major mode that permits text
796 insertion. To be general, a minor mode must be effectively independent
797 of the things major modes do.
799 A minor mode is often much more difficult to implement than a major
800 mode. One reason is that you should be able to activate and deactivate
801 minor modes in any order. A minor mode should be able to have its
802 desired effect regardless of the major mode and regardless of the other
803 minor modes in effect.
805 Often the biggest problem in implementing a minor mode is finding a
806 way to insert the necessary hook into the rest of SXEmacs. Minor mode
807 keymaps make this easier than it used to be.
810 * Minor Mode Conventions:: Tips for writing a minor mode.
811 * Keymaps and Minor Modes:: How a minor mode can have its own keymap.
815 @node Minor Mode Conventions
816 @subsection Conventions for Writing Minor Modes
817 @cindex minor mode conventions
818 @cindex conventions for writing minor modes
820 There are conventions for writing minor modes just as there are for
821 major modes. Several of the major mode conventions apply to minor
822 modes as well: those regarding the name of the mode initialization
823 function, the names of global symbols, and the use of keymaps and
826 In addition, there are several conventions that are specific to
831 @cindex mode variable
832 Make a variable whose name ends in @samp{-mode} to represent the minor
833 mode. Its value should enable or disable the mode (@code{nil} to
834 disable; anything else to enable.) We call this the @dfn{mode
837 This variable is used in conjunction with the @code{minor-mode-alist} to
838 display the minor mode name in the modeline. It can also enable
839 or disable a minor mode keymap. Individual commands or hooks can also
840 check the variable's value.
842 If you want the minor mode to be enabled separately in each buffer,
843 make the variable buffer-local.
846 Define a command whose name is the same as the mode variable.
847 Its job is to enable and disable the mode by setting the variable.
849 The command should accept one optional argument. If the argument is
850 @code{nil}, it should toggle the mode (turn it on if it is off, and off
851 if it is on). Otherwise, it should turn the mode on if the argument is
852 a positive integer, a symbol other than @code{nil} or @code{-}, or a
853 list whose @sc{car} is such an integer or symbol; it should turn the
856 Here is an example taken from the definition of @code{transient-mark-mode}.
857 It shows the use of @code{transient-mark-mode} as a variable that enables or
858 disables the mode's behavior, and also shows the proper way to toggle,
859 enable or disable the minor mode based on the raw prefix argument value.
863 (setq transient-mark-mode
864 (if (null arg) (not transient-mark-mode)
865 (> (prefix-numeric-value arg) 0)))
870 Add an element to @code{minor-mode-alist} for each minor mode
871 (@pxref{Modeline Variables}). This element should be a list of the
875 (@var{mode-variable} @var{string})
878 Here @var{mode-variable} is the variable that controls enabling of the
879 minor mode, and @var{string} is a short string, starting with a space,
880 to represent the mode in the modeline. These strings must be short so
881 that there is room for several of them at once.
883 When you add an element to @code{minor-mode-alist}, use @code{assq} to
884 check for an existing element, to avoid duplication. For example:
888 (or (assq 'leif-mode minor-mode-alist)
889 (setq minor-mode-alist
890 (cons '(leif-mode " Leif") minor-mode-alist)))
896 @node Keymaps and Minor Modes
897 @subsection Keymaps and Minor Modes
899 Each minor mode can have its own keymap, which is active when the mode
900 is enabled. To set up a keymap for a minor mode, add an element to the
901 alist @code{minor-mode-map-alist}. @xref{Active Keymaps}.
903 @cindex @code{self-insert-command}, minor modes
904 One use of minor mode keymaps is to modify the behavior of certain
905 self-inserting characters so that they do something else as well as
906 self-insert. In general, this is the only way to do that, since the
907 facilities for customizing @code{self-insert-command} are limited to
908 special cases (designed for abbrevs and Auto Fill mode). (Do not try
909 substituting your own definition of @code{self-insert-command} for the
910 standard one. The editor command loop handles this function specially.)
913 @node Modeline Format
914 @section Modeline Format
917 Each SXEmacs window (aside from minibuffer windows) includes a modeline,
918 which displays status information about the buffer displayed in the
919 window. The modeline contains information about the buffer, such as its
920 name, associated file, depth of recursive editing, and the major and
923 This section describes how the contents of the modeline are
924 controlled. It is in the chapter on modes because much of the
925 information displayed in the modeline relates to the enabled major and
928 @code{modeline-format} is a buffer-local variable that holds a
929 template used to display the modeline of the current buffer. All
930 windows for the same buffer use the same @code{modeline-format} and
931 their modelines appear the same (except for scrolling percentages and
934 The modeline of a window is normally updated whenever a different
935 buffer is shown in the window, or when the buffer's modified-status
936 changes from @code{nil} to @code{t} or vice-versa. If you modify any of
937 the variables referenced by @code{modeline-format} (@pxref{Modeline
938 Variables}), you may want to force an update of the modeline so as to
939 display the new information.
942 @defun redraw-modeline &optional all
943 Force redisplay of the current buffer's modeline. If @var{all} is
944 non-@code{nil}, then force redisplay of all modelines.
947 The modeline is usually displayed in inverse video. This
948 is controlled using the @code{modeline} face. @xref{Faces}.
951 * Modeline Data:: The data structure that controls the modeline.
952 * Modeline Variables:: Variables used in that data structure.
953 * %-Constructs:: Putting information into a modeline.
958 @subsection The Data Structure of the Modeline
959 @cindex modeline construct
961 The modeline contents are controlled by a data structure of lists,
962 strings, symbols, and numbers kept in the buffer-local variable
963 @code{modeline-format}. The data structure is called a @dfn{modeline
964 construct}, and it is built in recursive fashion out of simpler modeline
965 constructs. The same data structure is used for constructing
966 frame titles (@pxref{Frame Titles}).
968 @defvar modeline-format
969 The value of this variable is a modeline construct with overall
970 responsibility for the modeline format. The value of this variable
971 controls which other variables are used to form the modeline text, and
975 A modeline construct may be as simple as a fixed string of text, but
976 it usually specifies how to use other variables to construct the text.
977 Many of these variables are themselves defined to have modeline
978 constructs as their values.
980 The default value of @code{modeline-format} incorporates the values
981 of variables such as @code{mode-name} and @code{minor-mode-alist}.
982 Because of this, very few modes need to alter @code{modeline-format}.
983 For most purposes, it is sufficient to alter the variables referenced by
984 @code{modeline-format}.
986 A modeline construct may be a string, symbol, glyph, generic
987 specifier, list or cons cell.
990 @cindex percent symbol in modeline
992 A string as a modeline construct is displayed verbatim in the mode line
993 except for @dfn{@code{%}-constructs}. Decimal digits after the @samp{%}
994 specify the field width for space filling on the right (i.e., the data
995 is left justified). @xref{%-Constructs}.
998 A symbol as a modeline construct stands for its value. The value of
999 @var{symbol} is processed as a modeline construct, in place of
1000 @var{symbol}. However, the symbols @code{t} and @code{nil} are ignored;
1001 so is any symbol whose value is void.
1003 There is one exception: if the value of @var{symbol} is a string, it is
1004 displayed verbatim: the @code{%}-constructs are not recognized.
1007 A glyph is displayed as is.
1009 @item @var{generic-specifier}
1010 A @var{generic-specifier} (i.e. a specifier of type @code{generic})
1011 stands for its instance. The instance of @var{generic-specifier} is
1012 computed in the current window using the equivalent of
1013 @code{specifier-instance} and the value is processed.
1015 @item (@var{string} @var{rest}@dots{}) @r{or} (@var{list} @var{rest}@dots{})
1016 A list whose first element is a string or list means to process all the
1017 elements recursively and concatenate the results. This is the most
1018 common form of mode line construct.
1020 @item (@var{symbol} @var{then} @var{else})
1021 A list whose first element is a symbol is a conditional. Its meaning
1022 depends on the value of @var{symbol}. If the value is non-@code{nil},
1023 the second element, @var{then}, is processed recursively as a modeline
1024 element. But if the value of @var{symbol} is @code{nil}, the third
1025 element, @var{else}, is processed recursively. You may omit @var{else};
1026 then the mode line element displays nothing if the value of @var{symbol}
1029 @item (@var{width} @var{rest}@dots{})
1030 A list whose first element is an integer specifies truncation or
1031 padding of the results of @var{rest}. The remaining elements
1032 @var{rest} are processed recursively as modeline constructs and
1033 concatenated together. Then the result is space filled (if
1034 @var{width} is positive) or truncated (to @minus{}@var{width} columns,
1035 if @var{width} is negative) on the right.
1037 For example, the usual way to show what percentage of a buffer is above
1038 the top of the window is to use a list like this: @code{(-3 "%p")}.
1040 @item (@var{extent} @var{rest}@dots{})
1042 A list whose car is an extent means the cdr of the list is processed
1043 normally but the results are displayed using the face of the extent, and
1044 mouse clicks over this section are processed using the keymap of the
1045 extent. (In addition, if the extent has a help-echo property, that
1046 string will be echoed when the mouse moves over this section.) If
1047 extents are nested, all keymaps are properly consulted when processing
1048 mouse clicks, but multiple faces are not correctly merged (only the
1049 first face is used), and lists of faces are not correctly handled.
1050 @c #### Document generate-modeline-string.
1051 @c See `generated-modeline-string' for more information.
1054 If you do alter @code{modeline-format} itself, the new value should
1055 use the same variables that appear in the default value (@pxref{Modeline
1056 Variables}), rather than duplicating their contents or displaying
1057 the information in another fashion. This way, customizations made by
1058 the user or by Lisp programs (such as @code{display-time} and major
1059 modes) via changes to those variables remain effective.
1061 @cindex Shell mode @code{modeline-format}
1062 Here is an example of a @code{modeline-format} that might be
1063 useful for @code{shell-mode}, since it contains the hostname and default
1068 (setq modeline-format
1073 (getenv "HOST") ; @r{One element is not constant.}
1085 '(line-number-mode "L%l--")
1092 @node Modeline Variables
1093 @subsection Variables Used in the Modeline
1095 This section describes variables incorporated by the
1096 standard value of @code{modeline-format} into the text of the mode
1097 line. There is nothing inherently special about these variables; any
1098 other variables could have the same effects on the modeline if
1099 @code{modeline-format} were changed to use them.
1101 @defvar modeline-modified
1102 This variable holds the value of the modeline construct that displays
1103 whether the current buffer is modified.
1105 The default value of @code{modeline-modified} is @code{("--%1*%1+-")}.
1106 This means that the modeline displays @samp{--**-} if the buffer is
1107 modified, @samp{-----} if the buffer is not modified, @samp{--%%-} if
1108 the buffer is read only, and @samp{--%*--} if the buffer is read only
1111 Changing this variable does not force an update of the modeline.
1114 @defvar modeline-buffer-identification
1115 This variable identifies the buffer being displayed in the window. Its
1116 default value is @code{("%F: %17b")}, which means that it usually
1117 displays @samp{SXEmacs:} followed by seventeen characters of the buffer
1118 @c we have to change this it still displays XEmacs
1121 In a terminal frame, it displays the frame name instead of
1122 @samp{SXEmacs}; this has the effect of showing the frame number.) You
1123 may want to change this in modes such as Rmail that do not behave like a
1127 @defvar global-mode-string
1128 This variable holds a modeline spec that appears in the mode line by
1129 default, just after the buffer name. The command @code{display-time}
1130 sets @code{global-mode-string} to refer to the variable
1131 @code{display-time-string}, which holds a string containing the time and
1134 The @samp{%M} construct substitutes the value of
1135 @code{global-mode-string}, but this is obsolete, since the variable is
1136 included directly in the modeline.
1140 This buffer-local variable holds the ``pretty'' name of the current
1141 buffer's major mode. Each major mode should set this variable so that the
1142 mode name will appear in the modeline.
1145 @defvar minor-mode-alist
1146 This variable holds an association list whose elements specify how the
1147 modeline should indicate that a minor mode is active. Each element of
1148 the @code{minor-mode-alist} should be a two-element list:
1151 (@var{minor-mode-variable} @var{modeline-string})
1154 More generally, @var{modeline-string} can be any mode line spec. It
1155 appears in the mode line when the value of @var{minor-mode-variable} is
1156 non-@code{nil}, and not otherwise. These strings should begin with
1157 spaces so that they don't run together. Conventionally, the
1158 @var{minor-mode-variable} for a specific mode is set to a non-@code{nil}
1159 value when that minor mode is activated.
1161 The default value of @code{minor-mode-alist} is:
1166 @result{} ((vc-mode vc-mode)
1167 (abbrev-mode " Abbrev")
1168 (overwrite-mode overwrite-mode)
1169 (auto-fill-function " Fill")
1170 (defining-kbd-macro " Def")
1171 (isearch-mode isearch-mode))
1175 @code{minor-mode-alist} is not buffer-local. The variables mentioned
1176 in the alist should be buffer-local if the minor mode can be enabled
1177 separately in each buffer.
1180 @defvar modeline-process
1181 This buffer-local variable contains the modeline information on process
1182 status in modes used for communicating with subprocesses. It is
1183 displayed immediately following the major mode name, with no intervening
1184 space. For example, its value in the @samp{*shell*} buffer is
1185 @code{(":@: %s")}, which allows the shell to display its status along
1186 with the major mode as: @samp{(Shell:@: run)}. Normally this variable
1190 @defvar default-modeline-format
1191 This variable holds the default @code{modeline-format} for buffers
1192 that do not override it. This is the same as @code{(default-value
1195 The default value of @code{default-modeline-format} is:
1201 modeline-buffer-identification
1212 (line-number-mode "L%l--")
1220 The variable @code{vc-mode}, local in each buffer, records whether the
1221 buffer's visited file is maintained with version control, and, if so,
1222 which kind. Its value is @code{nil} for no version control, or a string
1223 that appears in the mode line.
1228 @subsection @code{%}-Constructs in the ModeLine
1230 The following table lists the recognized @code{%}-constructs and what
1231 they mean. In any construct except @samp{%%}, you can add a decimal
1232 integer after the @samp{%} to specify how many characters to display.
1236 The current buffer name, obtained with the @code{buffer-name} function.
1237 @xref{Buffer Names}.
1240 The visited file name, obtained with the @code{buffer-file-name}
1241 function. @xref{Buffer File Name}.
1244 The name of the selected frame.
1247 The current column number of point.
1250 The current line number of point.
1253 @samp{%} if the buffer is read only (see @code{buffer-read-only}); @*
1254 @samp{*} if the buffer is modified (see @code{buffer-modified-p}); @*
1255 @samp{-} otherwise. @xref{Buffer Modification}.
1258 @samp{*} if the buffer is modified (see @code{buffer-modified-p}); @*
1259 @samp{%} if the buffer is read only (see @code{buffer-read-only}); @*
1260 @samp{-} otherwise. This differs from @samp{%*} only for a modified
1261 read-only buffer. @xref{Buffer Modification}.
1264 @samp{*} if the buffer is modified, and @samp{-} otherwise.
1267 The status of the subprocess belonging to the current buffer, obtained with
1268 @code{process-status}. @xref{Process Information}.
1270 @c The following two may only apply in SXEmacs and XEmacs.
1272 The current line number.
1275 The name of the selected frame; this is only meaningful under the
1276 X Window System. @xref{Frame Name}.
1279 Whether the visited file is a text file or a binary file. (This is a
1280 meaningful distinction only on certain operating systems.)
1283 The percentage of the buffer text above the @strong{top} of window, or
1284 @samp{Top}, @samp{Bottom} or @samp{All}.
1287 The percentage of the buffer text that is above the @strong{bottom} of
1288 the window (which includes the text visible in the window, as well as
1289 the text above the top), plus @samp{Top} if the top of the buffer is
1290 visible on screen; or @samp{Bottom} or @samp{All}.
1293 @samp{Narrow} when narrowing is in effect; nothing otherwise (see
1294 @code{narrow-to-region} in @ref{Narrowing}).
1297 Under SXEmacs/mule, the mnemonic for @code{buffer-file-coding-system}.
1300 An indication of the depth of recursive editing levels (not counting
1301 minibuffer levels): one @samp{[} for each editing level.
1302 @xref{Recursive Editing}.
1305 One @samp{]} for each recursive editing level (not counting minibuffer
1309 The character @samp{%}---this is how to include a literal @samp{%} in a
1310 string in which @code{%}-constructs are allowed.
1313 Dashes sufficient to fill the remainder of the modeline.
1316 The following two @code{%}-constructs are still supported, but they are
1317 obsolete, since you can get the same results with the variables
1318 @code{mode-name} and @code{global-mode-string}.
1322 The value of @code{mode-name}.
1325 The value of @code{global-mode-string}. Currently, only
1326 @code{display-time} modifies the value of @code{global-mode-string}.
1334 A @dfn{hook} is a variable where you can store a function or functions
1335 to be called on a particular occasion by an existing program. SXEmacs
1336 provides hooks for the sake of customization. Most often, hooks are set
1337 up in the @file{init.el} file, but Lisp programs can set them also.
1338 @xref{Standard Hooks}, for a list of standard hook variables.
1340 Most of the hooks in SXEmacs are @dfn{normal hooks}. These variables
1341 contain lists of functions to be called with no arguments. The reason
1342 most hooks are normal hooks is so that you can use them in a uniform
1343 way. You can usually tell when a hook is a normal hook, because its
1344 name ends in @samp{-hook}.
1346 The recommended way to add a hook function to a normal hook is by
1347 calling @code{add-hook} (see below). The hook functions may be any of
1348 the valid kinds of functions that @code{funcall} accepts (@pxref{What Is
1349 a Function}). Most normal hook variables are initially void;
1350 @code{add-hook} knows how to deal with this.
1352 As for abnormal hooks, those whose names end in @samp{-function} have
1353 a value that is a single function. Those whose names end in
1354 @samp{-hooks} have a value that is a list of functions. Any hook that
1355 is abnormal is abnormal because a normal hook won't do the job; either
1356 the functions are called with arguments, or their values are meaningful.
1357 The name shows you that the hook is abnormal and that you should look at
1358 its documentation string to see how to use it properly.
1360 Major mode functions are supposed to run a hook called the @dfn{mode
1361 hook} as the last step of initialization. This makes it easy for a user
1362 to customize the behavior of the mode, by overriding the local variable
1363 assignments already made by the mode. But hooks are used in other
1364 contexts too. For example, the hook @code{suspend-hook} runs just
1365 before SXEmacs suspends itself (@pxref{Suspending SXEmacs}).
1367 Here's an expression that uses a mode hook to turn on Auto Fill mode
1368 when in Lisp Interaction mode:
1371 (add-hook 'lisp-interaction-mode-hook 'turn-on-auto-fill)
1374 The next example shows how to use a hook to customize the way SXEmacs
1375 formats C code. (People often have strong personal preferences for one
1376 format or another.) Here the hook function is an anonymous lambda
1379 @cindex lambda expression in hook
1382 (add-hook 'c-mode-hook
1383 (function (lambda ()
1384 (setq c-indent-level 4
1389 c-continued-statement-indent 0
1391 comment-column 40))))
1393 (setq c++-mode-hook c-mode-hook)
1397 The final example shows how the appearance of the modeline can be
1398 modified for a particular class of buffers only.
1402 (add-hook 'text-mode-hook
1403 (function (lambda ()
1404 (setq modeline-format
1424 At the appropriate time, SXEmacs uses the @code{run-hooks} function to
1425 run particular hooks. This function calls the hook functions you have
1426 added with @code{add-hooks}.
1428 @defun run-hooks &rest hookvar
1429 This function takes one or more hook variable names as arguments, and
1430 runs each hook in turn. Each @var{hookvar} argument should be a symbol
1431 that is a hook variable. These arguments are processed in the order
1434 If a hook variable has a non-@code{nil} value, that value may be a
1435 function or a list of functions. If the value is a function (either a
1436 lambda expression or a symbol with a function definition), it is
1437 called. If it is a list, the elements are called, in order.
1438 The hook functions are called with no arguments.
1440 For example, here's how @code{emacs-lisp-mode} runs its mode hook:
1443 (run-hooks 'emacs-lisp-mode-hook)
1447 @defun run-mode-hooks &rest hookvars
1448 Like @code{run-hooks}, but is affected by the @code{delay-mode-hooks}
1452 @defmac delay-mode-hooks body...
1453 This macro executes the @var{body} forms but defers all calls to
1454 @code{run-mode-hooks} within them until the end of @var{body}.
1455 This macro enables a derived mode to arrange not to run
1456 its parent modes' mode hooks until the end.
1459 @defun run-hook-with-args hook &rest args
1460 This function is the way to run an abnormal hook and always call all
1461 of the hook functions. It calls each of the hook functions one by
1462 one, passing each of them the arguments @var{args}.
1465 @defun run-hook-with-args-until-failure hook &rest args
1466 This function is the way to run an abnormal hook until one of the hook
1467 functions fails. It calls each of the hook functions, passing each of
1468 them the arguments @var{args}, until some hook function returns
1469 @code{nil}. It then stops and returns @code{nil}. If none of the
1470 hook functions return @code{nil}, it returns a non-@code{nil} value.
1473 @defun run-hook-with-args-until-success hook &rest args
1474 This function is the way to run an abnormal hook until a hook function
1475 succeeds. It calls each of the hook functions, passing each of them
1476 the arguments @var{args}, until some hook function returns
1477 non-@code{nil}. Then it stops, and returns whatever was returned by
1478 the last hook function that was called. If all hook functions return
1479 @code{nil}, it returns @code{nil} as well.
1482 @defun add-hook hook function &optional append local
1483 This function is the handy way to add function @var{function} to hook
1484 variable @var{hook}. The argument @var{function} may be any valid Lisp
1485 function with the proper number of arguments. For example,
1488 (add-hook 'text-mode-hook 'my-text-hook-function)
1492 adds @code{my-text-hook-function} to the hook called @code{text-mode-hook}.
1494 You can use @code{add-hook} for abnormal hooks as well as for normal
1497 It is best to design your hook functions so that the order in which they
1498 are executed does not matter. Any dependence on the order is ``asking
1499 for trouble.'' However, the order is predictable: normally,
1500 @var{function} goes at the front of the hook list, so it will be
1501 executed first (barring another @code{add-hook} call).
1503 If the optional argument @var{append} is non-@code{nil}, the new hook
1504 function goes at the end of the hook list and will be executed last.
1506 If @var{local} is non-@code{nil}, that says to make the new hook
1507 function local to the current buffer. Before you can do this, you must
1508 make the hook itself buffer-local by calling @code{make-local-hook}
1509 (@strong{not} @code{make-local-variable}). If the hook itself is not
1510 buffer-local, then the value of @var{local} makes no difference---the
1511 hook function is always global.
1514 @defun remove-hook hook function &optional local
1515 This function removes @var{function} from the hook variable @var{hook}.
1517 If @var{local} is non-@code{nil}, that says to remove @var{function}
1518 from the local hook list instead of from the global hook list. If the
1519 hook itself is not buffer-local, then the value of @var{local} makes no
1523 @defun make-local-hook hook
1524 This function makes the hook variable @var{hook} local to the current
1525 buffer. When a hook variable is local, it can have local and global
1526 hook functions, and @code{run-hooks} runs all of them.
1528 This function works by making @code{t} an element of the buffer-local
1529 value. That serves as a flag to use the hook functions in the default
1530 value of the hook variable as well as those in the local value. Since
1531 @code{run-hooks} understands this flag, @code{make-local-hook} works
1532 with all normal hooks. It works for only some non-normal hooks---those
1533 whose callers have been updated to understand this meaning of @code{t}.
1535 Do not use @code{make-local-variable} directly for hook variables; it is