update.
[chise/xemacs-chise.git] / man / lispref / modes.texi
1 @c -*-texinfo-*-
2 @c This is part of the XEmacs Lisp Reference Manual.
3 @c Copyright (C) 1990, 1991, 1992, 1993, 1994 Free Software Foundation, Inc.
4 @c See the file lispref.texi for copying conditions.
5 @setfilename ../../info/modes.info
6 @node Modes, Documentation, Drag and Drop, Top
7 @chapter Major and Minor Modes
8 @cindex mode
9
10   A @dfn{mode} is a set of definitions that customize XEmacs and can be
11 turned on and off while you edit.  There are two varieties of modes:
12 @dfn{major modes}, which are mutually exclusive and used for editing
13 particular kinds of text, and @dfn{minor modes}, which provide features
14 that users can enable individually.
15
16   This chapter describes how to write both major and minor modes, how to
17 indicate them in the modeline, and how they run hooks supplied by the
18 user.  For related topics such as keymaps and syntax tables, see
19 @ref{Keymaps}, and @ref{Syntax Tables}.
20
21 @menu
22 * Major Modes::        Defining major modes.
23 * Minor Modes::        Defining minor modes.
24 * Modeline Format::    Customizing the text that appears in the modeline.
25 * Hooks::              How to use hooks; how to write code that provides hooks.
26 @end menu
27
28 @node Major Modes
29 @section Major Modes
30 @cindex major mode
31 @cindex Fundamental mode
32
33   Major modes specialize XEmacs for editing particular kinds of text.
34 Each buffer has only one major mode at a time.
35
36   The least specialized major mode is called @dfn{Fundamental mode}.
37 This mode has no mode-specific definitions or variable settings, so each
38 XEmacs command behaves in its default manner, and each option is in its
39 default state.  All other major modes redefine various keys and options.
40 For example, Lisp Interaction mode provides special key bindings for
41 @key{LFD} (@code{eval-print-last-sexp}), @key{TAB}
42 (@code{lisp-indent-line}), and other keys.
43
44   When you need to write several editing commands to help you perform a
45 specialized editing task, creating a new major mode is usually a good
46 idea.  In practice, writing a major mode is easy (in contrast to
47 writing a minor mode, which is often difficult).
48
49   If the new mode is similar to an old one, it is often unwise to modify
50 the old one to serve two purposes, since it may become harder to use and
51 maintain.  Instead, copy and rename an existing major mode definition
52 and alter the copy---or define a @dfn{derived mode} (@pxref{Derived
53 Modes}).  For example, Rmail Edit mode, which is in
54 @file{emacs/lisp/rmailedit.el}, is a major mode that is very similar to
55 Text mode except that it provides three additional commands.  Its
56 definition is distinct from that of Text mode, but was derived from it.
57
58   Rmail Edit mode is an example of a case where one piece of text is put
59 temporarily into a different major mode so it can be edited in a
60 different way (with ordinary XEmacs commands rather than Rmail).  In such
61 cases, the temporary major mode usually has a command to switch back to
62 the buffer's usual mode (Rmail mode, in this case).  You might be
63 tempted to present the temporary redefinitions inside a recursive edit
64 and restore the usual ones when the user exits; but this is a bad idea
65 because it constrains the user's options when it is done in more than
66 one buffer: recursive edits must be exited most-recently-entered first.
67 Using alternative major modes avoids this limitation.  @xref{Recursive
68 Editing}.
69
70   The standard XEmacs Lisp library directory contains the code for
71 several major modes, in files including @file{text-mode.el},
72 @file{texinfo.el}, @file{lisp-mode.el}, @file{c-mode.el}, and
73 @file{rmail.el}.  You can look at these libraries to see how modes are
74 written.  Text mode is perhaps the simplest major mode aside from
75 Fundamental mode.  Rmail mode is a complicated and specialized mode.
76
77 @menu
78 * Major Mode Conventions::  Coding conventions for keymaps, etc.
79 * Example Major Modes::     Text mode and Lisp modes.
80 * Auto Major Mode::         How XEmacs chooses the major mode automatically.
81 * Mode Help::               Finding out how to use a mode.
82 * Derived Modes::           Defining a new major mode based on another major
83                               mode.
84 @end menu
85
86 @node Major Mode Conventions
87 @subsection Major Mode Conventions
88
89   The code for existing major modes follows various coding conventions,
90 including conventions for local keymap and syntax table initialization,
91 global names, and hooks.  Please follow these conventions when you
92 define a new major mode:
93
94 @itemize @bullet
95 @item
96 Define a command whose name ends in @samp{-mode}, with no arguments,
97 that switches to the new mode in the current buffer.  This command
98 should set up the keymap, syntax table, and local variables in an
99 existing buffer without changing the buffer's text.
100
101 @item
102 Write a documentation string for this command that describes the
103 special commands available in this mode.  @kbd{C-h m}
104 (@code{describe-mode}) in your mode will display this string.
105
106 The documentation string may include the special documentation
107 substrings, @samp{\[@var{command}]}, @samp{\@{@var{keymap}@}}, and
108 @samp{\<@var{keymap}>}, that enable the documentation to adapt
109 automatically to the user's own key bindings.  @xref{Keys in
110 Documentation}.
111
112 @item
113 The major mode command should start by calling
114 @code{kill-all-local-variables}.  This is what gets rid of the local
115 variables of the major mode previously in effect.
116
117 @item
118 The major mode command should set the variable @code{major-mode} to the
119 major mode command symbol.  This is how @code{describe-mode} discovers
120 which documentation to print.
121
122 @item
123 The major mode command should set the variable @code{mode-name} to the
124 ``pretty'' name of the mode, as a string.  This appears in the mode
125 line.
126
127 @item
128 @cindex functions in modes
129 Since all global names are in the same name space, all the global
130 variables, constants, and functions that are part of the mode should
131 have names that start with the major mode name (or with an abbreviation
132 of it if the name is long).  @xref{Style Tips}.
133
134 @item
135 @cindex keymaps in modes
136 The major mode should usually have its own keymap, which is used as the
137 local keymap in all buffers in that mode.  The major mode function
138 should call @code{use-local-map} to install this local map.
139 @xref{Active Keymaps}, for more information.
140
141 This keymap should be kept in a global variable named
142 @code{@var{modename}-mode-map}.  Normally the library that defines the
143 mode sets this variable.
144
145 @item
146 @cindex syntax tables in modes
147 The mode may have its own syntax table or may share one with other
148 related modes.  If it has its own syntax table, it should store this in
149 a variable named @code{@var{modename}-mode-syntax-table}.  @xref{Syntax
150 Tables}.
151
152 @item
153 @cindex abbrev tables in modes
154 The mode may have its own abbrev table or may share one with other
155 related modes.  If it has its own abbrev table, it should store this in
156 a variable named @code{@var{modename}-mode-abbrev-table}.  @xref{Abbrev
157 Tables}.
158
159 @item
160 Use @code{defvar} to set mode-related variables, so that they are not
161 reinitialized if they already have a value.  (Such reinitialization
162 could discard customizations made by the user.)
163
164 @item
165 @cindex buffer-local variables in modes
166 To make a buffer-local binding for an Emacs customization variable, use
167 @code{make-local-variable} in the major mode command, not
168 @code{make-variable-buffer-local}.  The latter function would make the
169 variable local to every buffer in which it is subsequently set, which
170 would affect buffers that do not use this mode.  It is undesirable for a
171 mode to have such global effects.  @xref{Buffer-Local Variables}.
172
173 It's ok to use @code{make-variable-buffer-local}, if you wish, for a
174 variable used only within a single Lisp package.
175
176 @item
177 @cindex mode hook
178 @cindex major mode hook
179 Each major mode should have a @dfn{mode hook} named
180 @code{@var{modename}-mode-hook}.  The major mode command should run that
181 hook, with @code{run-hooks}, as the very last thing it
182 does. @xref{Hooks}.
183
184 @item
185 The major mode command may also run the hooks of some more basic modes.
186 For example, @code{indented-text-mode} runs @code{text-mode-hook} as
187 well as @code{indented-text-mode-hook}.  It may run these other hooks
188 immediately before the mode's own hook (that is, after everything else),
189 or it may run them earlier.
190
191 @item
192 If something special should be done if the user switches a buffer from
193 this mode to any other major mode, the mode can set a local value for
194 @code{change-major-mode-hook}.
195
196 @item
197 If this mode is appropriate only for specially-prepared text, then the
198 major mode command symbol should have a property named @code{mode-class}
199 with value @code{special}, put on as follows:
200
201 @cindex @code{mode-class} property
202 @cindex @code{special}
203 @example
204 (put 'funny-mode 'mode-class 'special)
205 @end example
206
207 @noindent
208 This tells XEmacs that new buffers created while the current buffer has
209 Funny mode should not inherit Funny mode.  Modes such as Dired, Rmail,
210 and Buffer List use this feature.
211
212 @item
213 If you want to make the new mode the default for files with certain
214 recognizable names, add an element to @code{auto-mode-alist} to select
215 the mode for those file names.  If you define the mode command to
216 autoload, you should add this element in the same file that calls
217 @code{autoload}.  Otherwise, it is sufficient to add the element in the
218 file that contains the mode definition.  @xref{Auto Major Mode}.
219
220 @item
221 @cindex @file{.emacs} customization
222 In the documentation, you should provide a sample @code{autoload} form
223 and an example of how to add to @code{auto-mode-alist}, that users can
224 include in their @file{.emacs} files.
225
226 @item
227 @cindex mode loading
228 The top-level forms in the file defining the mode should be written so
229 that they may be evaluated more than once without adverse consequences.
230 Even if you never load the file more than once, someone else will.
231 @end itemize
232
233 @defvar change-major-mode-hook
234 This normal hook is run by @code{kill-all-local-variables} before it
235 does anything else.  This gives major modes a way to arrange for
236 something special to be done if the user switches to a different major
237 mode.  For best results, make this variable buffer-local, so that it
238 will disappear after doing its job and will not interfere with the
239 subsequent major mode.  @xref{Hooks}.
240 @end defvar
241
242 @node Example Major Modes
243 @subsection Major Mode Examples
244
245   Text mode is perhaps the simplest mode besides Fundamental mode.
246 Here are excerpts from  @file{text-mode.el} that illustrate many of
247 the conventions listed above:
248
249 @smallexample
250 @group
251 ;; @r{Create mode-specific tables.}
252 (defvar text-mode-syntax-table nil
253   "Syntax table used while in text mode.")
254 @end group
255
256 @group
257 (if text-mode-syntax-table
258     ()              ; @r{Do not change the table if it is already set up.}
259   (setq text-mode-syntax-table (make-syntax-table))
260   (modify-syntax-entry ?\" ".   " text-mode-syntax-table)
261   (modify-syntax-entry ?\\ ".   " text-mode-syntax-table)
262   (modify-syntax-entry ?' "w   " text-mode-syntax-table))
263 @end group
264
265 @group
266 (defvar text-mode-abbrev-table nil
267   "Abbrev table used while in text mode.")
268 (define-abbrev-table 'text-mode-abbrev-table ())
269 @end group
270
271 @group
272 (defvar text-mode-map nil)   ; @r{Create a mode-specific keymap.}
273
274 (if text-mode-map
275     ()              ; @r{Do not change the keymap if it is already set up.}
276   (setq text-mode-map (make-sparse-keymap))
277   (define-key text-mode-map "\t" 'tab-to-tab-stop)
278   (define-key text-mode-map "\es" 'center-line)
279   (define-key text-mode-map "\eS" 'center-paragraph))
280 @end group
281 @end smallexample
282
283   Here is the complete major mode function definition for Text mode:
284
285 @smallexample
286 @group
287 (defun text-mode ()
288   "Major mode for editing text intended for humans to read.
289  Special commands: \\@{text-mode-map@}
290 @end group
291 @group
292 Turning on text-mode runs the hook `text-mode-hook'."
293   (interactive)
294   (kill-all-local-variables)
295 @end group
296 @group
297   (use-local-map text-mode-map)     ; @r{This provides the local keymap.}
298   (setq mode-name "Text")           ; @r{This name goes into the modeline.}
299   (setq major-mode 'text-mode)      ; @r{This is how @code{describe-mode}}
300                                     ;   @r{finds the doc string to print.}
301   (setq local-abbrev-table text-mode-abbrev-table)
302   (set-syntax-table text-mode-syntax-table)
303   (run-hooks 'text-mode-hook))      ; @r{Finally, this permits the user to}
304                                     ;   @r{customize the mode with a hook.}
305 @end group
306 @end smallexample
307
308 @cindex @file{lisp-mode.el}
309   The three Lisp modes (Lisp mode, Emacs Lisp mode, and Lisp
310 Interaction mode) have more features than Text mode and the code is
311 correspondingly more complicated.  Here are excerpts from
312 @file{lisp-mode.el} that illustrate how these modes are written.
313
314 @cindex syntax table example
315 @smallexample
316 @group
317 ;; @r{Create mode-specific table variables.}
318 (defvar lisp-mode-syntax-table nil "")
319 (defvar emacs-lisp-mode-syntax-table nil "")
320 (defvar lisp-mode-abbrev-table nil "")
321 @end group
322
323 @group
324 (if (not emacs-lisp-mode-syntax-table) ; @r{Do not change the table}
325                                        ;   @r{if it is already set.}
326     (let ((i 0))
327       (setq emacs-lisp-mode-syntax-table (make-syntax-table))
328 @end group
329
330 @group
331       ;; @r{Set syntax of chars up to 0 to class of chars that are}
332       ;;   @r{part of symbol names but not words.}
333       ;;   @r{(The number 0 is @code{48} in the @sc{ascii} character set.)}
334       (while (< i ?0)
335         (modify-syntax-entry i "_   " emacs-lisp-mode-syntax-table)
336         (setq i (1+ i)))
337       @dots{}
338 @end group
339 @group
340       ;; @r{Set the syntax for other characters.}
341       (modify-syntax-entry ?  "    " emacs-lisp-mode-syntax-table)
342       (modify-syntax-entry ?\t "    " emacs-lisp-mode-syntax-table)
343       @dots{}
344 @end group
345 @group
346       (modify-syntax-entry ?\( "()  " emacs-lisp-mode-syntax-table)
347       (modify-syntax-entry ?\) ")(  " emacs-lisp-mode-syntax-table)
348       @dots{}))
349 ;; @r{Create an abbrev table for lisp-mode.}
350 (define-abbrev-table 'lisp-mode-abbrev-table ())
351 @end group
352 @end smallexample
353
354   Much code is shared among the three Lisp modes.  The following
355 function sets various variables; it is called by each of the major Lisp
356 mode functions:
357
358 @smallexample
359 @group
360 (defun lisp-mode-variables (lisp-syntax)
361   ;; @r{The @code{lisp-syntax} argument is @code{nil} in Emacs Lisp mode,}
362   ;;   @r{and @code{t} in the other two Lisp modes.}
363   (cond (lisp-syntax
364          (if (not lisp-mode-syntax-table)
365              ;; @r{The Emacs Lisp mode syntax table always exists, but}
366              ;;   @r{the Lisp Mode syntax table is created the first time a}
367              ;;   @r{mode that needs it is called.  This is to save space.}
368 @end group
369 @group
370              (progn (setq lisp-mode-syntax-table
371                        (copy-syntax-table emacs-lisp-mode-syntax-table))
372                     ;; @r{Change some entries for Lisp mode.}
373                     (modify-syntax-entry ?\| "\"   "
374                                          lisp-mode-syntax-table)
375                     (modify-syntax-entry ?\[ "_   "
376                                          lisp-mode-syntax-table)
377                     (modify-syntax-entry ?\] "_   "
378                                          lisp-mode-syntax-table)))
379 @end group
380 @group
381           (set-syntax-table lisp-mode-syntax-table)))
382   (setq local-abbrev-table lisp-mode-abbrev-table)
383   @dots{})
384 @end group
385 @end smallexample
386
387   Functions such as @code{forward-paragraph} use the value of the
388 @code{paragraph-start} variable.  Since Lisp code is different from
389 ordinary text, the @code{paragraph-start} variable needs to be set
390 specially to handle Lisp.  Also, comments are indented in a special
391 fashion in Lisp and the Lisp modes need their own mode-specific
392 @code{comment-indent-function}.  The code to set these variables is the
393 rest of @code{lisp-mode-variables}.
394
395 @smallexample
396 @group
397   (make-local-variable 'paragraph-start)
398   ;; @r{Having @samp{^} is not clean, but @code{page-delimiter}}
399   ;; @r{has them too, and removing those is a pain.}
400   (setq paragraph-start (concat "^$\\|" page-delimiter))
401   @dots{}
402 @end group
403 @group
404   (make-local-variable 'comment-indent-function)
405   (setq comment-indent-function 'lisp-comment-indent))
406 @end group
407 @end smallexample
408
409   Each of the different Lisp modes has a slightly different keymap.  For
410 example, Lisp mode binds @kbd{C-c C-l} to @code{run-lisp}, but the other
411 Lisp modes do not.  However, all Lisp modes have some commands in
412 common.  The following function adds these common commands to a given
413 keymap.
414
415 @smallexample
416 @group
417 (defun lisp-mode-commands (map)
418   (define-key map "\e\C-q" 'indent-sexp)
419   (define-key map "\177" 'backward-delete-char-untabify)
420   (define-key map "\t" 'lisp-indent-line))
421 @end group
422 @end smallexample
423
424   Here is an example of using @code{lisp-mode-commands} to initialize a
425 keymap, as part of the code for Emacs Lisp mode.  First we declare a
426 variable with @code{defvar} to hold the mode-specific keymap.  When this
427 @code{defvar} executes, it sets the variable to @code{nil} if it was
428 void.  Then we set up the keymap if the variable is @code{nil}.
429
430   This code avoids changing the keymap or the variable if it is already
431 set up.  This lets the user customize the keymap.
432
433 @smallexample
434 @group
435 (defvar emacs-lisp-mode-map () "")
436 (if emacs-lisp-mode-map
437     ()
438   (setq emacs-lisp-mode-map (make-sparse-keymap))
439   (define-key emacs-lisp-mode-map "\e\C-x" 'eval-defun)
440   (lisp-mode-commands emacs-lisp-mode-map))
441 @end group
442 @end smallexample
443
444   Finally, here is the complete major mode function definition for
445 Emacs Lisp mode.
446
447 @smallexample
448 @group
449 (defun emacs-lisp-mode ()
450   "Major mode for editing Lisp code to run in XEmacs.
451 Commands:
452 Delete converts tabs to spaces as it moves back.
453 Blank lines separate paragraphs.  Semicolons start comments.
454 \\@{emacs-lisp-mode-map@}
455 @end group
456 @group
457 Entry to this mode runs the hook `emacs-lisp-mode-hook'."
458   (interactive)
459   (kill-all-local-variables)
460   (use-local-map emacs-lisp-mode-map)    ; @r{This provides the local keymap.}
461   (set-syntax-table emacs-lisp-mode-syntax-table)
462 @end group
463 @group
464   (setq major-mode 'emacs-lisp-mode)     ; @r{This is how @code{describe-mode}}
465                                          ;   @r{finds out what to describe.}
466   (setq mode-name "Emacs-Lisp")          ; @r{This goes into the modeline.}
467   (lisp-mode-variables nil)              ; @r{This defines various variables.}
468   (run-hooks 'emacs-lisp-mode-hook))     ; @r{This permits the user to use a}
469                                          ;   @r{hook to customize the mode.}
470 @end group
471 @end smallexample
472
473 @node Auto Major Mode
474 @subsection How XEmacs Chooses a Major Mode
475
476   Based on information in the file name or in the file itself, XEmacs
477 automatically selects a major mode for the new buffer when a file is
478 visited.
479
480 @deffn Command fundamental-mode
481   Fundamental mode is a major mode that is not specialized for anything
482 in particular.  Other major modes are defined in effect by comparison
483 with this one---their definitions say what to change, starting from
484 Fundamental mode.  The @code{fundamental-mode} function does @emph{not}
485 run any hooks; you're not supposed to customize it.  (If you want Emacs
486 to behave differently in Fundamental mode, change the @emph{global}
487 state of Emacs.)
488 @end deffn
489
490 @deffn Command normal-mode &optional find-file
491 This function establishes the proper major mode and local variable
492 bindings for the current buffer.  First it calls @code{set-auto-mode},
493 then it runs @code{hack-local-variables} to parse, and bind or
494 evaluate as appropriate, any local variables.
495
496 If the @var{find-file} argument to @code{normal-mode} is
497 non-@code{nil}, @code{normal-mode} assumes that the @code{find-file}
498 function is calling it.  In this case, it may process a local variables
499 list at the end of the file and in the @samp{-*-} line.  The variable
500 @code{enable-local-variables} controls whether to do so.
501
502 If you run @code{normal-mode} interactively, the argument
503 @var{find-file} is normally @code{nil}.  In this case,
504 @code{normal-mode} unconditionally processes any local variables list.
505 @xref{File variables, , Local Variables in Files, xemacs, The XEmacs
506 Reference Manual}, for the syntax of the local variables section of a file.
507
508 @cindex file mode specification error
509 @code{normal-mode} uses @code{condition-case} around the call to the
510 major mode function, so errors are caught and reported as a @samp{File
511 mode specification error},  followed by the original error message.
512 @end deffn
513
514 @defopt enable-local-variables
515 This variable controls processing of local variables lists in files
516 being visited.  A value of @code{t} means process the local variables
517 lists unconditionally; @code{nil} means ignore them; anything else means
518 ask the user what to do for each file.  The default value is @code{t}.
519 @end defopt
520
521 @defvar ignored-local-variables
522 This variable holds a list of variables that should not be
523 set by a local variables list.  Any value specified
524 for one of these variables is ignored.
525 @end defvar
526
527 In addition to this list, any variable whose name has a non-@code{nil}
528 @code{risky-local-variable} property is also ignored.
529
530 @defopt enable-local-eval
531 This variable controls processing of @samp{Eval:} in local variables
532 lists in files being visited.  A value of @code{t} means process them
533 unconditionally; @code{nil} means ignore them; anything else means ask
534 the user what to do for each file.  The default value is @code{maybe}.
535 @end defopt
536
537 @defun set-auto-mode
538 @cindex visited file mode
539   This function selects the major mode that is appropriate for the
540 current buffer.  It may base its decision on the value of the @w{@samp{-*-}}
541 line, on the visited file name (using @code{auto-mode-alist}), or on the
542 value of a local variable.  However, this function does not look for
543 the @samp{mode:} local variable near the end of a file; the
544 @code{hack-local-variables} function does that.  @xref{Choosing Modes, ,
545 How Major Modes are Chosen, xemacs, The XEmacs Lisp Reference Manual}.
546 @end defun
547
548 @defopt default-major-mode
549   This variable holds the default major mode for new buffers.  The
550 standard value is @code{fundamental-mode}.
551
552   If the value of @code{default-major-mode} is @code{nil}, XEmacs uses
553 the (previously) current buffer's major mode for the major mode of a new
554 buffer.  However, if the major mode symbol has a @code{mode-class}
555 property with value @code{special}, then it is not used for new buffers;
556 Fundamental mode is used instead.  The modes that have this property are
557 those such as Dired and Rmail that are useful only with text that has
558 been specially prepared.
559 @end defopt
560
561 @defun set-buffer-major-mode buffer
562 This function sets the major mode of @var{buffer} to the value of
563 @code{default-major-mode}.  If that variable is @code{nil}, it uses
564 the current buffer's major mode (if that is suitable).
565
566 The low-level primitives for creating buffers do not use this function,
567 but medium-level commands such as @code{switch-to-buffer} and
568 @code{find-file-noselect} use it whenever they create buffers.
569 @end defun
570
571 @defvar initial-major-mode
572 @cindex @samp{*scratch*}
573 The value of this variable determines the major mode of the initial
574 @samp{*scratch*} buffer.  The value should be a symbol that is a major
575 mode command name.  The default value is @code{lisp-interaction-mode}.
576 @end defvar
577
578 @defvar auto-mode-alist
579 This variable contains an association list of file name patterns
580 (regular expressions; @pxref{Regular Expressions}) and corresponding
581 major mode functions.  Usually, the file name patterns test for
582 suffixes, such as @samp{.el} and @samp{.c}, but this need not be the
583 case.  An ordinary element of the alist looks like @code{(@var{regexp} .
584 @var{mode-function})}.
585
586 For example,
587
588 @smallexample
589 @group
590 (("^/tmp/fol/" . text-mode)
591  ("\\.texinfo\\'" . texinfo-mode)
592  ("\\.texi\\'" . texinfo-mode)
593 @end group
594 @group
595  ("\\.el\\'" . emacs-lisp-mode)
596  ("\\.c\\'" . c-mode)
597  ("\\.h\\'" . c-mode)
598  @dots{})
599 @end group
600 @end smallexample
601
602 When you visit a file whose expanded file name (@pxref{File Name
603 Expansion}) matches a @var{regexp}, @code{set-auto-mode} calls the
604 corresponding @var{mode-function}.  This feature enables XEmacs to select
605 the proper major mode for most files.
606
607 If an element of @code{auto-mode-alist} has the form @code{(@var{regexp}
608 @var{function} t)}, then after calling @var{function}, XEmacs searches
609 @code{auto-mode-alist} again for a match against the portion of the file
610 name that did not match before.
611
612 This match-again feature is useful for uncompression packages: an entry
613 of the form @code{("\\.gz\\'" . @var{function})} can uncompress the file
614 and then put the uncompressed file in the proper mode according to the
615 name sans @samp{.gz}.
616
617 Here is an example of how to prepend several pattern pairs to
618 @code{auto-mode-alist}.  (You might use this sort of expression in your
619 @file{.emacs} file.)
620
621 @smallexample
622 @group
623 (setq auto-mode-alist
624   (append
625    ;; @r{File name starts with a dot.}
626    '(("/\\.[^/]*\\'" . fundamental-mode)
627      ;; @r{File name has no dot.}
628      ("[^\\./]*\\'" . fundamental-mode)
629      ;; @r{File name ends in @samp{.C}.}
630      ("\\.C\\'" . c++-mode))
631    auto-mode-alist))
632 @end group
633 @end smallexample
634 @end defvar
635
636 @defvar interpreter-mode-alist
637 This variable specifies major modes to use for scripts that specify a
638 command interpreter in an @samp{#!} line.  Its value is a list of
639 elements of the form @code{(@var{interpreter} . @var{mode})}; for
640 example, @code{("perl" . perl-mode)} is one element present by default.
641 The element says to use mode @var{mode} if the file specifies
642 @var{interpreter}.
643
644 This variable is applicable only when the @code{auto-mode-alist} does
645 not indicate which major mode to use.
646 @end defvar
647
648 @defun hack-local-variables &optional force
649   This function parses, and binds or evaluates as appropriate, any local
650 variables for the current buffer.
651
652   The handling of @code{enable-local-variables} documented for
653 @code{normal-mode} actually takes place here.  The argument @var{force}
654 usually comes from the argument @var{find-file} given to
655 @code{normal-mode}.
656 @end defun
657
658 @node Mode Help
659 @subsection Getting Help about a Major Mode
660 @cindex mode help
661 @cindex help for major mode
662 @cindex documentation for major mode
663
664   The @code{describe-mode} function is used to provide information
665 about major modes.  It is normally called with @kbd{C-h m}.  The
666 @code{describe-mode} function uses the value of @code{major-mode},
667 which is why every major mode function needs to set the
668 @code{major-mode} variable.
669
670 @deffn Command describe-mode
671 This function displays the documentation of the current major mode.
672
673 The @code{describe-mode} function calls the @code{documentation}
674 function using the value of @code{major-mode} as an argument.  Thus, it
675 displays the documentation string of the major mode function.
676 (@xref{Accessing Documentation}.)
677 @end deffn
678
679 @defvar major-mode
680 This variable holds the symbol for the current buffer's major mode.
681 This symbol should have a function definition that is the command to
682 switch to that major mode.  The @code{describe-mode} function uses the
683 documentation string of the function as the documentation of the major
684 mode.
685 @end defvar
686
687 @node Derived Modes
688 @subsection Defining Derived Modes
689
690   It's often useful to define a new major mode in terms of an existing
691 one.  An easy way to do this is to use @code{define-derived-mode}.
692
693 @defmac define-derived-mode variant parent name docstring body@dots{}
694 This construct defines @var{variant} as a major mode command, using
695 @var{name} as the string form of the mode name.
696
697 The new command @var{variant} is defined to call the function
698 @var{parent}, then override certain aspects of that parent mode:
699
700 @itemize @bullet
701 @item
702 The new mode has its own keymap, named @code{@var{variant}-map}.
703 @code{define-derived-mode} initializes this map to inherit from
704 @code{@var{parent}-map}, if it is not already set.
705
706 @item
707 The new mode has its own syntax table, kept in the variable
708 @code{@var{variant}-syntax-table}.
709 @code{define-derived-mode} initializes this variable by copying
710 @code{@var{parent}-syntax-table}, if it is not already set.
711
712 @item
713 The new mode has its own abbrev table, kept in the variable
714 @code{@var{variant}-abbrev-table}.
715 @code{define-derived-mode} initializes this variable by copying
716 @code{@var{parent}-abbrev-table}, if it is not already set.
717
718 @item
719 The new mode has its own mode hook, @code{@var{variant}-hook},
720 which it runs in standard fashion as the very last thing that it does.
721 (The new mode also runs the mode hook of @var{parent} as part
722 of calling @var{parent}.)
723 @end itemize
724
725 In addition, you can specify how to override other aspects of
726 @var{parent} with @var{body}.  The command @var{variant}
727 evaluates the forms in @var{body} after setting up all its usual
728 overrides, just before running @code{@var{variant}-hook}.
729
730 The argument @var{docstring} specifies the documentation string for the
731 new mode.  If you omit @var{docstring}, @code{define-derived-mode}
732 generates a documentation string.
733
734 Here is a hypothetical example:
735
736 @example
737 (define-derived-mode hypertext-mode
738   text-mode "Hypertext"
739   "Major mode for hypertext.
740 \\@{hypertext-mode-map@}"
741   (setq case-fold-search nil))
742
743 (define-key hypertext-mode-map
744   [down-mouse-3] 'do-hyper-link)
745 @end example
746 @end defmac
747
748 @node Minor Modes
749 @section Minor Modes
750 @cindex minor mode
751
752   A @dfn{minor mode} provides features that users may enable or disable
753 independently of the choice of major mode.  Minor modes can be enabled
754 individually or in combination.  Minor modes would be better named
755 ``Generally available, optional feature modes'' except that such a name is
756 unwieldy.
757
758   A minor mode is not usually a modification of single major mode.  For
759 example, Auto Fill mode may be used in any major mode that permits text
760 insertion.  To be general, a minor mode must be effectively independent
761 of the things major modes do.
762
763   A minor mode is often much more difficult to implement than a major
764 mode.  One reason is that you should be able to activate and deactivate
765 minor modes in any order.  A minor mode should be able to have its
766 desired effect regardless of the major mode and regardless of the other
767 minor modes in effect.
768
769   Often the biggest problem in implementing a minor mode is finding a
770 way to insert the necessary hook into the rest of XEmacs.  Minor mode
771 keymaps make this easier than it used to be.
772
773 @menu
774 * Minor Mode Conventions::      Tips for writing a minor mode.
775 * Keymaps and Minor Modes::     How a minor mode can have its own keymap.
776 @end menu
777
778 @node Minor Mode Conventions
779 @subsection Conventions for Writing Minor Modes
780 @cindex minor mode conventions
781 @cindex conventions for writing minor modes
782
783   There are conventions for writing minor modes just as there are for
784 major modes.  Several of the major mode conventions apply to minor
785 modes as well: those regarding the name of the mode initialization
786 function, the names of global symbols, and the use of keymaps and
787 other tables.
788
789   In addition, there are several conventions that are specific to
790 minor modes.
791
792 @itemize @bullet
793 @item
794 @cindex mode variable
795 Make a variable whose name ends in @samp{-mode} to represent the minor
796 mode.  Its value should enable or disable the mode (@code{nil} to
797 disable; anything else to enable.)  We call this the @dfn{mode
798 variable}.
799
800 This variable is used in conjunction with the @code{minor-mode-alist} to
801 display the minor mode name in the modeline.  It can also enable
802 or disable a minor mode keymap.  Individual commands or hooks can also
803 check the variable's value.
804
805 If you want the minor mode to be enabled separately in each buffer,
806 make the variable buffer-local.
807
808 @item
809 Define a command whose name is the same as the mode variable.
810 Its job is to enable and disable the mode by setting the variable.
811
812 The command should accept one optional argument.  If the argument is
813 @code{nil}, it should toggle the mode (turn it on if it is off, and off
814 if it is on).  Otherwise, it should turn the mode on if the argument is
815 a positive integer, a symbol other than @code{nil} or @code{-}, or a
816 list whose @sc{car} is such an integer or symbol; it should turn the
817 mode off otherwise.
818
819 Here is an example taken from the definition of @code{transient-mark-mode}.
820 It shows the use of @code{transient-mark-mode} as a variable that enables or
821 disables the mode's behavior, and also shows the proper way to toggle,
822 enable or disable the minor mode based on the raw prefix argument value.
823
824 @smallexample
825 @group
826 (setq transient-mark-mode
827       (if (null arg) (not transient-mark-mode)
828         (> (prefix-numeric-value arg) 0)))
829 @end group
830 @end smallexample
831
832 @item
833 Add an element to @code{minor-mode-alist} for each minor mode
834 (@pxref{Modeline Variables}).  This element should be a list of the
835 following form:
836
837 @smallexample
838 (@var{mode-variable} @var{string})
839 @end smallexample
840
841 Here @var{mode-variable} is the variable that controls enabling of the
842 minor mode, and @var{string} is a short string, starting with a space,
843 to represent the mode in the modeline.  These strings must be short so
844 that there is room for several of them at once.
845
846 When you add an element to @code{minor-mode-alist}, use @code{assq} to
847 check for an existing element, to avoid duplication.  For example:
848
849 @smallexample
850 @group
851 (or (assq 'leif-mode minor-mode-alist)
852     (setq minor-mode-alist
853           (cons '(leif-mode " Leif") minor-mode-alist)))
854 @end group
855 @end smallexample
856 @end itemize
857
858 @node Keymaps and Minor Modes
859 @subsection Keymaps and Minor Modes
860
861   Each minor mode can have its own keymap, which is active when the mode
862 is enabled.  To set up a keymap for a minor mode, add an element to the
863 alist @code{minor-mode-map-alist}.  @xref{Active Keymaps}.
864
865 @cindex @code{self-insert-command}, minor modes
866 One use of minor mode keymaps is to modify the behavior of certain
867 self-inserting characters so that they do something else as well as
868 self-insert.  In general, this is the only way to do that, since the
869 facilities for customizing @code{self-insert-command} are limited to
870 special cases (designed for abbrevs and Auto Fill mode).  (Do not try
871 substituting your own definition of @code{self-insert-command} for the
872 standard one.  The editor command loop handles this function specially.)
873
874 @node Modeline Format
875 @section Modeline Format
876 @cindex modeline
877
878   Each Emacs window (aside from minibuffer windows) includes a modeline,
879 which displays status information about the buffer displayed in the
880 window.  The modeline contains information about the buffer, such as its
881 name, associated file, depth of recursive editing, and the major and
882 minor modes.
883
884   This section describes how the contents of the modeline are
885 controlled.  It is in the chapter on modes because much of the
886 information displayed in the modeline relates to the enabled major and
887 minor modes.
888
889   @code{modeline-format} is a buffer-local variable that holds a
890 template used to display the modeline of the current buffer.  All
891 windows for the same buffer use the same @code{modeline-format} and
892 their modelines appear the same (except for scrolling percentages and
893 line numbers).
894
895   The modeline of a window is normally updated whenever a different
896 buffer is shown in the window, or when the buffer's modified-status
897 changes from @code{nil} to @code{t} or vice-versa.  If you modify any of
898 the variables referenced by @code{modeline-format} (@pxref{Modeline
899 Variables}), you may want to force an update of the modeline so as to
900 display the new information.
901
902 @c Emacs 19 feature
903 @defun redraw-modeline &optional all
904 Force redisplay of the current buffer's modeline.  If @var{all} is
905 non-@code{nil}, then force redisplay of all modelines.
906 @end defun
907
908   The modeline is usually displayed in inverse video.  This
909 is controlled using the @code{modeline} face.  @xref{Faces}.
910
911 @menu
912 * Modeline Data::         The data structure that controls the modeline.
913 * Modeline Variables::    Variables used in that data structure.
914 * %-Constructs::          Putting information into a modeline.
915 @end menu
916
917 @node Modeline Data
918 @subsection The Data Structure of the Modeline
919 @cindex modeline construct
920
921   The modeline contents are controlled by a data structure of lists,
922 strings, symbols, and numbers kept in the buffer-local variable
923 @code{modeline-format}.  The data structure is called a @dfn{modeline
924 construct}, and it is built in recursive fashion out of simpler modeline
925 constructs.  The same data structure is used for constructing
926 frame titles (@pxref{Frame Titles}).
927
928 @defvar modeline-format
929 The value of this variable is a modeline construct with overall
930 responsibility for the modeline format.  The value of this variable
931 controls which other variables are used to form the modeline text, and
932 where they appear.
933 @end defvar
934
935   A modeline construct may be as simple as a fixed string of text, but
936 it usually specifies how to use other variables to construct the text.
937 Many of these variables are themselves defined to have modeline
938 constructs as their values.
939
940   The default value of @code{modeline-format} incorporates the values
941 of variables such as @code{mode-name} and @code{minor-mode-alist}.
942 Because of this, very few modes need to alter @code{modeline-format}.
943 For most purposes, it is sufficient to alter the variables referenced by
944 @code{modeline-format}.
945
946   A modeline construct may be a string, symbol, glyph, generic
947 specifier, list or cons cell.
948
949 @table @code
950 @cindex percent symbol in modeline
951 @item @var{string}
952 A string as a modeline construct is displayed verbatim in the mode line
953 except for @dfn{@code{%}-constructs}.  Decimal digits after the @samp{%}
954 specify the field width for space filling on the right (i.e., the data
955 is left justified).  @xref{%-Constructs}.
956
957 @item @var{symbol}
958 A symbol as a modeline construct stands for its value.  The value of
959 @var{symbol} is processed as a modeline construct, in place of
960 @var{symbol}.  However, the symbols @code{t} and @code{nil} are ignored;
961 so is any symbol whose value is void.
962
963 There is one exception: if the value of @var{symbol} is a string, it is
964 displayed verbatim: the @code{%}-constructs are not recognized.
965
966 @item @var{glyph}
967 A glyph is displayed as is.
968
969 @item @var{generic-specifier}
970 A @var{generic-specifier} (i.e. a specifier of type @code{generic})
971 stands for its instance.  The instance of @var{generic-specifier} is
972 computed in the current window using the equivalent of
973 @code{specifier-instance} and the value is processed.
974
975 @item (@var{string} @var{rest}@dots{}) @r{or} (@var{list} @var{rest}@dots{})
976 A list whose first element is a string or list means to process all the
977 elements recursively and concatenate the results.  This is the most
978 common form of mode line construct.
979
980 @item (@var{symbol} @var{then} @var{else})
981 A list whose first element is a symbol is a conditional.  Its meaning
982 depends on the value of @var{symbol}.  If the value is non-@code{nil},
983 the second element, @var{then}, is processed recursively as a modeline
984 element.  But if the value of @var{symbol} is @code{nil}, the third
985 element, @var{else}, is processed recursively.  You may omit @var{else};
986 then the mode line element displays nothing if the value of @var{symbol}
987 is @code{nil}.
988
989 @item (@var{width} @var{rest}@dots{})
990 A list whose first element is an integer specifies truncation or
991 padding of the results of @var{rest}.  The remaining elements
992 @var{rest} are processed recursively as modeline constructs and
993 concatenated together.  Then the result is space filled (if
994 @var{width} is positive) or truncated (to @minus{}@var{width} columns,
995 if @var{width} is negative) on the right.
996
997 For example, the usual way to show what percentage of a buffer is above
998 the top of the window is to use a list like this: @code{(-3 "%p")}.
999
1000 @item (@var{extent} @var{rest}@dots{})
1001
1002 A list whose car is an extent means the cdr of the list is processed
1003 normally but the results are displayed using the face of the extent, and
1004 mouse clicks over this section are processed using the keymap of the
1005 extent. (In addition, if the extent has a help-echo property, that
1006 string will be echoed when the mouse moves over this section.) If
1007 extents are nested, all keymaps are properly consulted when processing
1008 mouse clicks, but multiple faces are not correctly merged (only the
1009 first face is used), and lists of faces are not correctly handled.
1010 @c #### Document generate-modeline-string.
1011 @c See `generated-modeline-string' for more information.
1012 @end table
1013
1014   If you do alter @code{modeline-format} itself, the new value should
1015 use the same variables that appear in the default value (@pxref{Modeline
1016 Variables}), rather than duplicating their contents or displaying
1017 the information in another fashion.  This way, customizations made by
1018 the user or by Lisp programs (such as @code{display-time} and major
1019 modes) via changes to those variables remain effective.
1020
1021 @cindex Shell mode @code{modeline-format}
1022   Here is an example of a @code{modeline-format} that might be
1023 useful for @code{shell-mode}, since it contains the hostname and default
1024 directory.
1025
1026 @example
1027 @group
1028 (setq modeline-format
1029   (list ""
1030    'modeline-modified
1031    "%b--"
1032 @end group
1033    (getenv "HOST")      ; @r{One element is not constant.}
1034    ":"
1035    'default-directory
1036    "   "
1037    'global-mode-string
1038    "   %[("
1039    'mode-name
1040    'modeline-process
1041    'minor-mode-alist
1042    "%n"
1043    ")%]----"
1044 @group
1045    '(line-number-mode "L%l--")
1046    '(-3 . "%p")
1047    "-%-"))
1048 @end group
1049 @end example
1050
1051 @node Modeline Variables
1052 @subsection Variables Used in the Modeline
1053
1054   This section describes variables incorporated by the
1055 standard value of @code{modeline-format} into the text of the mode
1056 line.  There is nothing inherently special about these variables; any
1057 other variables could have the same effects on the modeline if
1058 @code{modeline-format} were changed to use them.
1059
1060 @defvar modeline-modified
1061 This variable holds the value of the modeline construct that displays
1062 whether the current buffer is modified.
1063
1064 The default value of @code{modeline-modified} is @code{("--%1*%1+-")}.
1065 This means that the modeline displays @samp{--**-} if the buffer is
1066 modified, @samp{-----} if the buffer is not modified, @samp{--%%-} if
1067 the buffer is read only, and @samp{--%*--} if the buffer is read only
1068 and modified.
1069
1070 Changing this variable does not force an update of the modeline.
1071 @end defvar
1072
1073 @defvar modeline-buffer-identification
1074 This variable identifies the buffer being displayed in the window.  Its
1075 default value is @code{("%F: %17b")}, which means that it usually
1076 displays @samp{Emacs:} followed by seventeen characters of the buffer
1077 name.  (In a terminal frame, it displays the frame name instead of
1078 @samp{Emacs}; this has the effect of showing the frame number.)  You may
1079 want to change this in modes such as Rmail that do not behave like a
1080 ``normal'' XEmacs.
1081 @end defvar
1082
1083 @defvar global-mode-string
1084 This variable holds a modeline spec that appears in the mode line by
1085 default, just after the buffer name.  The command @code{display-time}
1086 sets @code{global-mode-string} to refer to the variable
1087 @code{display-time-string}, which holds a string containing the time and
1088 load information.
1089
1090 The @samp{%M} construct substitutes the value of
1091 @code{global-mode-string}, but this is obsolete, since the variable is
1092 included directly in the modeline.
1093 @end defvar
1094
1095 @defvar mode-name
1096 This buffer-local variable holds the ``pretty'' name of the current
1097 buffer's major mode.  Each major mode should set this variable so that the
1098 mode name will appear in the modeline.
1099 @end defvar
1100
1101 @defvar minor-mode-alist
1102 This variable holds an association list whose elements specify how the
1103 modeline should indicate that a minor mode is active.  Each element of
1104 the @code{minor-mode-alist} should be a two-element list:
1105
1106 @example
1107 (@var{minor-mode-variable} @var{modeline-string})
1108 @end example
1109
1110 More generally, @var{modeline-string} can be any mode line spec.  It
1111 appears in the mode line when the value of @var{minor-mode-variable} is
1112 non-@code{nil}, and not otherwise.  These strings should begin with
1113 spaces so that they don't run together.  Conventionally, the
1114 @var{minor-mode-variable} for a specific mode is set to a non-@code{nil}
1115 value when that minor mode is activated.
1116
1117 The default value of @code{minor-mode-alist} is:
1118
1119 @example
1120 @group
1121 minor-mode-alist
1122 @result{} ((vc-mode vc-mode)
1123     (abbrev-mode " Abbrev")
1124     (overwrite-mode overwrite-mode)
1125     (auto-fill-function " Fill")
1126     (defining-kbd-macro " Def")
1127     (isearch-mode isearch-mode))
1128 @end group
1129 @end example
1130
1131 @code{minor-mode-alist} is not buffer-local.  The variables mentioned
1132 in the alist should be buffer-local if the minor mode can be enabled
1133 separately in each buffer.
1134 @end defvar
1135
1136 @defvar modeline-process
1137 This buffer-local variable contains the modeline information on process
1138 status in modes used for communicating with subprocesses.  It is
1139 displayed immediately following the major mode name, with no intervening
1140 space.  For example, its value in the @samp{*shell*} buffer is
1141 @code{(":@: %s")}, which allows the shell to display its status along
1142 with the major mode as: @samp{(Shell:@: run)}.  Normally this variable
1143 is @code{nil}.
1144 @end defvar
1145
1146 @defvar default-modeline-format
1147 This variable holds the default @code{modeline-format} for buffers
1148 that do not override it.  This is the same as @code{(default-value
1149 'modeline-format)}.
1150
1151 The default value of @code{default-modeline-format} is:
1152
1153 @example
1154 @group
1155 (""
1156  modeline-modified
1157  modeline-buffer-identification
1158  "   "
1159  global-mode-string
1160  "   %[("
1161  mode-name
1162 @end group
1163 @group
1164  modeline-process
1165  minor-mode-alist
1166  "%n"
1167  ")%]----"
1168  (line-number-mode "L%l--")
1169  (-3 . "%p")
1170  "-%-")
1171 @end group
1172 @end example
1173 @end defvar
1174
1175 @defvar vc-mode
1176 The variable @code{vc-mode}, local in each buffer, records whether the
1177 buffer's visited file is maintained with version control, and, if so,
1178 which kind.  Its value is @code{nil} for no version control, or a string
1179 that appears in the mode line.
1180 @end defvar
1181
1182 @node %-Constructs
1183 @subsection @code{%}-Constructs in the ModeLine
1184
1185   The following table lists the recognized @code{%}-constructs and what
1186 they mean.  In any construct except @samp{%%}, you can add a decimal
1187 integer after the @samp{%} to specify how many characters to display.
1188
1189 @table @code
1190 @item %b
1191 The current buffer name, obtained with the @code{buffer-name} function.
1192 @xref{Buffer Names}.
1193
1194 @item %f
1195 The visited file name, obtained with the @code{buffer-file-name}
1196 function.  @xref{Buffer File Name}.
1197
1198 @item %F
1199 The name of the selected frame.
1200
1201 @item %c
1202 The current column number of point.
1203
1204 @item %l
1205 The current line number of point.
1206
1207 @item %*
1208 @samp{%} if the buffer is read only (see @code{buffer-read-only}); @*
1209 @samp{*} if the buffer is modified (see @code{buffer-modified-p}); @*
1210 @samp{-} otherwise.  @xref{Buffer Modification}.
1211
1212 @item %+
1213 @samp{*} if the buffer is modified (see @code{buffer-modified-p}); @*
1214 @samp{%} if the buffer is read only (see @code{buffer-read-only}); @*
1215 @samp{-} otherwise.  This differs from @samp{%*} only for a modified
1216 read-only buffer.  @xref{Buffer Modification}.
1217
1218 @item %&
1219 @samp{*} if the buffer is modified, and @samp{-} otherwise.
1220
1221 @item %s
1222 The status of the subprocess belonging to the current buffer, obtained with
1223 @code{process-status}.  @xref{Process Information}.
1224
1225 @c The following two may only apply in XEmacs.
1226 @item %l
1227 The current line number.
1228
1229 @item %S
1230 The name of the selected frame; this is only meaningful under the
1231 X Window System.  @xref{Frame Name}.
1232
1233 @item %t
1234 Whether the visited file is a text file or a binary file.  (This is a
1235 meaningful distinction only on certain operating systems.)
1236
1237 @item %p
1238 The percentage of the buffer text above the @strong{top} of window, or
1239 @samp{Top}, @samp{Bottom} or @samp{All}.
1240
1241 @item %P
1242 The percentage of the buffer text that is above the @strong{bottom} of
1243 the window (which includes the text visible in the window, as well as
1244 the text above the top), plus @samp{Top} if the top of the buffer is
1245 visible on screen; or @samp{Bottom} or @samp{All}.
1246
1247 @item %n
1248 @samp{Narrow} when narrowing is in effect; nothing otherwise (see
1249 @code{narrow-to-region} in @ref{Narrowing}).
1250
1251 @item %C
1252 Under XEmacs/mule, the mnemonic for @code{buffer-file-coding-system}.
1253
1254 @item %[
1255 An indication of the depth of recursive editing levels (not counting
1256 minibuffer levels): one @samp{[} for each editing level.
1257 @xref{Recursive Editing}.
1258
1259 @item %]
1260 One @samp{]} for each recursive editing level (not counting minibuffer
1261 levels).
1262
1263 @item %%
1264 The character @samp{%}---this is how to include a literal @samp{%} in a
1265 string in which @code{%}-constructs are allowed.
1266
1267 @item %-
1268 Dashes sufficient to fill the remainder of the modeline.
1269 @end table
1270
1271 The following two @code{%}-constructs are still supported, but they are
1272 obsolete, since you can get the same results with the variables
1273 @code{mode-name} and @code{global-mode-string}.
1274
1275 @table @code
1276 @item %m
1277 The value of @code{mode-name}.
1278
1279 @item %M
1280 The value of @code{global-mode-string}.  Currently, only
1281 @code{display-time} modifies the value of @code{global-mode-string}.
1282 @end table
1283
1284 @node Hooks
1285 @section Hooks
1286 @cindex hooks
1287
1288   A @dfn{hook} is a variable where you can store a function or functions
1289 to be called on a particular occasion by an existing program.  XEmacs
1290 provides hooks for the sake of customization.  Most often, hooks are set
1291 up in the @file{.emacs} file, but Lisp programs can set them also.
1292 @xref{Standard Hooks}, for a list of standard hook variables.
1293
1294   Most of the hooks in XEmacs are @dfn{normal hooks}.  These variables
1295 contain lists of functions to be called with no arguments.  The reason
1296 most hooks are normal hooks is so that you can use them in a uniform
1297 way.  You can usually tell when a hook is a normal hook, because its
1298 name ends in @samp{-hook}.
1299
1300   The recommended way to add a hook function to a normal hook is by
1301 calling @code{add-hook} (see below).  The hook functions may be any of
1302 the valid kinds of functions that @code{funcall} accepts (@pxref{What Is
1303 a Function}).  Most normal hook variables are initially void;
1304 @code{add-hook} knows how to deal with this.
1305
1306   As for abnormal hooks, those whose names end in @samp{-function} have
1307 a value that is a single function.  Those whose names end in
1308 @samp{-hooks} have a value that is a list of functions.  Any hook that
1309 is abnormal is abnormal because a normal hook won't do the job; either
1310 the functions are called with arguments, or their values are meaningful.
1311 The name shows you that the hook is abnormal and that you should look at
1312 its documentation string to see how to use it properly.
1313
1314   Major mode functions are supposed to run a hook called the @dfn{mode
1315 hook} as the last step of initialization.  This makes it easy for a user
1316 to customize the behavior of the mode, by overriding the local variable
1317 assignments already made by the mode.  But hooks are used in other
1318 contexts too.  For example, the hook @code{suspend-hook} runs just
1319 before XEmacs suspends itself (@pxref{Suspending XEmacs}).
1320
1321   Here's an expression that uses a mode hook to turn on Auto Fill mode
1322 when in Lisp Interaction mode:
1323
1324 @example
1325 (add-hook 'lisp-interaction-mode-hook 'turn-on-auto-fill)
1326 @end example
1327
1328   The next example shows how to use a hook to customize the way XEmacs
1329 formats C code.  (People often have strong personal preferences for one
1330 format or another.)  Here the hook function is an anonymous lambda
1331 expression.
1332
1333 @cindex lambda expression in hook
1334 @example
1335 @group
1336 (add-hook 'c-mode-hook
1337   (function (lambda ()
1338               (setq c-indent-level 4
1339                     c-argdecl-indent 0
1340                     c-label-offset -4
1341 @end group
1342 @group
1343                     c-continued-statement-indent 0
1344                     c-brace-offset 0
1345                     comment-column 40))))
1346
1347 (setq c++-mode-hook c-mode-hook)
1348 @end group
1349 @end example
1350
1351 The final example shows how the appearance of the modeline can be
1352 modified for a particular class of buffers only.
1353
1354 @example
1355 @group
1356 (add-hook 'text-mode-hook
1357   (function (lambda ()
1358               (setq modeline-format
1359                     '(modeline-modified
1360                       "Emacs: %14b"
1361                       "  "
1362 @end group
1363 @group
1364                       default-directory
1365                       " "
1366                       global-mode-string
1367                       "%[("
1368                       mode-name
1369                       minor-mode-alist
1370                       "%n"
1371                       modeline-process
1372                       ") %]---"
1373                       (-3 . "%p")
1374                       "-%-")))))
1375 @end group
1376 @end example
1377
1378   At the appropriate time, XEmacs uses the @code{run-hooks} function to
1379 run particular hooks.  This function calls the hook functions you have
1380 added with @code{add-hooks}.
1381
1382 @defun run-hooks &rest hookvar
1383 This function takes one or more hook variable names as arguments, and
1384 runs each hook in turn.  Each @var{hookvar} argument should be a symbol
1385 that is a hook variable.  These arguments are processed in the order
1386 specified.
1387
1388 If a hook variable has a non-@code{nil} value, that value may be a
1389 function or a list of functions.  If the value is a function (either a
1390 lambda expression or a symbol with a function definition), it is
1391 called.  If it is a list, the elements are called, in order.
1392 The hook functions are called with no arguments.
1393
1394 For example, here's how @code{emacs-lisp-mode} runs its mode hook:
1395
1396 @example
1397 (run-hooks 'emacs-lisp-mode-hook)
1398 @end example
1399 @end defun
1400
1401 @defun add-hook hook function &optional append local
1402 This function is the handy way to add function @var{function} to hook
1403 variable @var{hook}.  The argument @var{function} may be any valid Lisp
1404 function with the proper number of arguments.  For example,
1405
1406 @example
1407 (add-hook 'text-mode-hook 'my-text-hook-function)
1408 @end example
1409
1410 @noindent
1411 adds @code{my-text-hook-function} to the hook called @code{text-mode-hook}.
1412
1413 You can use @code{add-hook} for abnormal hooks as well as for normal
1414 hooks.
1415
1416 It is best to design your hook functions so that the order in which they
1417 are executed does not matter.  Any dependence on the order is ``asking
1418 for trouble.''  However, the order is predictable: normally,
1419 @var{function} goes at the front of the hook list, so it will be
1420 executed first (barring another @code{add-hook} call).
1421
1422 If the optional argument @var{append} is non-@code{nil}, the new hook
1423 function goes at the end of the hook list and will be executed last.
1424
1425 If @var{local} is non-@code{nil}, that says to make the new hook
1426 function local to the current buffer.  Before you can do this, you must
1427 make the hook itself buffer-local by calling @code{make-local-hook}
1428 (@strong{not} @code{make-local-variable}).  If the hook itself is not
1429 buffer-local, then the value of @var{local} makes no difference---the
1430 hook function is always global.
1431 @end defun
1432
1433 @defun remove-hook hook function &optional local
1434 This function removes @var{function} from the hook variable @var{hook}.
1435
1436 If @var{local} is non-@code{nil}, that says to remove @var{function}
1437 from the local hook list instead of from the global hook list.  If the
1438 hook itself is not buffer-local, then the value of @var{local} makes no
1439 difference.
1440 @end defun
1441
1442 @defun make-local-hook hook
1443 This function makes the hook variable @var{hook} local to the current
1444 buffer.  When a hook variable is local, it can have local and global
1445 hook functions, and @code{run-hooks} runs all of them.
1446
1447 This function works by making @code{t} an element of the buffer-local
1448 value.  That serves as a flag to use the hook functions in the default
1449 value of the hook variable as well as those in the local value.  Since
1450 @code{run-hooks} understands this flag, @code{make-local-hook} works
1451 with all normal hooks.  It works for only some non-normal hooks---those
1452 whose callers have been updated to understand this meaning of @code{t}.
1453
1454 Do not use @code{make-local-variable} directly for hook variables; it is
1455 not sufficient.
1456 @end defun