annotate lispref/modes.texi @ 50809:d02f8c881e70

Correct size for cleaner bitmaps.
author Nick Roberts <nickrob@snap.net.nz>
date Sun, 04 May 2003 19:21:03 +0000
parents 17c60796aa6a
children 59fa0bb3f282
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
6451
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1 @c -*-texinfo-*-
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2 @c This is part of the GNU Emacs Lisp Reference Manual.
50693
17c60796aa6a (font-lock-syntactic-keywords): Fix/expand description.
Dave Love <fx@gnu.org>
parents: 49600
diff changeset
3 @c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998, 1999, 2003
49600
23a1cea22d13 Trailing whitespace deleted.
Juanma Barranquero <lekktu@gmail.com>
parents: 48700
diff changeset
4 @c Free Software Foundation, Inc.
6451
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
5 @c See the file elisp.texi for copying conditions.
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
6 @setfilename ../info/modes
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
7 @node Modes, Documentation, Keymaps, Top
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
8 @chapter Major and Minor Modes
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
9 @cindex mode
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
10
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
11 A @dfn{mode} is a set of definitions that customize Emacs and can be
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
12 turned on and off while you edit. There are two varieties of modes:
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
13 @dfn{major modes}, which are mutually exclusive and used for editing
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
14 particular kinds of text, and @dfn{minor modes}, which provide features
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
15 that users can enable individually.
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
16
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
17 This chapter describes how to write both major and minor modes, how to
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
18 indicate them in the mode line, and how they run hooks supplied by the
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
19 user. For related topics such as keymaps and syntax tables, see
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
20 @ref{Keymaps}, and @ref{Syntax Tables}.
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
21
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
22 @menu
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
23 * Major Modes:: Defining major modes.
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
24 * Minor Modes:: Defining minor modes.
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
25 * Mode Line Format:: Customizing the text that appears in the mode line.
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17278
diff changeset
26 * Imenu:: How a mode can provide a menu
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17278
diff changeset
27 of definitions in the buffer.
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17278
diff changeset
28 * Font Lock Mode:: How modes can highlight text according to syntax.
6451
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
29 * Hooks:: How to use hooks; how to write code that provides hooks.
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
30 @end menu
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
31
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
32 @node Major Modes
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
33 @section Major Modes
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
34 @cindex major mode
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
35 @cindex Fundamental mode
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
36
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
37 Major modes specialize Emacs for editing particular kinds of text.
43677
8d02880abeaa (Major Modes): Explain major mode functions, how they work, and how
Richard M. Stallman <rms@gnu.org>
parents: 43264
diff changeset
38 Each buffer has only one major mode at a time. For each major mode
8d02880abeaa (Major Modes): Explain major mode functions, how they work, and how
Richard M. Stallman <rms@gnu.org>
parents: 43264
diff changeset
39 there is a function to switch to that mode in the current buffer; its
8d02880abeaa (Major Modes): Explain major mode functions, how they work, and how
Richard M. Stallman <rms@gnu.org>
parents: 43264
diff changeset
40 name should end in @samp{-mode}. These functions work by setting
8d02880abeaa (Major Modes): Explain major mode functions, how they work, and how
Richard M. Stallman <rms@gnu.org>
parents: 43264
diff changeset
41 buffer-local variable bindings and other data associated with the
8d02880abeaa (Major Modes): Explain major mode functions, how they work, and how
Richard M. Stallman <rms@gnu.org>
parents: 43264
diff changeset
42 buffer, such as a local keymap. The effect lasts until you switch
8d02880abeaa (Major Modes): Explain major mode functions, how they work, and how
Richard M. Stallman <rms@gnu.org>
parents: 43264
diff changeset
43 to another major mode in the same buffer.
6451
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
44
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
45 The least specialized major mode is called @dfn{Fundamental mode}.
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
46 This mode has no mode-specific definitions or variable settings, so each
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
47 Emacs command behaves in its default manner, and each option is in its
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
48 default state. All other major modes redefine various keys and options.
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
49 For example, Lisp Interaction mode provides special key bindings for
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
50 @kbd{C-j} (@code{eval-print-last-sexp}), @key{TAB}
6451
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
51 (@code{lisp-indent-line}), and other keys.
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
52
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
53 When you need to write several editing commands to help you perform a
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
54 specialized editing task, creating a new major mode is usually a good
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
55 idea. In practice, writing a major mode is easy (in contrast to
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
56 writing a minor mode, which is often difficult).
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
57
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
58 If the new mode is similar to an old one, it is often unwise to modify
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
59 the old one to serve two purposes, since it may become harder to use and
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
60 maintain. Instead, copy and rename an existing major mode definition
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
61 and alter the copy---or define a @dfn{derived mode} (@pxref{Derived
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
62 Modes}). For example, Rmail Edit mode, which is in
25875
6a17c48b52ef *** empty log message ***
Phillip Rulon <pjr@gnu.org>
parents: 25751
diff changeset
63 @file{emacs/lisp/mail/rmailedit.el}, is a major mode that is very similar to
6a17c48b52ef *** empty log message ***
Phillip Rulon <pjr@gnu.org>
parents: 25751
diff changeset
64 Text mode except that it provides two additional commands. Its
6a17c48b52ef *** empty log message ***
Phillip Rulon <pjr@gnu.org>
parents: 25751
diff changeset
65 definition is distinct from that of Text mode, but uses that of Text mode.
6451
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
66
28603
cb9db16dba12 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 27390
diff changeset
67 Even if the new mode is not an obvious derivative of any other mode,
39793
1d5b7d31671f Recommend the use of define-derived-mode (and nil argument).
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 38200
diff changeset
68 it is convenient to use @code{define-derived-mode} with a @code{nil}
1d5b7d31671f Recommend the use of define-derived-mode (and nil argument).
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 38200
diff changeset
69 parent argument, since it automatically enforces the most important
1d5b7d31671f Recommend the use of define-derived-mode (and nil argument).
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 38200
diff changeset
70 coding conventions for you.
28603
cb9db16dba12 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 27390
diff changeset
71
46914
56bbdfd75143 Mention define-generic-mode.
Richard M. Stallman <rms@gnu.org>
parents: 45714
diff changeset
72 @findex define-generic-mode
56bbdfd75143 Mention define-generic-mode.
Richard M. Stallman <rms@gnu.org>
parents: 45714
diff changeset
73 For a very simple programming language major mode that handles
56bbdfd75143 Mention define-generic-mode.
Richard M. Stallman <rms@gnu.org>
parents: 45714
diff changeset
74 comments and fontification, you can use @code{define-generic-mode}
56bbdfd75143 Mention define-generic-mode.
Richard M. Stallman <rms@gnu.org>
parents: 45714
diff changeset
75 in @file{generic.el}.
56bbdfd75143 Mention define-generic-mode.
Richard M. Stallman <rms@gnu.org>
parents: 45714
diff changeset
76
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
77 Rmail Edit mode offers an example of changing the major mode
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
78 temporarily for a buffer, so it can be edited in a different way (with
22252
40089afa2b1d *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22138
diff changeset
79 ordinary Emacs commands rather than Rmail commands). In such cases, the
25751
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 24934
diff changeset
80 temporary major mode usually provides a command to switch back to the
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
81 buffer's usual mode (Rmail mode, in this case). You might be tempted to
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
82 present the temporary redefinitions inside a recursive edit and restore
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
83 the usual ones when the user exits; but this is a bad idea because it
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
84 constrains the user's options when it is done in more than one buffer:
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
85 recursive edits must be exited most-recently-entered first. Using an
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
86 alternative major mode avoids this limitation. @xref{Recursive
6451
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
87 Editing}.
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
88
25751
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 24934
diff changeset
89 The standard GNU Emacs Lisp library directory tree contains the code
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 24934
diff changeset
90 for several major modes, in files such as @file{text-mode.el},
6451
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
91 @file{texinfo.el}, @file{lisp-mode.el}, @file{c-mode.el}, and
25875
6a17c48b52ef *** empty log message ***
Phillip Rulon <pjr@gnu.org>
parents: 25751
diff changeset
92 @file{rmail.el}. They are found in various subdirectories of the
6a17c48b52ef *** empty log message ***
Phillip Rulon <pjr@gnu.org>
parents: 25751
diff changeset
93 @file{lisp} directory. You can study these libraries to see how modes
6a17c48b52ef *** empty log message ***
Phillip Rulon <pjr@gnu.org>
parents: 25751
diff changeset
94 are written. Text mode is perhaps the simplest major mode aside from
6451
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
95 Fundamental mode. Rmail mode is a complicated and specialized mode.
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
96
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
97 @menu
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
98 * Major Mode Conventions:: Coding conventions for keymaps, etc.
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
99 * Example Major Modes:: Text mode and Lisp modes.
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
100 * Auto Major Mode:: How Emacs chooses the major mode automatically.
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
101 * Mode Help:: Finding out how to use a mode.
49600
23a1cea22d13 Trailing whitespace deleted.
Juanma Barranquero <lekktu@gmail.com>
parents: 48700
diff changeset
102 * Derived Modes:: Defining a new major mode based on another major
6451
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
103 mode.
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
104 @end menu
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
105
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
106 @node Major Mode Conventions
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
107 @subsection Major Mode Conventions
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
108
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
109 The code for existing major modes follows various coding conventions,
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
110 including conventions for local keymap and syntax table initialization,
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
111 global names, and hooks. Please follow these conventions when you
38200
6c286c714f74 (Major Mode Conventions): Say not to change meaning of RET, and not to
Richard M. Stallman <rms@gnu.org>
parents: 38161
diff changeset
112 define a new major mode.
6c286c714f74 (Major Mode Conventions): Say not to change meaning of RET, and not to
Richard M. Stallman <rms@gnu.org>
parents: 38161
diff changeset
113
6c286c714f74 (Major Mode Conventions): Say not to change meaning of RET, and not to
Richard M. Stallman <rms@gnu.org>
parents: 38161
diff changeset
114 This list of conventions is only partial, because each major mode
6c286c714f74 (Major Mode Conventions): Say not to change meaning of RET, and not to
Richard M. Stallman <rms@gnu.org>
parents: 38161
diff changeset
115 should aim for consistency in general with other Emacs major modes.
6c286c714f74 (Major Mode Conventions): Say not to change meaning of RET, and not to
Richard M. Stallman <rms@gnu.org>
parents: 38161
diff changeset
116 This makes Emacs as a whole more coherent. It is impossible to list
6c286c714f74 (Major Mode Conventions): Say not to change meaning of RET, and not to
Richard M. Stallman <rms@gnu.org>
parents: 38161
diff changeset
117 here all the possible points where this issue might come up; if the
6c286c714f74 (Major Mode Conventions): Say not to change meaning of RET, and not to
Richard M. Stallman <rms@gnu.org>
parents: 38161
diff changeset
118 Emacs developers point out an area where your major mode deviates from
6c286c714f74 (Major Mode Conventions): Say not to change meaning of RET, and not to
Richard M. Stallman <rms@gnu.org>
parents: 38161
diff changeset
119 the usual conventions, please make it compatible.
6451
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
120
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
121 @itemize @bullet
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
122 @item
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
123 Define a command whose name ends in @samp{-mode}, with no arguments,
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
124 that switches to the new mode in the current buffer. This command
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
125 should set up the keymap, syntax table, and buffer-local variables in an
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
126 existing buffer, without changing the buffer's contents.
6451
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
127
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
128 @item
7253
6ba87aed7836 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6451
diff changeset
129 Write a documentation string for this command that describes the
6451
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
130 special commands available in this mode. @kbd{C-h m}
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
131 (@code{describe-mode}) in your mode will display this string.
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
132
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
133 The documentation string may include the special documentation
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
134 substrings, @samp{\[@var{command}]}, @samp{\@{@var{keymap}@}}, and
24934
f5e3b4ecd255 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 22274
diff changeset
135 @samp{\<@var{keymap}>}, which enable the documentation to adapt
6451
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
136 automatically to the user's own key bindings. @xref{Keys in
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
137 Documentation}.
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
138
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
139 @item
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
140 The major mode command should start by calling
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
141 @code{kill-all-local-variables}. This is what gets rid of the
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
142 buffer-local variables of the major mode previously in effect.
6451
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
143
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
144 @item
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
145 The major mode command should set the variable @code{major-mode} to the
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
146 major mode command symbol. This is how @code{describe-mode} discovers
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
147 which documentation to print.
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
148
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
149 @item
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
150 The major mode command should set the variable @code{mode-name} to the
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
151 ``pretty'' name of the mode, as a string. This string appears in the
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
152 mode line.
6451
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
153
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
154 @item
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
155 @cindex functions in modes
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
156 Since all global names are in the same name space, all the global
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
157 variables, constants, and functions that are part of the mode should
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
158 have names that start with the major mode name (or with an abbreviation
17278
8ed8412c1ce7 Document key binding conventions for major modes and minor modes.
Richard M. Stallman <rms@gnu.org>
parents: 16432
diff changeset
159 of it if the name is long). @xref{Coding Conventions}.
6451
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
160
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
161 @item
38200
6c286c714f74 (Major Mode Conventions): Say not to change meaning of RET, and not to
Richard M. Stallman <rms@gnu.org>
parents: 38161
diff changeset
162 In a major mode for editing some kind of structured text, such as a
6c286c714f74 (Major Mode Conventions): Say not to change meaning of RET, and not to
Richard M. Stallman <rms@gnu.org>
parents: 38161
diff changeset
163 programming language, indentation of text according to structure is
6c286c714f74 (Major Mode Conventions): Say not to change meaning of RET, and not to
Richard M. Stallman <rms@gnu.org>
parents: 38161
diff changeset
164 probably useful. So the mode should set @code{indent-line-function}
6c286c714f74 (Major Mode Conventions): Say not to change meaning of RET, and not to
Richard M. Stallman <rms@gnu.org>
parents: 38161
diff changeset
165 to a suitable function, and probably customize other variables
6c286c714f74 (Major Mode Conventions): Say not to change meaning of RET, and not to
Richard M. Stallman <rms@gnu.org>
parents: 38161
diff changeset
166 for indentation.
6c286c714f74 (Major Mode Conventions): Say not to change meaning of RET, and not to
Richard M. Stallman <rms@gnu.org>
parents: 38161
diff changeset
167
6c286c714f74 (Major Mode Conventions): Say not to change meaning of RET, and not to
Richard M. Stallman <rms@gnu.org>
parents: 38161
diff changeset
168 @item
6451
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
169 @cindex keymaps in modes
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
170 The major mode should usually have its own keymap, which is used as the
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
171 local keymap in all buffers in that mode. The major mode command should
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
172 call @code{use-local-map} to install this local map. @xref{Active
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
173 Keymaps}, for more information.
6451
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
174
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
175 This keymap should be stored permanently in a global variable named
6451
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
176 @code{@var{modename}-mode-map}. Normally the library that defines the
7253
6ba87aed7836 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6451
diff changeset
177 mode sets this variable.
6451
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
178
12803
6dcd5ad16790 Make Major Mode Conventions xref to Tips for Defining.
Richard M. Stallman <rms@gnu.org>
parents: 12234
diff changeset
179 @xref{Tips for Defining}, for advice about how to write the code to set
6dcd5ad16790 Make Major Mode Conventions xref to Tips for Defining.
Richard M. Stallman <rms@gnu.org>
parents: 12234
diff changeset
180 up the mode's keymap variable.
6dcd5ad16790 Make Major Mode Conventions xref to Tips for Defining.
Richard M. Stallman <rms@gnu.org>
parents: 12234
diff changeset
181
6451
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
182 @item
17278
8ed8412c1ce7 Document key binding conventions for major modes and minor modes.
Richard M. Stallman <rms@gnu.org>
parents: 16432
diff changeset
183 The key sequences bound in a major mode keymap should usually start with
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
184 @kbd{C-c}, followed by a control character, a digit, or @kbd{@{},
17278
8ed8412c1ce7 Document key binding conventions for major modes and minor modes.
Richard M. Stallman <rms@gnu.org>
parents: 16432
diff changeset
185 @kbd{@}}, @kbd{<}, @kbd{>}, @kbd{:} or @kbd{;}. The other punctuation
8ed8412c1ce7 Document key binding conventions for major modes and minor modes.
Richard M. Stallman <rms@gnu.org>
parents: 16432
diff changeset
186 characters are reserved for minor modes, and ordinary letters are
8ed8412c1ce7 Document key binding conventions for major modes and minor modes.
Richard M. Stallman <rms@gnu.org>
parents: 16432
diff changeset
187 reserved for users.
8ed8412c1ce7 Document key binding conventions for major modes and minor modes.
Richard M. Stallman <rms@gnu.org>
parents: 16432
diff changeset
188
8ed8412c1ce7 Document key binding conventions for major modes and minor modes.
Richard M. Stallman <rms@gnu.org>
parents: 16432
diff changeset
189 It is reasonable for a major mode to rebind a key sequence with a
8ed8412c1ce7 Document key binding conventions for major modes and minor modes.
Richard M. Stallman <rms@gnu.org>
parents: 16432
diff changeset
190 standard meaning, if it implements a command that does ``the same job''
8ed8412c1ce7 Document key binding conventions for major modes and minor modes.
Richard M. Stallman <rms@gnu.org>
parents: 16432
diff changeset
191 in a way that fits the major mode better. For example, a major mode for
8ed8412c1ce7 Document key binding conventions for major modes and minor modes.
Richard M. Stallman <rms@gnu.org>
parents: 16432
diff changeset
192 editing a programming language might redefine @kbd{C-M-a} to ``move to
8ed8412c1ce7 Document key binding conventions for major modes and minor modes.
Richard M. Stallman <rms@gnu.org>
parents: 16432
diff changeset
193 the beginning of a function'' in a way that works better for that
8ed8412c1ce7 Document key binding conventions for major modes and minor modes.
Richard M. Stallman <rms@gnu.org>
parents: 16432
diff changeset
194 language.
8ed8412c1ce7 Document key binding conventions for major modes and minor modes.
Richard M. Stallman <rms@gnu.org>
parents: 16432
diff changeset
195
8ed8412c1ce7 Document key binding conventions for major modes and minor modes.
Richard M. Stallman <rms@gnu.org>
parents: 16432
diff changeset
196 Major modes such as Dired or Rmail that do not allow self-insertion of
8ed8412c1ce7 Document key binding conventions for major modes and minor modes.
Richard M. Stallman <rms@gnu.org>
parents: 16432
diff changeset
197 text can reasonably redefine letters and other printing characters as
8ed8412c1ce7 Document key binding conventions for major modes and minor modes.
Richard M. Stallman <rms@gnu.org>
parents: 16432
diff changeset
198 editing commands. Dired and Rmail both do this.
8ed8412c1ce7 Document key binding conventions for major modes and minor modes.
Richard M. Stallman <rms@gnu.org>
parents: 16432
diff changeset
199
8ed8412c1ce7 Document key binding conventions for major modes and minor modes.
Richard M. Stallman <rms@gnu.org>
parents: 16432
diff changeset
200 @item
38161
45d64a431eea (Major Mode Conventions): Major modes should not change RET.
Richard M. Stallman <rms@gnu.org>
parents: 36347
diff changeset
201 Major modes must not define @key{RET} to do anything other than insert
45d64a431eea (Major Mode Conventions): Major modes should not change RET.
Richard M. Stallman <rms@gnu.org>
parents: 36347
diff changeset
202 a newline. The command to insert a newline and then indent is
38200
6c286c714f74 (Major Mode Conventions): Say not to change meaning of RET, and not to
Richard M. Stallman <rms@gnu.org>
parents: 38161
diff changeset
203 @kbd{C-j}. Please keep this distinction uniform for all major modes.
6c286c714f74 (Major Mode Conventions): Say not to change meaning of RET, and not to
Richard M. Stallman <rms@gnu.org>
parents: 38161
diff changeset
204
6c286c714f74 (Major Mode Conventions): Say not to change meaning of RET, and not to
Richard M. Stallman <rms@gnu.org>
parents: 38161
diff changeset
205 @item
6c286c714f74 (Major Mode Conventions): Say not to change meaning of RET, and not to
Richard M. Stallman <rms@gnu.org>
parents: 38161
diff changeset
206 Major modes should not alter options that are primary a matter of user
6c286c714f74 (Major Mode Conventions): Say not to change meaning of RET, and not to
Richard M. Stallman <rms@gnu.org>
parents: 38161
diff changeset
207 preference, such as whether Auto-Fill mode is enabled. Leave this to
6c286c714f74 (Major Mode Conventions): Say not to change meaning of RET, and not to
Richard M. Stallman <rms@gnu.org>
parents: 38161
diff changeset
208 each user to decide. However, a major mode should customize other
6c286c714f74 (Major Mode Conventions): Say not to change meaning of RET, and not to
Richard M. Stallman <rms@gnu.org>
parents: 38161
diff changeset
209 variables so that Auto-Fill mode will work usefully @emph{if} the user
6c286c714f74 (Major Mode Conventions): Say not to change meaning of RET, and not to
Richard M. Stallman <rms@gnu.org>
parents: 38161
diff changeset
210 decides to use it.
38161
45d64a431eea (Major Mode Conventions): Major modes should not change RET.
Richard M. Stallman <rms@gnu.org>
parents: 36347
diff changeset
211
45d64a431eea (Major Mode Conventions): Major modes should not change RET.
Richard M. Stallman <rms@gnu.org>
parents: 36347
diff changeset
212 @item
6451
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
213 @cindex syntax tables in modes
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
214 The mode may have its own syntax table or may share one with other
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
215 related modes. If it has its own syntax table, it should store this in
7253
6ba87aed7836 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6451
diff changeset
216 a variable named @code{@var{modename}-mode-syntax-table}. @xref{Syntax
6451
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
217 Tables}.
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
218
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
219 @item
16432
6f58503776e5 Explain what major modes can do for imenu and font-lock.
Richard M. Stallman <rms@gnu.org>
parents: 16056
diff changeset
220 If the mode handles a language that has a syntax for comments, it should
6f58503776e5 Explain what major modes can do for imenu and font-lock.
Richard M. Stallman <rms@gnu.org>
parents: 16056
diff changeset
221 set the variables that define the comment syntax. @xref{Options for
6f58503776e5 Explain what major modes can do for imenu and font-lock.
Richard M. Stallman <rms@gnu.org>
parents: 16056
diff changeset
222 Comments,, Options Controlling Comments, emacs, The GNU Emacs Manual}.
6f58503776e5 Explain what major modes can do for imenu and font-lock.
Richard M. Stallman <rms@gnu.org>
parents: 16056
diff changeset
223
6f58503776e5 Explain what major modes can do for imenu and font-lock.
Richard M. Stallman <rms@gnu.org>
parents: 16056
diff changeset
224 @item
6451
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
225 @cindex abbrev tables in modes
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
226 The mode may have its own abbrev table or may share one with other
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
227 related modes. If it has its own abbrev table, it should store this in
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
228 a variable named @code{@var{modename}-mode-abbrev-table}. @xref{Abbrev
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
229 Tables}.
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
230
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
231 @item
16432
6f58503776e5 Explain what major modes can do for imenu and font-lock.
Richard M. Stallman <rms@gnu.org>
parents: 16056
diff changeset
232 The mode should specify how to do highlighting for Font Lock mode, by
6f58503776e5 Explain what major modes can do for imenu and font-lock.
Richard M. Stallman <rms@gnu.org>
parents: 16056
diff changeset
233 setting up a buffer-local value for the variable
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
234 @code{font-lock-defaults} (@pxref{Font Lock Mode}).
16432
6f58503776e5 Explain what major modes can do for imenu and font-lock.
Richard M. Stallman <rms@gnu.org>
parents: 16056
diff changeset
235
6f58503776e5 Explain what major modes can do for imenu and font-lock.
Richard M. Stallman <rms@gnu.org>
parents: 16056
diff changeset
236 @item
6f58503776e5 Explain what major modes can do for imenu and font-lock.
Richard M. Stallman <rms@gnu.org>
parents: 16056
diff changeset
237 The mode should specify how Imenu should find the definitions or
6f58503776e5 Explain what major modes can do for imenu and font-lock.
Richard M. Stallman <rms@gnu.org>
parents: 16056
diff changeset
238 sections of a buffer, by setting up a buffer-local value for the
6f58503776e5 Explain what major modes can do for imenu and font-lock.
Richard M. Stallman <rms@gnu.org>
parents: 16056
diff changeset
239 variable @code{imenu-generic-expression} or
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
240 @code{imenu-create-index-function} (@pxref{Imenu}).
16432
6f58503776e5 Explain what major modes can do for imenu and font-lock.
Richard M. Stallman <rms@gnu.org>
parents: 16056
diff changeset
241
6f58503776e5 Explain what major modes can do for imenu and font-lock.
Richard M. Stallman <rms@gnu.org>
parents: 16056
diff changeset
242 @item
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
243 Use @code{defvar} or @code{defcustom} to set mode-related variables, so
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
244 that they are not reinitialized if they already have a value. (Such
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
245 reinitialization could discard customizations made by the user.)
7253
6ba87aed7836 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6451
diff changeset
246
6ba87aed7836 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6451
diff changeset
247 @item
6451
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
248 @cindex buffer-local variables in modes
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
249 To make a buffer-local binding for an Emacs customization variable, use
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
250 @code{make-local-variable} in the major mode command, not
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
251 @code{make-variable-buffer-local}. The latter function would make the
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
252 variable local to every buffer in which it is subsequently set, which
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
253 would affect buffers that do not use this mode. It is undesirable for a
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
254 mode to have such global effects. @xref{Buffer-Local Variables}.
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
255
49600
23a1cea22d13 Trailing whitespace deleted.
Juanma Barranquero <lekktu@gmail.com>
parents: 48700
diff changeset
256 With rare exceptions, the only reasonable way to use
25875
6a17c48b52ef *** empty log message ***
Phillip Rulon <pjr@gnu.org>
parents: 25751
diff changeset
257 @code{make-variable-buffer-local} in a Lisp package is for a variable
6a17c48b52ef *** empty log message ***
Phillip Rulon <pjr@gnu.org>
parents: 25751
diff changeset
258 which is used only within that package. Using it on a variable used by
6a17c48b52ef *** empty log message ***
Phillip Rulon <pjr@gnu.org>
parents: 25751
diff changeset
259 other packages would interfere with them.
6451
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
260
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
261 @item
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
262 @cindex mode hook
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
263 @cindex major mode hook
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
264 Each major mode should have a @dfn{mode hook} named
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
265 @code{@var{modename}-mode-hook}. The major mode command should run that
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
266 hook, with @code{run-hooks}, as the very last thing it
17278
8ed8412c1ce7 Document key binding conventions for major modes and minor modes.
Richard M. Stallman <rms@gnu.org>
parents: 16432
diff changeset
267 does. @xref{Hooks}.
6451
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
268
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
269 @item
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
270 The major mode command may also run the hooks of some more basic modes.
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
271 For example, @code{indented-text-mode} runs @code{text-mode-hook} as
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
272 well as @code{indented-text-mode-hook}. It may run these other hooks
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
273 immediately before the mode's own hook (that is, after everything else),
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
274 or it may run them earlier.
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
275
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
276 @item
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
277 If something special should be done if the user switches a buffer from
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17278
diff changeset
278 this mode to any other major mode, this mode can set up a buffer-local
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
279 value for @code{change-major-mode-hook} (@pxref{Creating Buffer-Local}).
6451
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
280
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
281 @item
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
282 If this mode is appropriate only for specially-prepared text, then the
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
283 major mode command symbol should have a property named @code{mode-class}
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
284 with value @code{special}, put on as follows:
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
285
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
286 @cindex @code{mode-class} property
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
287 @cindex @code{special}
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
288 @example
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
289 (put 'funny-mode 'mode-class 'special)
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
290 @end example
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
291
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
292 @noindent
25751
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 24934
diff changeset
293 This tells Emacs that new buffers created while the current buffer is in
6451
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
294 Funny mode should not inherit Funny mode. Modes such as Dired, Rmail,
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
295 and Buffer List use this feature.
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
296
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
297 @item
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
298 If you want to make the new mode the default for files with certain
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
299 recognizable names, add an element to @code{auto-mode-alist} to select
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
300 the mode for those file names. If you define the mode command to
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
301 autoload, you should add this element in the same file that calls
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
302 @code{autoload}. Otherwise, it is sufficient to add the element in the
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
303 file that contains the mode definition. @xref{Auto Major Mode}.
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
304
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
305 @item
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
306 In the documentation, you should provide a sample @code{autoload} form
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
307 and an example of how to add to @code{auto-mode-alist}, that users can
25875
6a17c48b52ef *** empty log message ***
Phillip Rulon <pjr@gnu.org>
parents: 25751
diff changeset
308 include in their init files (@pxref{Init File}).
6451
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
309
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
310 @item
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
311 @cindex mode loading
7253
6ba87aed7836 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6451
diff changeset
312 The top-level forms in the file defining the mode should be written so
6451
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
313 that they may be evaluated more than once without adverse consequences.
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
314 Even if you never load the file more than once, someone else will.
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
315 @end itemize
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
316
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
317 @node Example Major Modes
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
318 @subsection Major Mode Examples
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
319
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
320 Text mode is perhaps the simplest mode besides Fundamental mode.
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
321 Here are excerpts from @file{text-mode.el} that illustrate many of
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
322 the conventions listed above:
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
323
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
324 @smallexample
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
325 @group
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
326 ;; @r{Create mode-specific tables.}
49600
23a1cea22d13 Trailing whitespace deleted.
Juanma Barranquero <lekktu@gmail.com>
parents: 48700
diff changeset
327 (defvar text-mode-syntax-table nil
6451
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
328 "Syntax table used while in text mode.")
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
329 @end group
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
330
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
331 @group
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
332 (if text-mode-syntax-table
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
333 () ; @r{Do not change the table if it is already set up.}
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
334 (setq text-mode-syntax-table (make-syntax-table))
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
335 (modify-syntax-entry ?\" ". " text-mode-syntax-table)
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
336 (modify-syntax-entry ?\\ ". " text-mode-syntax-table)
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
337 (modify-syntax-entry ?' "w " text-mode-syntax-table))
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
338 @end group
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
339
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
340 @group
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
341 (defvar text-mode-abbrev-table nil
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
342 "Abbrev table used while in text mode.")
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
343 (define-abbrev-table 'text-mode-abbrev-table ())
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
344 @end group
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
345
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
346 @group
25875
6a17c48b52ef *** empty log message ***
Phillip Rulon <pjr@gnu.org>
parents: 25751
diff changeset
347 (defvar text-mode-map nil ; @r{Create a mode-specific keymap.}
6a17c48b52ef *** empty log message ***
Phillip Rulon <pjr@gnu.org>
parents: 25751
diff changeset
348 "Keymap for Text mode.
6a17c48b52ef *** empty log message ***
Phillip Rulon <pjr@gnu.org>
parents: 25751
diff changeset
349 Many other modes, such as Mail mode, Outline mode and Indented Text mode,
6a17c48b52ef *** empty log message ***
Phillip Rulon <pjr@gnu.org>
parents: 25751
diff changeset
350 inherit all the commands defined in this map.")
6451
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
351
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
352 (if text-mode-map
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
353 () ; @r{Do not change the keymap if it is already set up.}
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
354 (setq text-mode-map (make-sparse-keymap))
25875
6a17c48b52ef *** empty log message ***
Phillip Rulon <pjr@gnu.org>
parents: 25751
diff changeset
355 (define-key text-mode-map "\e\t" 'ispell-complete-word)
22138
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
356 (define-key text-mode-map "\t" 'indent-relative)
6451
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
357 (define-key text-mode-map "\es" 'center-line)
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
358 (define-key text-mode-map "\eS" 'center-paragraph))
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
359 @end group
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
360 @end smallexample
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
361
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
362 Here is the complete major mode function definition for Text mode:
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
363
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
364 @smallexample
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
365 @group
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
366 (defun text-mode ()
25950
7996385fc601 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 25875
diff changeset
367 "Major mode for editing text intended for humans to read...
6451
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
368 Special commands: \\@{text-mode-map@}
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
369 @end group
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
370 @group
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
371 Turning on text-mode runs the hook `text-mode-hook'."
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
372 (interactive)
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
373 (kill-all-local-variables)
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
374 (use-local-map text-mode-map)
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
375 @end group
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
376 @group
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
377 (setq local-abbrev-table text-mode-abbrev-table)
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
378 (set-syntax-table text-mode-syntax-table)
6451
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
379 @end group
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
380 @group
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
381 (make-local-variable 'paragraph-start)
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
382 (setq paragraph-start (concat "[ \t]*$\\|" page-delimiter))
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
383 (make-local-variable 'paragraph-separate)
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
384 (setq paragraph-separate paragraph-start)
25875
6a17c48b52ef *** empty log message ***
Phillip Rulon <pjr@gnu.org>
parents: 25751
diff changeset
385 (make-local-variable 'indent-line-function)
6a17c48b52ef *** empty log message ***
Phillip Rulon <pjr@gnu.org>
parents: 25751
diff changeset
386 (setq indent-line-function 'indent-relative-maybe)
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
387 @end group
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
388 @group
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
389 (setq mode-name "Text")
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
390 (setq major-mode 'text-mode)
6451
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
391 (run-hooks 'text-mode-hook)) ; @r{Finally, this permits the user to}
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
392 ; @r{customize the mode with a hook.}
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
393 @end group
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
394 @end smallexample
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
395
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
396 @cindex @file{lisp-mode.el}
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
397 The three Lisp modes (Lisp mode, Emacs Lisp mode, and Lisp
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
398 Interaction mode) have more features than Text mode and the code is
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
399 correspondingly more complicated. Here are excerpts from
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
400 @file{lisp-mode.el} that illustrate how these modes are written.
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
401
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
402 @cindex syntax table example
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
403 @smallexample
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
404 @group
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
405 ;; @r{Create mode-specific table variables.}
49600
23a1cea22d13 Trailing whitespace deleted.
Juanma Barranquero <lekktu@gmail.com>
parents: 48700
diff changeset
406 (defvar lisp-mode-syntax-table nil "")
6451
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
407 (defvar emacs-lisp-mode-syntax-table nil "")
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
408 (defvar lisp-mode-abbrev-table nil "")
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
409 @end group
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
410
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
411 @group
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
412 (if (not emacs-lisp-mode-syntax-table) ; @r{Do not change the table}
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
413 ; @r{if it is already set.}
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
414 (let ((i 0))
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
415 (setq emacs-lisp-mode-syntax-table (make-syntax-table))
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
416 @end group
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
417
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
418 @group
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
419 ;; @r{Set syntax of chars up to 0 to class of chars that are}
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
420 ;; @r{part of symbol names but not words.}
25751
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 24934
diff changeset
421 ;; @r{(The number 0 is @code{48} in the @sc{ascii} character set.)}
49600
23a1cea22d13 Trailing whitespace deleted.
Juanma Barranquero <lekktu@gmail.com>
parents: 48700
diff changeset
422 (while (< i ?0)
6451
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
423 (modify-syntax-entry i "_ " emacs-lisp-mode-syntax-table)
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
424 (setq i (1+ i)))
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
425 @dots{}
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
426 @end group
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
427 @group
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
428 ;; @r{Set the syntax for other characters.}
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
429 (modify-syntax-entry ? " " emacs-lisp-mode-syntax-table)
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
430 (modify-syntax-entry ?\t " " emacs-lisp-mode-syntax-table)
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
431 @dots{}
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
432 @end group
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
433 @group
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
434 (modify-syntax-entry ?\( "() " emacs-lisp-mode-syntax-table)
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
435 (modify-syntax-entry ?\) ")( " emacs-lisp-mode-syntax-table)
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
436 @dots{}))
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
437 ;; @r{Create an abbrev table for lisp-mode.}
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
438 (define-abbrev-table 'lisp-mode-abbrev-table ())
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
439 @end group
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
440 @end smallexample
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
441
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
442 Much code is shared among the three Lisp modes. The following
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
443 function sets various variables; it is called by each of the major Lisp
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
444 mode functions:
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
445
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
446 @smallexample
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
447 @group
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
448 (defun lisp-mode-variables (lisp-syntax)
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
449 (cond (lisp-syntax
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
450 (set-syntax-table lisp-mode-syntax-table)))
6451
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
451 (setq local-abbrev-table lisp-mode-abbrev-table)
22138
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
452 @dots{}
6451
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
453 @end group
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
454 @end smallexample
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
455
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
456 Functions such as @code{forward-paragraph} use the value of the
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
457 @code{paragraph-start} variable. Since Lisp code is different from
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
458 ordinary text, the @code{paragraph-start} variable needs to be set
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
459 specially to handle Lisp. Also, comments are indented in a special
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
460 fashion in Lisp and the Lisp modes need their own mode-specific
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
461 @code{comment-indent-function}. The code to set these variables is the
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
462 rest of @code{lisp-mode-variables}.
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
463
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
464 @smallexample
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
465 @group
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
466 (make-local-variable 'paragraph-start)
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
467 (setq paragraph-start (concat page-delimiter "\\|$" ))
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
468 (make-local-variable 'paragraph-separate)
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
469 (setq paragraph-separate paragraph-start)
6451
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
470 @dots{}
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
471 @end group
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
472 @group
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
473 (make-local-variable 'comment-indent-function)
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
474 (setq comment-indent-function 'lisp-comment-indent))
25875
6a17c48b52ef *** empty log message ***
Phillip Rulon <pjr@gnu.org>
parents: 25751
diff changeset
475 @dots{}
6451
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
476 @end group
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
477 @end smallexample
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
478
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
479 Each of the different Lisp modes has a slightly different keymap. For
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17278
diff changeset
480 example, Lisp mode binds @kbd{C-c C-z} to @code{run-lisp}, but the other
6451
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
481 Lisp modes do not. However, all Lisp modes have some commands in
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
482 common. The following code sets up the common commands:
6451
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
483
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
484 @smallexample
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
485 @group
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
486 (defvar shared-lisp-mode-map ()
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
487 "Keymap for commands shared by all sorts of Lisp modes.")
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
488
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
489 (if shared-lisp-mode-map
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
490 ()
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
491 (setq shared-lisp-mode-map (make-sparse-keymap))
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
492 (define-key shared-lisp-mode-map "\e\C-q" 'indent-sexp)
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
493 (define-key shared-lisp-mode-map "\177"
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
494 'backward-delete-char-untabify))
6451
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
495 @end group
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
496 @end smallexample
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
497
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
498 @noindent
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
499 And here is the code to set up the keymap for Lisp mode:
6451
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
500
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
501 @smallexample
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
502 @group
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
503 (defvar lisp-mode-map ()
25950
7996385fc601 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 25875
diff changeset
504 "Keymap for ordinary Lisp mode...")
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
505
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
506 (if lisp-mode-map
6451
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
507 ()
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
508 (setq lisp-mode-map (make-sparse-keymap))
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
509 (set-keymap-parent lisp-mode-map shared-lisp-mode-map)
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
510 (define-key lisp-mode-map "\e\C-x" 'lisp-eval-defun)
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
511 (define-key lisp-mode-map "\C-c\C-z" 'run-lisp))
6451
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
512 @end group
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
513 @end smallexample
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
514
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
515 Finally, here is the complete major mode function definition for
49600
23a1cea22d13 Trailing whitespace deleted.
Juanma Barranquero <lekktu@gmail.com>
parents: 48700
diff changeset
516 Lisp mode.
6451
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
517
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
518 @smallexample
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
519 @group
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
520 (defun lisp-mode ()
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
521 "Major mode for editing Lisp code for Lisps other than GNU Emacs Lisp.
6451
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
522 Commands:
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
523 Delete converts tabs to spaces as it moves back.
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
524 Blank lines separate paragraphs. Semicolons start comments.
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
525 \\@{lisp-mode-map@}
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
526 Note that `run-lisp' may be used either to start an inferior Lisp job
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
527 or to switch back to an existing one.
6451
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
528 @end group
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
529
6451
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
530 @group
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
531 Entry to this mode calls the value of `lisp-mode-hook'
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
532 if that value is non-nil."
6451
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
533 (interactive)
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
534 (kill-all-local-variables)
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
535 @end group
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
536 @group
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
537 (use-local-map lisp-mode-map) ; @r{Select the mode's keymap.}
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
538 (setq major-mode 'lisp-mode) ; @r{This is how @code{describe-mode}}
6451
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
539 ; @r{finds out what to describe.}
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
540 (setq mode-name "Lisp") ; @r{This goes into the mode line.}
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
541 (lisp-mode-variables t) ; @r{This defines various variables.}
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
542 @end group
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
543 @group
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
544 (setq imenu-case-fold-search t)
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
545 (set-syntax-table lisp-mode-syntax-table)
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
546 (run-hooks 'lisp-mode-hook)) ; @r{This permits the user to use a}
6451
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
547 ; @r{hook to customize the mode.}
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
548 @end group
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
549 @end smallexample
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
550
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
551 @node Auto Major Mode
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
552 @subsection How Emacs Chooses a Major Mode
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
553
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
554 Based on information in the file name or in the file itself, Emacs
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
555 automatically selects a major mode for the new buffer when a file is
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
556 visited. It also processes local variables specified in the file text.
6451
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
557
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
558 @deffn Command fundamental-mode
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
559 Fundamental mode is a major mode that is not specialized for anything
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
560 in particular. Other major modes are defined in effect by comparison
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
561 with this one---their definitions say what to change, starting from
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
562 Fundamental mode. The @code{fundamental-mode} function does @emph{not}
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
563 run any hooks; you're not supposed to customize it. (If you want Emacs
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
564 to behave differently in Fundamental mode, change the @emph{global}
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
565 state of Emacs.)
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
566 @end deffn
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
567
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
568 @deffn Command normal-mode &optional find-file
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
569 This function establishes the proper major mode and buffer-local variable
6451
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
570 bindings for the current buffer. First it calls @code{set-auto-mode},
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
571 then it runs @code{hack-local-variables} to parse, and bind or
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
572 evaluate as appropriate, the file's local variables.
6451
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
573
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
574 If the @var{find-file} argument to @code{normal-mode} is non-@code{nil},
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
575 @code{normal-mode} assumes that the @code{find-file} function is calling
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
576 it. In this case, it may process a local variables list at the end of
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
577 the file and in the @samp{-*-} line. The variable
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
578 @code{enable-local-variables} controls whether to do so. @xref{File
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
579 variables, , Local Variables in Files, emacs, The GNU Emacs Manual}, for
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
580 the syntax of the local variables section of a file.
6451
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
581
12098
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
582 If you run @code{normal-mode} interactively, the argument
6451
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
583 @var{find-file} is normally @code{nil}. In this case,
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
584 @code{normal-mode} unconditionally processes any local variables list.
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
585
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
586 @cindex file mode specification error
12098
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
587 @code{normal-mode} uses @code{condition-case} around the call to the
6451
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
588 major mode function, so errors are caught and reported as a @samp{File
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
589 mode specification error}, followed by the original error message.
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
590 @end deffn
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
591
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
592 @defun set-auto-mode
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
593 @cindex visited file mode
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
594 This function selects the major mode that is appropriate for the
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
595 current buffer. It may base its decision on the value of the @w{@samp{-*-}}
12888
684378ed4f45 Fix typos.
Richard M. Stallman <rms@gnu.org>
parents: 12803
diff changeset
596 line, on the visited file name (using @code{auto-mode-alist}), on the
684378ed4f45 Fix typos.
Richard M. Stallman <rms@gnu.org>
parents: 12803
diff changeset
597 @w{@samp{#!}} line (using @code{interpreter-mode-alist}), or on the
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
598 file's local variables list. However, this function does not look for
6451
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
599 the @samp{mode:} local variable near the end of a file; the
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
600 @code{hack-local-variables} function does that. @xref{Choosing Modes, ,
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
601 How Major Modes are Chosen, emacs, The GNU Emacs Manual}.
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
602 @end defun
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
603
49600
23a1cea22d13 Trailing whitespace deleted.
Juanma Barranquero <lekktu@gmail.com>
parents: 48700
diff changeset
604 @defopt default-major-mode
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
605 This variable holds the default major mode for new buffers. The
6451
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
606 standard value is @code{fundamental-mode}.
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
607
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
608 If the value of @code{default-major-mode} is @code{nil}, Emacs uses
6451
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
609 the (previously) current buffer's major mode for the major mode of a new
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17278
diff changeset
610 buffer. However, if that major mode symbol has a @code{mode-class}
6451
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
611 property with value @code{special}, then it is not used for new buffers;
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
612 Fundamental mode is used instead. The modes that have this property are
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
613 those such as Dired and Rmail that are useful only with text that has
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
614 been specially prepared.
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
615 @end defopt
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
616
12067
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 8960
diff changeset
617 @defun set-buffer-major-mode buffer
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 8960
diff changeset
618 This function sets the major mode of @var{buffer} to the value of
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 8960
diff changeset
619 @code{default-major-mode}. If that variable is @code{nil}, it uses
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 8960
diff changeset
620 the current buffer's major mode (if that is suitable).
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 8960
diff changeset
621
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 8960
diff changeset
622 The low-level primitives for creating buffers do not use this function,
12098
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
623 but medium-level commands such as @code{switch-to-buffer} and
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
624 @code{find-file-noselect} use it whenever they create buffers.
12067
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 8960
diff changeset
625 @end defun
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 8960
diff changeset
626
6451
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
627 @defvar initial-major-mode
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
628 @cindex @samp{*scratch*}
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
629 The value of this variable determines the major mode of the initial
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
630 @samp{*scratch*} buffer. The value should be a symbol that is a major
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17278
diff changeset
631 mode command. The default value is @code{lisp-interaction-mode}.
6451
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
632 @end defvar
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
633
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
634 @defvar auto-mode-alist
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
635 This variable contains an association list of file name patterns
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
636 (regular expressions; @pxref{Regular Expressions}) and corresponding
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17278
diff changeset
637 major mode commands. Usually, the file name patterns test for suffixes,
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17278
diff changeset
638 such as @samp{.el} and @samp{.c}, but this need not be the case. An
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17278
diff changeset
639 ordinary element of the alist looks like @code{(@var{regexp} .
6451
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
640 @var{mode-function})}.
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
641
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
642 For example,
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
643
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
644 @smallexample
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
645 @group
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
646 (("\\`/tmp/fol/" . text-mode)
8505
d3f7cadf8c95 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 8016
diff changeset
647 ("\\.texinfo\\'" . texinfo-mode)
d3f7cadf8c95 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 8016
diff changeset
648 ("\\.texi\\'" . texinfo-mode)
6451
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
649 @end group
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
650 @group
8505
d3f7cadf8c95 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 8016
diff changeset
651 ("\\.el\\'" . emacs-lisp-mode)
49600
23a1cea22d13 Trailing whitespace deleted.
Juanma Barranquero <lekktu@gmail.com>
parents: 48700
diff changeset
652 ("\\.c\\'" . c-mode)
8505
d3f7cadf8c95 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 8016
diff changeset
653 ("\\.h\\'" . c-mode)
6451
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
654 @dots{})
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
655 @end group
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
656 @end smallexample
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
657
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
658 When you visit a file whose expanded file name (@pxref{File Name
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
659 Expansion}) matches a @var{regexp}, @code{set-auto-mode} calls the
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
660 corresponding @var{mode-function}. This feature enables Emacs to select
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
661 the proper major mode for most files.
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
662
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
663 If an element of @code{auto-mode-alist} has the form @code{(@var{regexp}
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
664 @var{function} t)}, then after calling @var{function}, Emacs searches
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
665 @code{auto-mode-alist} again for a match against the portion of the file
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
666 name that did not match before. This feature is useful for
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
667 uncompression packages: an entry of the form @code{("\\.gz\\'"
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
668 @var{function} t)} can uncompress the file and then put the uncompressed
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
669 file in the proper mode according to the name sans @samp{.gz}.
6451
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
670
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
671 Here is an example of how to prepend several pattern pairs to
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
672 @code{auto-mode-alist}. (You might use this sort of expression in your
25875
6a17c48b52ef *** empty log message ***
Phillip Rulon <pjr@gnu.org>
parents: 25751
diff changeset
673 init file.)
6451
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
674
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
675 @smallexample
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
676 @group
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
677 (setq auto-mode-alist
49600
23a1cea22d13 Trailing whitespace deleted.
Juanma Barranquero <lekktu@gmail.com>
parents: 48700
diff changeset
678 (append
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17278
diff changeset
679 ;; @r{File name (within directory) starts with a dot.}
49600
23a1cea22d13 Trailing whitespace deleted.
Juanma Barranquero <lekktu@gmail.com>
parents: 48700
diff changeset
680 '(("/\\.[^/]*\\'" . fundamental-mode)
7253
6ba87aed7836 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6451
diff changeset
681 ;; @r{File name has no dot.}
49600
23a1cea22d13 Trailing whitespace deleted.
Juanma Barranquero <lekktu@gmail.com>
parents: 48700
diff changeset
682 ("[^\\./]*\\'" . fundamental-mode)
7253
6ba87aed7836 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6451
diff changeset
683 ;; @r{File name ends in @samp{.C}.}
8505
d3f7cadf8c95 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 8016
diff changeset
684 ("\\.C\\'" . c++-mode))
6451
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
685 auto-mode-alist))
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
686 @end group
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
687 @end smallexample
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
688 @end defvar
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
689
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
690 @defvar interpreter-mode-alist
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17278
diff changeset
691 This variable specifies major modes to use for scripts that specify a
24934
f5e3b4ecd255 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 22274
diff changeset
692 command interpreter in a @samp{#!} line. Its value is a list of
6451
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
693 elements of the form @code{(@var{interpreter} . @var{mode})}; for
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
694 example, @code{("perl" . perl-mode)} is one element present by default.
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
695 The element says to use mode @var{mode} if the file specifies
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17278
diff changeset
696 an interpreter which matches @var{interpreter}. The value of
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17278
diff changeset
697 @var{interpreter} is actually a regular expression.
6451
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
698
7253
6ba87aed7836 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6451
diff changeset
699 This variable is applicable only when the @code{auto-mode-alist} does
6ba87aed7836 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6451
diff changeset
700 not indicate which major mode to use.
6451
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
701 @end defvar
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
702
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
703 @node Mode Help
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
704 @subsection Getting Help about a Major Mode
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
705 @cindex mode help
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
706 @cindex help for major mode
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
707 @cindex documentation for major mode
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
708
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
709 The @code{describe-mode} function is used to provide information
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
710 about major modes. It is normally called with @kbd{C-h m}. The
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
711 @code{describe-mode} function uses the value of @code{major-mode},
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
712 which is why every major mode function needs to set the
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
713 @code{major-mode} variable.
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
714
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
715 @deffn Command describe-mode
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
716 This function displays the documentation of the current major mode.
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
717
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
718 The @code{describe-mode} function calls the @code{documentation}
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
719 function using the value of @code{major-mode} as an argument. Thus, it
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
720 displays the documentation string of the major mode function.
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
721 (@xref{Accessing Documentation}.)
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
722 @end deffn
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
723
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
724 @defvar major-mode
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
725 This variable holds the symbol for the current buffer's major mode.
7253
6ba87aed7836 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6451
diff changeset
726 This symbol should have a function definition that is the command to
6451
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
727 switch to that major mode. The @code{describe-mode} function uses the
7253
6ba87aed7836 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6451
diff changeset
728 documentation string of the function as the documentation of the major
6451
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
729 mode.
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
730 @end defvar
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
731
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
732 @node Derived Modes
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
733 @subsection Defining Derived Modes
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
734
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
735 It's often useful to define a new major mode in terms of an existing
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
736 one. An easy way to do this is to use @code{define-derived-mode}.
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
737
7253
6ba87aed7836 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6451
diff changeset
738 @defmac define-derived-mode variant parent name docstring body@dots{}
6451
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
739 This construct defines @var{variant} as a major mode command, using
7253
6ba87aed7836 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6451
diff changeset
740 @var{name} as the string form of the mode name.
6451
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
741
7253
6ba87aed7836 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6451
diff changeset
742 The new command @var{variant} is defined to call the function
6ba87aed7836 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6451
diff changeset
743 @var{parent}, then override certain aspects of that parent mode:
6451
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
744
49600
23a1cea22d13 Trailing whitespace deleted.
Juanma Barranquero <lekktu@gmail.com>
parents: 48700
diff changeset
745 @itemize @bullet
6451
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
746 @item
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
747 The new mode has its own keymap, named @code{@var{variant}-map}.
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
748 @code{define-derived-mode} initializes this map to inherit from
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
749 @code{@var{parent}-map}, if it is not already set.
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
750
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
751 @item
7253
6ba87aed7836 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6451
diff changeset
752 The new mode has its own syntax table, kept in the variable
6451
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
753 @code{@var{variant}-syntax-table}.
49600
23a1cea22d13 Trailing whitespace deleted.
Juanma Barranquero <lekktu@gmail.com>
parents: 48700
diff changeset
754 @code{define-derived-mode} initializes this variable by copying
6451
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
755 @code{@var{parent}-syntax-table}, if it is not already set.
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
756
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
757 @item
7253
6ba87aed7836 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6451
diff changeset
758 The new mode has its own abbrev table, kept in the variable
6451
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
759 @code{@var{variant}-abbrev-table}.
49600
23a1cea22d13 Trailing whitespace deleted.
Juanma Barranquero <lekktu@gmail.com>
parents: 48700
diff changeset
760 @code{define-derived-mode} initializes this variable by copying
6451
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
761 @code{@var{parent}-abbrev-table}, if it is not already set.
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
762
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
763 @item
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
764 The new mode has its own mode hook, @code{@var{variant}-hook},
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
765 which it runs in standard fashion as the very last thing that it does.
49600
23a1cea22d13 Trailing whitespace deleted.
Juanma Barranquero <lekktu@gmail.com>
parents: 48700
diff changeset
766 (The new mode also runs the mode hook of @var{parent} as part
6451
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
767 of calling @var{parent}.)
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
768 @end itemize
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
769
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
770 In addition, you can specify how to override other aspects of
7253
6ba87aed7836 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6451
diff changeset
771 @var{parent} with @var{body}. The command @var{variant}
49600
23a1cea22d13 Trailing whitespace deleted.
Juanma Barranquero <lekktu@gmail.com>
parents: 48700
diff changeset
772 evaluates the forms in @var{body} after setting up all its usual
6451
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
773 overrides, just before running @code{@var{variant}-hook}.
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
774
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
775 The argument @var{docstring} specifies the documentation string for the
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
776 new mode. If you omit @var{docstring}, @code{define-derived-mode}
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
777 generates a documentation string.
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
778
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
779 Here is a hypothetical example:
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
780
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
781 @example
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
782 (define-derived-mode hypertext-mode
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
783 text-mode "Hypertext"
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
784 "Major mode for hypertext.
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
785 \\@{hypertext-mode-map@}"
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
786 (setq case-fold-search nil))
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
787
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
788 (define-key hypertext-mode-map
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
789 [down-mouse-3] 'do-hyper-link)
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
790 @end example
40928
ebfea94f75d4 Don't write explicit (interactive) in defining a derived mode.
Richard M. Stallman <rms@gnu.org>
parents: 39793
diff changeset
791
ebfea94f75d4 Don't write explicit (interactive) in defining a derived mode.
Richard M. Stallman <rms@gnu.org>
parents: 39793
diff changeset
792 Do not write an @code{interactive} spec in the definition;
ebfea94f75d4 Don't write explicit (interactive) in defining a derived mode.
Richard M. Stallman <rms@gnu.org>
parents: 39793
diff changeset
793 @code{define-derived-mode} does that automatically.
6451
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
794 @end defmac
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
795
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
796 @node Minor Modes
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
797 @section Minor Modes
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
798 @cindex minor mode
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
799
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
800 A @dfn{minor mode} provides features that users may enable or disable
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
801 independently of the choice of major mode. Minor modes can be enabled
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
802 individually or in combination. Minor modes would be better named
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
803 ``generally available, optional feature modes,'' except that such a name
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
804 would be unwieldy.
6451
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
805
25751
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 24934
diff changeset
806 A minor mode is not usually meant as a variation of a single major mode.
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 24934
diff changeset
807 Usually they are general and can apply to many major modes. For
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
808 example, Auto Fill mode works with any major mode that permits text
6451
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
809 insertion. To be general, a minor mode must be effectively independent
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
810 of the things major modes do.
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
811
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
812 A minor mode is often much more difficult to implement than a major
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
813 mode. One reason is that you should be able to activate and deactivate
7253
6ba87aed7836 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6451
diff changeset
814 minor modes in any order. A minor mode should be able to have its
6ba87aed7836 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6451
diff changeset
815 desired effect regardless of the major mode and regardless of the other
6ba87aed7836 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6451
diff changeset
816 minor modes in effect.
6451
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
817
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
818 Often the biggest problem in implementing a minor mode is finding a
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
819 way to insert the necessary hook into the rest of Emacs. Minor mode
12098
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
820 keymaps make this easier than it used to be.
6451
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
821
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
822 @menu
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
823 * Minor Mode Conventions:: Tips for writing a minor mode.
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
824 * Keymaps and Minor Modes:: How a minor mode can have its own keymap.
26696
ef5e7bbe6f19 Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents: 26211
diff changeset
825 * Defining Minor Modes:: A convenient facility for defining minor modes.
6451
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
826 @end menu
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
827
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
828 @node Minor Mode Conventions
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
829 @subsection Conventions for Writing Minor Modes
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
830 @cindex minor mode conventions
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
831 @cindex conventions for writing minor modes
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
832
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
833 There are conventions for writing minor modes just as there are for
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
834 major modes. Several of the major mode conventions apply to minor
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
835 modes as well: those regarding the name of the mode initialization
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
836 function, the names of global symbols, and the use of keymaps and
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
837 other tables.
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
838
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
839 In addition, there are several conventions that are specific to
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
840 minor modes.
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
841
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
842 @itemize @bullet
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
843 @item
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
844 @cindex mode variable
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
845 Make a variable whose name ends in @samp{-mode} to control the minor
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
846 mode. We call this the @dfn{mode variable}. The minor mode command
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
847 should set this variable (@code{nil} to disable; anything else to
22252
40089afa2b1d *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22138
diff changeset
848 enable).
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
849
25751
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 24934
diff changeset
850 If possible, implement the mode so that setting the variable
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
851 automatically enables or disables the mode. Then the minor mode command
22252
40089afa2b1d *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22138
diff changeset
852 does not need to do anything except set the variable.
6451
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
853
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
854 This variable is used in conjunction with the @code{minor-mode-alist} to
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
855 display the minor mode name in the mode line. It can also enable
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
856 or disable a minor mode keymap. Individual commands or hooks can also
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
857 check the variable's value.
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
858
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
859 If you want the minor mode to be enabled separately in each buffer,
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
860 make the variable buffer-local.
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
861
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
862 @item
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
863 Define a command whose name is the same as the mode variable.
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
864 Its job is to enable and disable the mode by setting the variable.
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
865
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
866 The command should accept one optional argument. If the argument is
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
867 @code{nil}, it should toggle the mode (turn it on if it is off, and off
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
868 if it is on). Otherwise, it should turn the mode on if the argument is
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
869 a positive integer, a symbol other than @code{nil} or @code{-}, or a
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
870 list whose @sc{car} is such an integer or symbol; it should turn the
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
871 mode off otherwise.
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
872
12098
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
873 Here is an example taken from the definition of @code{transient-mark-mode}.
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
874 It shows the use of @code{transient-mark-mode} as a variable that enables or
7253
6ba87aed7836 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6451
diff changeset
875 disables the mode's behavior, and also shows the proper way to toggle,
6ba87aed7836 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6451
diff changeset
876 enable or disable the minor mode based on the raw prefix argument value.
6451
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
877
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
878 @smallexample
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
879 @group
12098
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
880 (setq transient-mark-mode
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
881 (if (null arg) (not transient-mark-mode)
6451
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
882 (> (prefix-numeric-value arg) 0)))
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
883 @end group
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
884 @end smallexample
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
885
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
886 @item
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
887 Add an element to @code{minor-mode-alist} for each minor mode
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
888 (@pxref{Mode Line Variables}), if you want to indicate the minor mode in
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
889 the mode line. This element should be a list of the following form:
6451
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
890
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
891 @smallexample
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
892 (@var{mode-variable} @var{string})
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
893 @end smallexample
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
894
7253
6ba87aed7836 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6451
diff changeset
895 Here @var{mode-variable} is the variable that controls enabling of the
6451
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
896 minor mode, and @var{string} is a short string, starting with a space,
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
897 to represent the mode in the mode line. These strings must be short so
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
898 that there is room for several of them at once.
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
899
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
900 When you add an element to @code{minor-mode-alist}, use @code{assq} to
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
901 check for an existing element, to avoid duplication. For example:
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
902
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
903 @smallexample
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
904 @group
25875
6a17c48b52ef *** empty log message ***
Phillip Rulon <pjr@gnu.org>
parents: 25751
diff changeset
905 (unless (assq 'leif-mode minor-mode-alist)
6a17c48b52ef *** empty log message ***
Phillip Rulon <pjr@gnu.org>
parents: 25751
diff changeset
906 (setq minor-mode-alist
6a17c48b52ef *** empty log message ***
Phillip Rulon <pjr@gnu.org>
parents: 25751
diff changeset
907 (cons '(leif-mode " Leif") minor-mode-alist)))
6a17c48b52ef *** empty log message ***
Phillip Rulon <pjr@gnu.org>
parents: 25751
diff changeset
908 @end group
6a17c48b52ef *** empty log message ***
Phillip Rulon <pjr@gnu.org>
parents: 25751
diff changeset
909 @end smallexample
6a17c48b52ef *** empty log message ***
Phillip Rulon <pjr@gnu.org>
parents: 25751
diff changeset
910
6a17c48b52ef *** empty log message ***
Phillip Rulon <pjr@gnu.org>
parents: 25751
diff changeset
911 @noindent
6a17c48b52ef *** empty log message ***
Phillip Rulon <pjr@gnu.org>
parents: 25751
diff changeset
912 or like this, using @code{add-to-list} (@pxref{Setting Variables}):
6a17c48b52ef *** empty log message ***
Phillip Rulon <pjr@gnu.org>
parents: 25751
diff changeset
913
6a17c48b52ef *** empty log message ***
Phillip Rulon <pjr@gnu.org>
parents: 25751
diff changeset
914 @smallexample
6a17c48b52ef *** empty log message ***
Phillip Rulon <pjr@gnu.org>
parents: 25751
diff changeset
915 @group
6a17c48b52ef *** empty log message ***
Phillip Rulon <pjr@gnu.org>
parents: 25751
diff changeset
916 (add-to-list 'minor-mode-alist '(leif-mode " Leif"))
6451
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
917 @end group
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
918 @end smallexample
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
919 @end itemize
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
920
25751
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 24934
diff changeset
921 Global minor modes distributed with Emacs should if possible support
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 24934
diff changeset
922 enabling and disabling via Custom (@pxref{Customization}). To do this,
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 24934
diff changeset
923 the first step is to define the mode variable with @code{defcustom}, and
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 24934
diff changeset
924 specify @code{:type boolean}.
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 24934
diff changeset
925
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 24934
diff changeset
926 If just setting the variable is not sufficient to enable the mode, you
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 24934
diff changeset
927 should also specify a @code{:set} method which enables the mode by
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 24934
diff changeset
928 invoke the mode command. Note in the variable's documentation string that
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 24934
diff changeset
929 setting the variable other than via Custom may not take effect.
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 24934
diff changeset
930
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 24934
diff changeset
931 Also mark the definition with an autoload cookie (@pxref{Autoload}),
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 24934
diff changeset
932 and specify a @code{:require} so that customizing the variable will load
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 24934
diff changeset
933 the library that defines the mode. This will copy suitable definitions
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 24934
diff changeset
934 into @file{loaddefs.el} so that users can use @code{customize-option} to
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 24934
diff changeset
935 enable the mode. For example:
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 24934
diff changeset
936
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 24934
diff changeset
937 @smallexample
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 24934
diff changeset
938 @group
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 24934
diff changeset
939
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 24934
diff changeset
940 ;;;###autoload
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 24934
diff changeset
941 (defcustom msb-mode nil
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 24934
diff changeset
942 "Toggle msb-mode.
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 24934
diff changeset
943 Setting this variable directly does not take effect;
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 24934
diff changeset
944 use either \\[customize] or the function `msb-mode'."
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 24934
diff changeset
945 :set (lambda (symbol value)
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 24934
diff changeset
946 (msb-mode (or value 0)))
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 24934
diff changeset
947 :initialize 'custom-initialize-default
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 24934
diff changeset
948 :version "20.4"
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 24934
diff changeset
949 :type 'boolean
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 24934
diff changeset
950 :group 'msb
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 24934
diff changeset
951 :require 'msb)
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 24934
diff changeset
952 @end group
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 24934
diff changeset
953 @end smallexample
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 24934
diff changeset
954
6451
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
955 @node Keymaps and Minor Modes
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
956 @subsection Keymaps and Minor Modes
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
957
12098
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
958 Each minor mode can have its own keymap, which is active when the mode
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
959 is enabled. To set up a keymap for a minor mode, add an element to the
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
960 alist @code{minor-mode-map-alist}. @xref{Active Keymaps}.
6451
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
961
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
962 @cindex @code{self-insert-command}, minor modes
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17278
diff changeset
963 One use of minor mode keymaps is to modify the behavior of certain
6451
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
964 self-inserting characters so that they do something else as well as
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
965 self-insert. In general, this is the only way to do that, since the
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
966 facilities for customizing @code{self-insert-command} are limited to
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
967 special cases (designed for abbrevs and Auto Fill mode). (Do not try
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
968 substituting your own definition of @code{self-insert-command} for the
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
969 standard one. The editor command loop handles this function specially.)
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
970
17278
8ed8412c1ce7 Document key binding conventions for major modes and minor modes.
Richard M. Stallman <rms@gnu.org>
parents: 16432
diff changeset
971 The key sequences bound in a minor mode should consist of @kbd{C-c}
8ed8412c1ce7 Document key binding conventions for major modes and minor modes.
Richard M. Stallman <rms@gnu.org>
parents: 16432
diff changeset
972 followed by a punctuation character @emph{other than} @kbd{@{},
25751
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 24934
diff changeset
973 @kbd{@}}, @kbd{<}, @kbd{>}, @kbd{:}, and @kbd{;}. (Those few punctuation
17278
8ed8412c1ce7 Document key binding conventions for major modes and minor modes.
Richard M. Stallman <rms@gnu.org>
parents: 16432
diff changeset
974 characters are reserved for major modes.)
8ed8412c1ce7 Document key binding conventions for major modes and minor modes.
Richard M. Stallman <rms@gnu.org>
parents: 16432
diff changeset
975
26696
ef5e7bbe6f19 Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents: 26211
diff changeset
976 @node Defining Minor Modes
ef5e7bbe6f19 Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents: 26211
diff changeset
977 @subsection Defining Minor Modes
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17278
diff changeset
978
26696
ef5e7bbe6f19 Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents: 26211
diff changeset
979 The macro @code{define-minor-mode} offers a convenient way of
ef5e7bbe6f19 Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents: 26211
diff changeset
980 implementing a mode in one self-contained definition. It supports only
25751
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 24934
diff changeset
981 buffer-local minor modes, not global ones.
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17278
diff changeset
982
26696
ef5e7bbe6f19 Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents: 26211
diff changeset
983 @defmac define-minor-mode mode doc &optional init-value mode-indicator keymap body...
ef5e7bbe6f19 Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents: 26211
diff changeset
984 @tindex define-minor-mode
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17278
diff changeset
985 This macro defines a new minor mode whose name is @var{mode} (a symbol).
26696
ef5e7bbe6f19 Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents: 26211
diff changeset
986 It defines a command named @var{mode} to toggle the minor
ef5e7bbe6f19 Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents: 26211
diff changeset
987 mode, with @var{doc} as its documentation string. It also defines a
ef5e7bbe6f19 Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents: 26211
diff changeset
988 variable named @var{mode}, which is set to @code{t} or @code{nil} by
ef5e7bbe6f19 Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents: 26211
diff changeset
989 enabling or disabling the mode. The variable is initialized to
ef5e7bbe6f19 Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents: 26211
diff changeset
990 @var{init-value}.
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17278
diff changeset
991
26696
ef5e7bbe6f19 Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents: 26211
diff changeset
992 The command named @var{mode} finishes by executing the @var{body} forms,
ef5e7bbe6f19 Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents: 26211
diff changeset
993 if any, after it has performed the standard actions such as setting
ef5e7bbe6f19 Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents: 26211
diff changeset
994 the variable named @var{mode}.
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17278
diff changeset
995
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17278
diff changeset
996 The string @var{mode-indicator} says what to display in the mode line
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17278
diff changeset
997 when the mode is enabled; if it is @code{nil}, the mode is not displayed
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17278
diff changeset
998 in the mode line.
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17278
diff changeset
999
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17278
diff changeset
1000 The optional argument @var{keymap} specifies the keymap for the minor mode.
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17278
diff changeset
1001 It can be a variable name, whose value is the keymap, or it can be an alist
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17278
diff changeset
1002 specifying bindings in this form:
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17278
diff changeset
1003
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17278
diff changeset
1004 @example
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17278
diff changeset
1005 (@var{key-sequence} . @var{definition})
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17278
diff changeset
1006 @end example
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17278
diff changeset
1007 @end defmac
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17278
diff changeset
1008
26696
ef5e7bbe6f19 Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents: 26211
diff changeset
1009 Here is an example of using @code{define-minor-mode}:
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17278
diff changeset
1010
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17278
diff changeset
1011 @smallexample
26696
ef5e7bbe6f19 Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents: 26211
diff changeset
1012 (define-minor-mode hungry-mode
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1013 "Toggle Hungry mode.
49600
23a1cea22d13 Trailing whitespace deleted.
Juanma Barranquero <lekktu@gmail.com>
parents: 48700
diff changeset
1014 With no argument, this command toggles the mode.
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17278
diff changeset
1015 Non-null prefix argument turns on the mode.
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17278
diff changeset
1016 Null prefix argument turns off the mode.
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17278
diff changeset
1017
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17278
diff changeset
1018 When Hungry mode is enabled, the control delete key
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17278
diff changeset
1019 gobbles all preceding whitespace except the last.
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17278
diff changeset
1020 See the command \\[hungry-electric-delete]."
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17278
diff changeset
1021 ;; The initial value.
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17278
diff changeset
1022 nil
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17278
diff changeset
1023 ;; The indicator for the mode line.
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17278
diff changeset
1024 " Hungry"
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17278
diff changeset
1025 ;; The minor mode bindings.
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17278
diff changeset
1026 '(("\C-\^?" . hungry-electric-delete)
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17278
diff changeset
1027 ("\C-\M-\^?"
49600
23a1cea22d13 Trailing whitespace deleted.
Juanma Barranquero <lekktu@gmail.com>
parents: 48700
diff changeset
1028 . (lambda ()
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17278
diff changeset
1029 (interactive)
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17278
diff changeset
1030 (hungry-electric-delete t)))))
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17278
diff changeset
1031 @end smallexample
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17278
diff changeset
1032
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17278
diff changeset
1033 @noindent
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17278
diff changeset
1034 This defines a minor mode named ``Hungry mode'', a command named
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17278
diff changeset
1035 @code{hungry-mode} to toggle it, a variable named @code{hungry-mode}
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17278
diff changeset
1036 which indicates whether the mode is enabled, and a variable named
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17278
diff changeset
1037 @code{hungry-mode-map} which holds the keymap that is active when the
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17278
diff changeset
1038 mode is enabled. It initializes the keymap with key bindings for
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17278
diff changeset
1039 @kbd{C-@key{DEL}} and @kbd{C-M-@key{DEL}}.
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17278
diff changeset
1040
26696
ef5e7bbe6f19 Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents: 26211
diff changeset
1041
ef5e7bbe6f19 Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents: 26211
diff changeset
1042 @findex easy-mmode-define-minor-mode
ef5e7bbe6f19 Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents: 26211
diff changeset
1043 The name @code{easy-mmode-define-minor-mode} is an alias
ef5e7bbe6f19 Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents: 26211
diff changeset
1044 for this macro.
ef5e7bbe6f19 Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents: 26211
diff changeset
1045
6451
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1046 @node Mode Line Format
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1047 @section Mode Line Format
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1048 @cindex mode line
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1049
25751
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 24934
diff changeset
1050 Each Emacs window (aside from minibuffer windows) typically has a mode
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 24934
diff changeset
1051 line at the bottom, which displays status information about the buffer
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 24934
diff changeset
1052 displayed in the window. The mode line contains information about the
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 24934
diff changeset
1053 buffer, such as its name, associated file, depth of recursive editing,
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 24934
diff changeset
1054 and major and minor modes. A window can also have a @dfn{header
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 24934
diff changeset
1055 line}, which is much like the mode line but appears at the top of the
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 24934
diff changeset
1056 window (starting in Emacs 21).
6451
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1057
25751
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 24934
diff changeset
1058 This section describes how to control the contents of the mode line
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 24934
diff changeset
1059 and header line. We include it in this chapter because much of the
6451
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1060 information displayed in the mode line relates to the enabled major and
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1061 minor modes.
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1062
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1063 @code{mode-line-format} is a buffer-local variable that holds a
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1064 template used to display the mode line of the current buffer. All
25751
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 24934
diff changeset
1065 windows for the same buffer use the same @code{mode-line-format}, so
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 24934
diff changeset
1066 their mode lines appear the same---except for scrolling percentages, and
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 24934
diff changeset
1067 line and column numbers, since those depend on point and on how the
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 24934
diff changeset
1068 window is scrolled. @code{header-line-format} is used likewise for
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 24934
diff changeset
1069 header lines.
6451
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1070
42296
7b9a0bcca3c2 Explain mode line redisplay better.
Richard M. Stallman <rms@gnu.org>
parents: 41938
diff changeset
1071 For efficiency, Emacs does not recompute the mode line and header
7b9a0bcca3c2 Explain mode line redisplay better.
Richard M. Stallman <rms@gnu.org>
parents: 41938
diff changeset
1072 line of a window in every redisplay. It does so when circumstances
7b9a0bcca3c2 Explain mode line redisplay better.
Richard M. Stallman <rms@gnu.org>
parents: 41938
diff changeset
1073 appear to call for it---for instance, if you change the window
7b9a0bcca3c2 Explain mode line redisplay better.
Richard M. Stallman <rms@gnu.org>
parents: 41938
diff changeset
1074 configuration, switch buffers, narrow or widen the buffer, scroll, or
7b9a0bcca3c2 Explain mode line redisplay better.
Richard M. Stallman <rms@gnu.org>
parents: 41938
diff changeset
1075 change the buffer's modification status. If you modify any of the
7b9a0bcca3c2 Explain mode line redisplay better.
Richard M. Stallman <rms@gnu.org>
parents: 41938
diff changeset
1076 variables referenced by @code{mode-line-format} (@pxref{Mode Line
7b9a0bcca3c2 Explain mode line redisplay better.
Richard M. Stallman <rms@gnu.org>
parents: 41938
diff changeset
1077 Variables}), or any other variables and data structures that affect
7b9a0bcca3c2 Explain mode line redisplay better.
Richard M. Stallman <rms@gnu.org>
parents: 41938
diff changeset
1078 how text is displayed (@pxref{Display}), you may want to force an
7b9a0bcca3c2 Explain mode line redisplay better.
Richard M. Stallman <rms@gnu.org>
parents: 41938
diff changeset
1079 update of the mode line so as to display the new information or
7b9a0bcca3c2 Explain mode line redisplay better.
Richard M. Stallman <rms@gnu.org>
parents: 41938
diff changeset
1080 display it in the new way.
6451
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1081
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1082 @c Emacs 19 feature
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1083 @defun force-mode-line-update
25751
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 24934
diff changeset
1084 Force redisplay of the current buffer's mode line and header line.
42296
7b9a0bcca3c2 Explain mode line redisplay better.
Richard M. Stallman <rms@gnu.org>
parents: 41938
diff changeset
1085 The next redisplay will update the mode line and header line based on
7b9a0bcca3c2 Explain mode line redisplay better.
Richard M. Stallman <rms@gnu.org>
parents: 41938
diff changeset
1086 the latest values of all relevant variables.
7b9a0bcca3c2 Explain mode line redisplay better.
Richard M. Stallman <rms@gnu.org>
parents: 41938
diff changeset
1087
7b9a0bcca3c2 Explain mode line redisplay better.
Richard M. Stallman <rms@gnu.org>
parents: 41938
diff changeset
1088 This function also forces recomputation of the menu bar menus
7b9a0bcca3c2 Explain mode line redisplay better.
Richard M. Stallman <rms@gnu.org>
parents: 41938
diff changeset
1089 and the frame title.
6451
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1090 @end defun
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1091
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1092 The mode line is usually displayed in inverse video; see
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1093 @code{mode-line-inverse-video} in @ref{Inverse Video}.
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1094
42866
03dd2df2b595 (Mode Line Format): Short windows can suppress the mode line and header line.
Richard M. Stallman <rms@gnu.org>
parents: 42296
diff changeset
1095 A window that is just one line tall does not display either a mode
03dd2df2b595 (Mode Line Format): Short windows can suppress the mode line and header line.
Richard M. Stallman <rms@gnu.org>
parents: 42296
diff changeset
1096 line or a header line, even if the variables call for one. A window
03dd2df2b595 (Mode Line Format): Short windows can suppress the mode line and header line.
Richard M. Stallman <rms@gnu.org>
parents: 42296
diff changeset
1097 that is two lines tall cannot display both a mode line and a header
03dd2df2b595 (Mode Line Format): Short windows can suppress the mode line and header line.
Richard M. Stallman <rms@gnu.org>
parents: 42296
diff changeset
1098 line at once; if the variables call for both, only the mode line
03dd2df2b595 (Mode Line Format): Short windows can suppress the mode line and header line.
Richard M. Stallman <rms@gnu.org>
parents: 42296
diff changeset
1099 actually appears.
03dd2df2b595 (Mode Line Format): Short windows can suppress the mode line and header line.
Richard M. Stallman <rms@gnu.org>
parents: 42296
diff changeset
1100
6451
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1101 @menu
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1102 * Mode Line Data:: The data structure that controls the mode line.
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1103 * Mode Line Variables:: Variables used in that data structure.
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1104 * %-Constructs:: Putting information into a mode line.
25751
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 24934
diff changeset
1105 * Properties in Mode:: Using text properties in the mode line.
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 24934
diff changeset
1106 * Header Lines:: Like a mode line, but at the top.
6451
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1107 @end menu
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1108
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1109 @node Mode Line Data
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1110 @subsection The Data Structure of the Mode Line
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1111 @cindex mode line construct
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1112
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1113 The mode line contents are controlled by a data structure of lists,
25875
6a17c48b52ef *** empty log message ***
Phillip Rulon <pjr@gnu.org>
parents: 25751
diff changeset
1114 strings, symbols, and numbers kept in buffer-local variables. The data
6a17c48b52ef *** empty log message ***
Phillip Rulon <pjr@gnu.org>
parents: 25751
diff changeset
1115 structure is called a @dfn{mode line construct}, and it is built in
6a17c48b52ef *** empty log message ***
Phillip Rulon <pjr@gnu.org>
parents: 25751
diff changeset
1116 recursive fashion out of simpler mode line constructs. The same data
6a17c48b52ef *** empty log message ***
Phillip Rulon <pjr@gnu.org>
parents: 25751
diff changeset
1117 structure is used for constructing frame titles (@pxref{Frame Titles})
6a17c48b52ef *** empty log message ***
Phillip Rulon <pjr@gnu.org>
parents: 25751
diff changeset
1118 and header lines (@pxref{Header Lines}).
6451
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1119
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1120 @defvar mode-line-format
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1121 The value of this variable is a mode line construct with overall
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1122 responsibility for the mode line format. The value of this variable
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1123 controls which other variables are used to form the mode line text, and
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1124 where they appear.
25751
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 24934
diff changeset
1125
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 24934
diff changeset
1126 If you set this variable to @code{nil} in a buffer, that buffer does not
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 24934
diff changeset
1127 have a mode line. (This feature was added in Emacs 21.)
6451
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1128 @end defvar
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1129
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1130 A mode line construct may be as simple as a fixed string of text, but
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1131 it usually specifies how to use other variables to construct the text.
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1132 Many of these variables are themselves defined to have mode line
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1133 constructs as their values.
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1134
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1135 The default value of @code{mode-line-format} incorporates the values
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1136 of variables such as @code{mode-name} and @code{minor-mode-alist}.
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17278
diff changeset
1137 Because of this, very few modes need to alter @code{mode-line-format}
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17278
diff changeset
1138 itself. For most purposes, it is sufficient to alter some of the
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17278
diff changeset
1139 variables that @code{mode-line-format} refers to.
6451
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1140
7253
6ba87aed7836 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6451
diff changeset
1141 A mode line construct may be a list, a symbol, or a string. If the
6ba87aed7836 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6451
diff changeset
1142 value is a list, each element may be a list, a symbol, or a string.
6451
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1143
25751
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 24934
diff changeset
1144 The mode line can display various faces, if the strings that control
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 24934
diff changeset
1145 it have the @code{face} property. @xref{Properties in Mode}. In
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 24934
diff changeset
1146 addition, the face @code{mode-line} is used as a default for the whole
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 24934
diff changeset
1147 mode line (@pxref{Standard Faces}).
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 24934
diff changeset
1148
6451
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1149 @table @code
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1150 @cindex percent symbol in mode line
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1151 @item @var{string}
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1152 A string as a mode line construct is displayed verbatim in the mode line
12098
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
1153 except for @dfn{@code{%}-constructs}. Decimal digits after the @samp{%}
6451
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1154 specify the field width for space filling on the right (i.e., the data
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1155 is left justified). @xref{%-Constructs}.
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1156
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1157 @item @var{symbol}
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1158 A symbol as a mode line construct stands for its value. The value of
7253
6ba87aed7836 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6451
diff changeset
1159 @var{symbol} is used as a mode line construct, in place of @var{symbol}.
25751
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 24934
diff changeset
1160 However, the symbols @code{t} and @code{nil} are ignored, as is any
7253
6ba87aed7836 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6451
diff changeset
1161 symbol whose value is void.
6451
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1162
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1163 There is one exception: if the value of @var{symbol} is a string, it is
7253
6ba87aed7836 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6451
diff changeset
1164 displayed verbatim: the @code{%}-constructs are not recognized.
6451
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1165
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1166 @item (@var{string} @var{rest}@dots{}) @r{or} (@var{list} @var{rest}@dots{})
7253
6ba87aed7836 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6451
diff changeset
1167 A list whose first element is a string or list means to process all the
6ba87aed7836 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6451
diff changeset
1168 elements recursively and concatenate the results. This is the most
6ba87aed7836 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6451
diff changeset
1169 common form of mode line construct.
6451
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1170
25751
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 24934
diff changeset
1171 @item (:eval @var{form})
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 24934
diff changeset
1172 A list whose first element is the symbol @code{:eval} says to evaluate
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 24934
diff changeset
1173 @var{form}, and use the result as a string to display.
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 24934
diff changeset
1174 (This feature is new as of Emacs 21.)
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 24934
diff changeset
1175
6451
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1176 @item (@var{symbol} @var{then} @var{else})
25751
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 24934
diff changeset
1177 A list whose first element is a symbol that is not a keyword specifies a
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 24934
diff changeset
1178 conditional. Its meaning depends on the value of @var{symbol}. If the
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 24934
diff changeset
1179 value is non-@code{nil}, the second element, @var{then}, is processed
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 24934
diff changeset
1180 recursively as a mode line element. But if the value of @var{symbol} is
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 24934
diff changeset
1181 @code{nil}, the third element, @var{else}, is processed recursively.
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 24934
diff changeset
1182 You may omit @var{else}; then the mode line element displays nothing if
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 24934
diff changeset
1183 the value of @var{symbol} is @code{nil}.
6451
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1184
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1185 @item (@var{width} @var{rest}@dots{})
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1186 A list whose first element is an integer specifies truncation or
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1187 padding of the results of @var{rest}. The remaining elements
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1188 @var{rest} are processed recursively as mode line constructs and
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1189 concatenated together. Then the result is space filled (if
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1190 @var{width} is positive) or truncated (to @minus{}@var{width} columns,
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1191 if @var{width} is negative) on the right.
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1192
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1193 For example, the usual way to show what percentage of a buffer is above
7253
6ba87aed7836 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6451
diff changeset
1194 the top of the window is to use a list like this: @code{(-3 "%p")}.
6451
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1195 @end table
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1196
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1197 If you do alter @code{mode-line-format} itself, the new value should
7253
6ba87aed7836 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6451
diff changeset
1198 use the same variables that appear in the default value (@pxref{Mode
6ba87aed7836 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6451
diff changeset
1199 Line Variables}), rather than duplicating their contents or displaying
6ba87aed7836 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6451
diff changeset
1200 the information in another fashion. This way, customizations made by
12098
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
1201 the user or by Lisp programs (such as @code{display-time} and major
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
1202 modes) via changes to those variables remain effective.
6451
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1203
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1204 @cindex Shell mode @code{mode-line-format}
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1205 Here is an example of a @code{mode-line-format} that might be
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1206 useful for @code{shell-mode}, since it contains the host name and default
6451
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1207 directory.
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1208
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1209 @example
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1210 @group
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1211 (setq mode-line-format
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1212 (list "-"
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1213 'mode-line-mule-info
6451
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1214 'mode-line-modified
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1215 'mode-line-frame-identification
49600
23a1cea22d13 Trailing whitespace deleted.
Juanma Barranquero <lekktu@gmail.com>
parents: 48700
diff changeset
1216 "%b--"
6451
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1217 @end group
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17278
diff changeset
1218 @group
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17278
diff changeset
1219 ;; @r{Note that this is evaluated while making the list.}
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17278
diff changeset
1220 ;; @r{It makes a mode line construct which is just a string.}
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17278
diff changeset
1221 (getenv "HOST")
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17278
diff changeset
1222 @end group
49600
23a1cea22d13 Trailing whitespace deleted.
Juanma Barranquero <lekktu@gmail.com>
parents: 48700
diff changeset
1223 ":"
6451
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1224 'default-directory
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1225 " "
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1226 'global-mode-string
7253
6ba87aed7836 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6451
diff changeset
1227 " %[("
25751
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 24934
diff changeset
1228 '(:eval (mode-line-mode-name))
49600
23a1cea22d13 Trailing whitespace deleted.
Juanma Barranquero <lekktu@gmail.com>
parents: 48700
diff changeset
1229 'mode-line-process
23a1cea22d13 Trailing whitespace deleted.
Juanma Barranquero <lekktu@gmail.com>
parents: 48700
diff changeset
1230 'minor-mode-alist
23a1cea22d13 Trailing whitespace deleted.
Juanma Barranquero <lekktu@gmail.com>
parents: 48700
diff changeset
1231 "%n"
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1232 ")%]--"
6451
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1233 @group
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1234 '(which-func-mode ("" which-func-format "--"))
12098
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
1235 '(line-number-mode "L%l--")
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1236 '(column-number-mode "C%c--")
6451
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1237 '(-3 . "%p")
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1238 "-%-"))
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1239 @end group
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1240 @end example
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1241
22252
40089afa2b1d *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22138
diff changeset
1242 @noindent
40089afa2b1d *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22138
diff changeset
1243 (The variables @code{line-number-mode}, @code{column-number-mode}
40089afa2b1d *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22138
diff changeset
1244 and @code{which-func-mode} enable particular minor modes; as usual,
40089afa2b1d *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22138
diff changeset
1245 these variable names are also the minor mode command names.)
40089afa2b1d *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22138
diff changeset
1246
6451
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1247 @node Mode Line Variables
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1248 @subsection Variables Used in the Mode Line
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1249
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1250 This section describes variables incorporated by the
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1251 standard value of @code{mode-line-format} into the text of the mode
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1252 line. There is nothing inherently special about these variables; any
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1253 other variables could have the same effects on the mode line if
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1254 @code{mode-line-format} were changed to use them.
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1255
22138
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
1256 @defvar mode-line-mule-info
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1257 This variable holds the value of the mode-line construct that displays
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1258 information about the language environment, buffer coding system, and
22138
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
1259 current input method. @xref{Non-ASCII Characters}.
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1260 @end defvar
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1261
6451
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1262 @defvar mode-line-modified
7253
6ba87aed7836 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6451
diff changeset
1263 This variable holds the value of the mode-line construct that displays
6451
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1264 whether the current buffer is modified.
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1265
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1266 The default value of @code{mode-line-modified} is @code{("%1*%1+")}.
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1267 This means that the mode line displays @samp{**} if the buffer is
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1268 modified, @samp{--} if the buffer is not modified, @samp{%%} if the
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1269 buffer is read only, and @samp{%*} if the buffer is read only and
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1270 modified.
6451
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1271
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1272 Changing this variable does not force an update of the mode line.
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1273 @end defvar
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1274
22138
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
1275 @defvar mode-line-frame-identification
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1276 This variable identifies the current frame. The default value is
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1277 @code{" "} if you are using a window system which can show multiple
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1278 frames, or @code{"-%F "} on an ordinary terminal which shows only one
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1279 frame at a time.
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1280 @end defvar
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1281
6451
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1282 @defvar mode-line-buffer-identification
7253
6ba87aed7836 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6451
diff changeset
1283 This variable identifies the buffer being displayed in the window. Its
22267
dfac7398266b *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22252
diff changeset
1284 default value is @code{("%12b")}, which displays the buffer name, padded
dfac7398266b *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22252
diff changeset
1285 with spaces to at least 12 columns.
6451
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1286 @end defvar
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1287
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1288 @defvar global-mode-string
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1289 This variable holds a mode line spec that appears in the mode line by
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1290 default, just after the buffer name. The command @code{display-time}
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1291 sets @code{global-mode-string} to refer to the variable
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1292 @code{display-time-string}, which holds a string containing the time and
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1293 load information.
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1294
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1295 The @samp{%M} construct substitutes the value of
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17278
diff changeset
1296 @code{global-mode-string}, but that is obsolete, since the variable is
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17278
diff changeset
1297 included in the mode line from @code{mode-line-format}.
6451
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1298 @end defvar
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1299
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1300 @defvar mode-name
7253
6ba87aed7836 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6451
diff changeset
1301 This buffer-local variable holds the ``pretty'' name of the current
6451
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1302 buffer's major mode. Each major mode should set this variable so that the
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1303 mode name will appear in the mode line.
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1304 @end defvar
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1305
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1306 @defvar minor-mode-alist
7253
6ba87aed7836 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6451
diff changeset
1307 This variable holds an association list whose elements specify how the
6451
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1308 mode line should indicate that a minor mode is active. Each element of
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1309 the @code{minor-mode-alist} should be a two-element list:
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1310
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1311 @example
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1312 (@var{minor-mode-variable} @var{mode-line-string})
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1313 @end example
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1314
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1315 More generally, @var{mode-line-string} can be any mode line spec. It
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1316 appears in the mode line when the value of @var{minor-mode-variable} is
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1317 non-@code{nil}, and not otherwise. These strings should begin with
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1318 spaces so that they don't run together. Conventionally, the
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1319 @var{minor-mode-variable} for a specific mode is set to a non-@code{nil}
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1320 value when that minor mode is activated.
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1321
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1322 The default value of @code{minor-mode-alist} is:
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1323
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1324 @example
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1325 @group
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1326 minor-mode-alist
12098
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
1327 @result{} ((vc-mode vc-mode)
49600
23a1cea22d13 Trailing whitespace deleted.
Juanma Barranquero <lekktu@gmail.com>
parents: 48700
diff changeset
1328 (abbrev-mode " Abbrev")
23a1cea22d13 Trailing whitespace deleted.
Juanma Barranquero <lekktu@gmail.com>
parents: 48700
diff changeset
1329 (overwrite-mode overwrite-mode)
23a1cea22d13 Trailing whitespace deleted.
Juanma Barranquero <lekktu@gmail.com>
parents: 48700
diff changeset
1330 (auto-fill-function " Fill")
12098
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
1331 (defining-kbd-macro " Def")
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
1332 (isearch-mode isearch-mode))
6451
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1333 @end group
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1334 @end example
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1335
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17278
diff changeset
1336 @code{minor-mode-alist} itself is not buffer-local. Each variable
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17278
diff changeset
1337 mentioned in the alist should be buffer-local if its minor mode can be
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17278
diff changeset
1338 enabled separately in each buffer.
6451
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1339 @end defvar
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1340
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1341 @defvar mode-line-process
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1342 This buffer-local variable contains the mode line information on process
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1343 status in modes used for communicating with subprocesses. It is
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1344 displayed immediately following the major mode name, with no intervening
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1345 space. For example, its value in the @samp{*shell*} buffer is
22252
40089afa2b1d *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22138
diff changeset
1346 @code{(":%s")}, which allows the shell to display its status along
25875
6a17c48b52ef *** empty log message ***
Phillip Rulon <pjr@gnu.org>
parents: 25751
diff changeset
1347 with the major mode as: @samp{(Shell:run)}. Normally this variable
6451
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1348 is @code{nil}.
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1349 @end defvar
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1350
25875
6a17c48b52ef *** empty log message ***
Phillip Rulon <pjr@gnu.org>
parents: 25751
diff changeset
1351 Some variables are used by @code{minor-mode-alist} to display
6a17c48b52ef *** empty log message ***
Phillip Rulon <pjr@gnu.org>
parents: 25751
diff changeset
1352 a string for various minor modes when enabled. This is a typical
6a17c48b52ef *** empty log message ***
Phillip Rulon <pjr@gnu.org>
parents: 25751
diff changeset
1353 example:
6a17c48b52ef *** empty log message ***
Phillip Rulon <pjr@gnu.org>
parents: 25751
diff changeset
1354
6a17c48b52ef *** empty log message ***
Phillip Rulon <pjr@gnu.org>
parents: 25751
diff changeset
1355 @defvar vc-mode
6a17c48b52ef *** empty log message ***
Phillip Rulon <pjr@gnu.org>
parents: 25751
diff changeset
1356 The variable @code{vc-mode}, buffer-local in each buffer, records
6a17c48b52ef *** empty log message ***
Phillip Rulon <pjr@gnu.org>
parents: 25751
diff changeset
1357 whether the buffer's visited file is maintained with version control,
6a17c48b52ef *** empty log message ***
Phillip Rulon <pjr@gnu.org>
parents: 25751
diff changeset
1358 and, if so, which kind. Its value is a string that appears in the mode
6a17c48b52ef *** empty log message ***
Phillip Rulon <pjr@gnu.org>
parents: 25751
diff changeset
1359 line, or @code{nil} for no version control.
6a17c48b52ef *** empty log message ***
Phillip Rulon <pjr@gnu.org>
parents: 25751
diff changeset
1360 @end defvar
6a17c48b52ef *** empty log message ***
Phillip Rulon <pjr@gnu.org>
parents: 25751
diff changeset
1361
6a17c48b52ef *** empty log message ***
Phillip Rulon <pjr@gnu.org>
parents: 25751
diff changeset
1362 The variable @code{default-mode-line-format} is where
6a17c48b52ef *** empty log message ***
Phillip Rulon <pjr@gnu.org>
parents: 25751
diff changeset
1363 @code{mode-line-format} usually gets its value:
6a17c48b52ef *** empty log message ***
Phillip Rulon <pjr@gnu.org>
parents: 25751
diff changeset
1364
6451
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1365 @defvar default-mode-line-format
7253
6ba87aed7836 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6451
diff changeset
1366 This variable holds the default @code{mode-line-format} for buffers
6451
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1367 that do not override it. This is the same as @code{(default-value
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1368 'mode-line-format)}.
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1369
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17278
diff changeset
1370 The default value of @code{default-mode-line-format} is this list:
6451
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1371
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1372 @example
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1373 @group
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17278
diff changeset
1374 ("-"
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17278
diff changeset
1375 mode-line-mule-info
6451
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1376 mode-line-modified
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17278
diff changeset
1377 mode-line-frame-identification
6451
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1378 mode-line-buffer-identification
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17278
diff changeset
1379 @end group
6451
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1380 " "
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1381 global-mode-string
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17278
diff changeset
1382 @group
6451
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1383 " %[("
25875
6a17c48b52ef *** empty log message ***
Phillip Rulon <pjr@gnu.org>
parents: 25751
diff changeset
1384 ;; @r{@code{mode-line-mode-name} is a function}
26211
df0efa93750b Patch from rms.
Gerd Moellmann <gerd@gnu.org>
parents: 25975
diff changeset
1385 ;; @r{that copies the mode name and adds text}
25875
6a17c48b52ef *** empty log message ***
Phillip Rulon <pjr@gnu.org>
parents: 25751
diff changeset
1386 ;; @r{properties to make it mouse-sensitive.}
25751
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 24934
diff changeset
1387 (:eval (mode-line-mode-name))
12098
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
1388 mode-line-process
49600
23a1cea22d13 Trailing whitespace deleted.
Juanma Barranquero <lekktu@gmail.com>
parents: 48700
diff changeset
1389 minor-mode-alist
23a1cea22d13 Trailing whitespace deleted.
Juanma Barranquero <lekktu@gmail.com>
parents: 48700
diff changeset
1390 "%n"
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17278
diff changeset
1391 ")%]--"
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17278
diff changeset
1392 @end group
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17278
diff changeset
1393 @group
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17278
diff changeset
1394 (which-func-mode ("" which-func-format "--"))
12098
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
1395 (line-number-mode "L%l--")
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17278
diff changeset
1396 (column-number-mode "C%c--")
6451
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1397 (-3 . "%p")
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1398 "-%-")
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1399 @end group
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1400 @end example
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1401 @end defvar
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1402
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1403 @node %-Constructs
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1404 @subsection @code{%}-Constructs in the Mode Line
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1405
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1406 The following table lists the recognized @code{%}-constructs and what
7253
6ba87aed7836 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6451
diff changeset
1407 they mean. In any construct except @samp{%%}, you can add a decimal
6ba87aed7836 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6451
diff changeset
1408 integer after the @samp{%} to specify how many characters to display.
6451
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1409
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1410 @table @code
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1411 @item %b
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1412 The current buffer name, obtained with the @code{buffer-name} function.
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1413 @xref{Buffer Names}.
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1414
25875
6a17c48b52ef *** empty log message ***
Phillip Rulon <pjr@gnu.org>
parents: 25751
diff changeset
1415 @item %c
6a17c48b52ef *** empty log message ***
Phillip Rulon <pjr@gnu.org>
parents: 25751
diff changeset
1416 The current column number of point.
6a17c48b52ef *** empty log message ***
Phillip Rulon <pjr@gnu.org>
parents: 25751
diff changeset
1417
6451
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1418 @item %f
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1419 The visited file name, obtained with the @code{buffer-file-name}
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1420 function. @xref{Buffer File Name}.
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1421
12067
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 8960
diff changeset
1422 @item %F
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1423 The title (only on a window system) or the name of the selected frame.
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1424 @xref{Window Frame Parameters}.
12067
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 8960
diff changeset
1425
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 8960
diff changeset
1426 @item %l
25751
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 24934
diff changeset
1427 The current line number of point, counting within the accessible portion
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 24934
diff changeset
1428 of the buffer.
12067
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 8960
diff changeset
1429
25875
6a17c48b52ef *** empty log message ***
Phillip Rulon <pjr@gnu.org>
parents: 25751
diff changeset
1430 @item %n
6a17c48b52ef *** empty log message ***
Phillip Rulon <pjr@gnu.org>
parents: 25751
diff changeset
1431 @samp{Narrow} when narrowing is in effect; nothing otherwise (see
6a17c48b52ef *** empty log message ***
Phillip Rulon <pjr@gnu.org>
parents: 25751
diff changeset
1432 @code{narrow-to-region} in @ref{Narrowing}).
6a17c48b52ef *** empty log message ***
Phillip Rulon <pjr@gnu.org>
parents: 25751
diff changeset
1433
6a17c48b52ef *** empty log message ***
Phillip Rulon <pjr@gnu.org>
parents: 25751
diff changeset
1434 @item %p
6a17c48b52ef *** empty log message ***
Phillip Rulon <pjr@gnu.org>
parents: 25751
diff changeset
1435 The percentage of the buffer text above the @strong{top} of window, or
6a17c48b52ef *** empty log message ***
Phillip Rulon <pjr@gnu.org>
parents: 25751
diff changeset
1436 @samp{Top}, @samp{Bottom} or @samp{All}. Note that the default
6a17c48b52ef *** empty log message ***
Phillip Rulon <pjr@gnu.org>
parents: 25751
diff changeset
1437 mode-line specification truncates this to three characters.
6a17c48b52ef *** empty log message ***
Phillip Rulon <pjr@gnu.org>
parents: 25751
diff changeset
1438
6a17c48b52ef *** empty log message ***
Phillip Rulon <pjr@gnu.org>
parents: 25751
diff changeset
1439 @item %P
6a17c48b52ef *** empty log message ***
Phillip Rulon <pjr@gnu.org>
parents: 25751
diff changeset
1440 The percentage of the buffer text that is above the @strong{bottom} of
6a17c48b52ef *** empty log message ***
Phillip Rulon <pjr@gnu.org>
parents: 25751
diff changeset
1441 the window (which includes the text visible in the window, as well as
6a17c48b52ef *** empty log message ***
Phillip Rulon <pjr@gnu.org>
parents: 25751
diff changeset
1442 the text above the top), plus @samp{Top} if the top of the buffer is
6a17c48b52ef *** empty log message ***
Phillip Rulon <pjr@gnu.org>
parents: 25751
diff changeset
1443 visible on screen; or @samp{Bottom} or @samp{All}.
6a17c48b52ef *** empty log message ***
Phillip Rulon <pjr@gnu.org>
parents: 25751
diff changeset
1444
6a17c48b52ef *** empty log message ***
Phillip Rulon <pjr@gnu.org>
parents: 25751
diff changeset
1445 @item %s
6a17c48b52ef *** empty log message ***
Phillip Rulon <pjr@gnu.org>
parents: 25751
diff changeset
1446 The status of the subprocess belonging to the current buffer, obtained with
6a17c48b52ef *** empty log message ***
Phillip Rulon <pjr@gnu.org>
parents: 25751
diff changeset
1447 @code{process-status}. @xref{Process Information}.
6a17c48b52ef *** empty log message ***
Phillip Rulon <pjr@gnu.org>
parents: 25751
diff changeset
1448
6a17c48b52ef *** empty log message ***
Phillip Rulon <pjr@gnu.org>
parents: 25751
diff changeset
1449 @item %t
6a17c48b52ef *** empty log message ***
Phillip Rulon <pjr@gnu.org>
parents: 25751
diff changeset
1450 Whether the visited file is a text file or a binary file. This is a
6a17c48b52ef *** empty log message ***
Phillip Rulon <pjr@gnu.org>
parents: 25751
diff changeset
1451 meaningful distinction only on certain operating systems (@pxref{MS-DOS
6a17c48b52ef *** empty log message ***
Phillip Rulon <pjr@gnu.org>
parents: 25751
diff changeset
1452 File Types}).
6a17c48b52ef *** empty log message ***
Phillip Rulon <pjr@gnu.org>
parents: 25751
diff changeset
1453
6451
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1454 @item %*
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1455 @samp{%} if the buffer is read only (see @code{buffer-read-only}); @*
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1456 @samp{*} if the buffer is modified (see @code{buffer-modified-p}); @*
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1457 @samp{-} otherwise. @xref{Buffer Modification}.
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1458
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1459 @item %+
12067
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 8960
diff changeset
1460 @samp{*} if the buffer is modified (see @code{buffer-modified-p}); @*
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 8960
diff changeset
1461 @samp{%} if the buffer is read only (see @code{buffer-read-only}); @*
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 8960
diff changeset
1462 @samp{-} otherwise. This differs from @samp{%*} only for a modified
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 8960
diff changeset
1463 read-only buffer. @xref{Buffer Modification}.
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 8960
diff changeset
1464
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 8960
diff changeset
1465 @item %&
7253
6ba87aed7836 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6451
diff changeset
1466 @samp{*} if the buffer is modified, and @samp{-} otherwise.
6451
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1467
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1468 @item %[
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1469 An indication of the depth of recursive editing levels (not counting
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1470 minibuffer levels): one @samp{[} for each editing level.
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1471 @xref{Recursive Editing}.
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1472
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1473 @item %]
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1474 One @samp{]} for each recursive editing level (not counting minibuffer
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1475 levels).
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1476
25875
6a17c48b52ef *** empty log message ***
Phillip Rulon <pjr@gnu.org>
parents: 25751
diff changeset
1477 @item %-
6a17c48b52ef *** empty log message ***
Phillip Rulon <pjr@gnu.org>
parents: 25751
diff changeset
1478 Dashes sufficient to fill the remainder of the mode line.
6a17c48b52ef *** empty log message ***
Phillip Rulon <pjr@gnu.org>
parents: 25751
diff changeset
1479
6451
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1480 @item %%
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1481 The character @samp{%}---this is how to include a literal @samp{%} in a
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1482 string in which @code{%}-constructs are allowed.
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1483 @end table
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1484
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1485 The following two @code{%}-constructs are still supported, but they are
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1486 obsolete, since you can get the same results with the variables
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1487 @code{mode-name} and @code{global-mode-string}.
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1488
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1489 @table @code
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1490 @item %m
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1491 The value of @code{mode-name}.
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1492
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1493 @item %M
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1494 The value of @code{global-mode-string}. Currently, only
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1495 @code{display-time} modifies the value of @code{global-mode-string}.
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1496 @end table
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1497
25751
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 24934
diff changeset
1498 @node Properties in Mode
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 24934
diff changeset
1499 @subsection Properties in the Mode Line
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 24934
diff changeset
1500
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 24934
diff changeset
1501 Starting in Emacs 21, certain text properties are meaningful in the
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 24934
diff changeset
1502 mode line. The @code{face} property affects the appearance of text; the
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 24934
diff changeset
1503 @code{help-echo} property associate help strings with the text, and
29102
ba9cfbfc601e *** empty log message ***
Gerd Moellmann <gerd@gnu.org>
parents: 29076
diff changeset
1504 @code{local-map} can make the text mouse-sensitive.
25751
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 24934
diff changeset
1505
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 24934
diff changeset
1506 There are three ways to specify text properties for text in the mode
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 24934
diff changeset
1507 line:
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 24934
diff changeset
1508
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 24934
diff changeset
1509 @enumerate
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 24934
diff changeset
1510 @item
29102
ba9cfbfc601e *** empty log message ***
Gerd Moellmann <gerd@gnu.org>
parents: 29076
diff changeset
1511 Put a string with the @code{local-map} property directly into the
ba9cfbfc601e *** empty log message ***
Gerd Moellmann <gerd@gnu.org>
parents: 29076
diff changeset
1512 mode-line data structure.
25751
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 24934
diff changeset
1513
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 24934
diff changeset
1514 @item
29102
ba9cfbfc601e *** empty log message ***
Gerd Moellmann <gerd@gnu.org>
parents: 29076
diff changeset
1515 Put a @code{local-map} property on a mode-line %-construct
ba9cfbfc601e *** empty log message ***
Gerd Moellmann <gerd@gnu.org>
parents: 29076
diff changeset
1516 such as @samp{%12b}; then the expansion of the %-construct
ba9cfbfc601e *** empty log message ***
Gerd Moellmann <gerd@gnu.org>
parents: 29076
diff changeset
1517 will have that same text property.
25751
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 24934
diff changeset
1518
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 24934
diff changeset
1519 @item
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 24934
diff changeset
1520 Use a list containing @code{:eval @var{form}} in the mode-line data
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 24934
diff changeset
1521 structure, and make @var{form} evaluate to a string that has a
29102
ba9cfbfc601e *** empty log message ***
Gerd Moellmann <gerd@gnu.org>
parents: 29076
diff changeset
1522 @code{local-map} property.
25751
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 24934
diff changeset
1523 @end enumerate
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 24934
diff changeset
1524
29102
ba9cfbfc601e *** empty log message ***
Gerd Moellmann <gerd@gnu.org>
parents: 29076
diff changeset
1525 You use the @code{local-map} property to specify a keymap. Like any
25751
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 24934
diff changeset
1526 keymap, it can bind character keys and function keys; but that has no
25875
6a17c48b52ef *** empty log message ***
Phillip Rulon <pjr@gnu.org>
parents: 25751
diff changeset
1527 effect, since it is impossible to move point into the mode line. This
25751
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 24934
diff changeset
1528 keymap can only take real effect for mouse clicks.
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 24934
diff changeset
1529
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 24934
diff changeset
1530 @node Header Lines
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 24934
diff changeset
1531 @subsection Window Header Lines
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 24934
diff changeset
1532 @cindex header line (of a window)
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 24934
diff changeset
1533 @cindex window header line
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 24934
diff changeset
1534
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 24934
diff changeset
1535 Starting in Emacs 21, a window can have a @dfn{header line} at the
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 24934
diff changeset
1536 top, just as it can have a mode line at the bottom. The header line
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 24934
diff changeset
1537 feature works just like the mode line feature, except that it's
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 24934
diff changeset
1538 controlled by different variables.
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 24934
diff changeset
1539
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 24934
diff changeset
1540 @tindex header-line-format
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 24934
diff changeset
1541 @defvar header-line-format
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 24934
diff changeset
1542 This variable, local in every buffer, specifies how to display the
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 24934
diff changeset
1543 header line, for windows displaying the buffer. The format of the value
26783
626ae4bb4994 Fix makeinfo complaints.
Dave Love <fx@gnu.org>
parents: 26696
diff changeset
1544 is the same as for @code{mode-line-format} (@pxref{Mode Line Data}).
25751
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 24934
diff changeset
1545 @end defvar
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 24934
diff changeset
1546
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 24934
diff changeset
1547 @tindex default-header-line-format
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 24934
diff changeset
1548 @defvar default-header-line-format
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 24934
diff changeset
1549 This variable holds the default @code{header-line-format} for buffers
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 24934
diff changeset
1550 that do not override it. This is the same as @code{(default-value
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 24934
diff changeset
1551 'header-line-format)}.
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 24934
diff changeset
1552
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 24934
diff changeset
1553 It is normally @code{nil}, so that ordinary buffers have no header line.
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 24934
diff changeset
1554 @end defvar
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 24934
diff changeset
1555
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17278
diff changeset
1556 @node Imenu
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17278
diff changeset
1557 @section Imenu
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17278
diff changeset
1558
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17278
diff changeset
1559 @cindex Imenu
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1560 @dfn{Imenu} is a feature that lets users select a definition or
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1561 section in the buffer, from a menu which lists all of them, to go
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1562 directly to that location in the buffer. Imenu works by constructing a
25751
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 24934
diff changeset
1563 buffer index which lists the names and buffer positions of the
25875
6a17c48b52ef *** empty log message ***
Phillip Rulon <pjr@gnu.org>
parents: 25751
diff changeset
1564 definitions, or other named portions of the buffer; then the user can
6a17c48b52ef *** empty log message ***
Phillip Rulon <pjr@gnu.org>
parents: 25751
diff changeset
1565 choose one of them and move point to it. This section explains how to
6a17c48b52ef *** empty log message ***
Phillip Rulon <pjr@gnu.org>
parents: 25751
diff changeset
1566 customize how Imenu finds the definitions or buffer portions for a
6a17c48b52ef *** empty log message ***
Phillip Rulon <pjr@gnu.org>
parents: 25751
diff changeset
1567 particular major mode.
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1568
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1569 The usual and simplest way is to set the variable
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1570 @code{imenu-generic-expression}:
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17278
diff changeset
1571
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17278
diff changeset
1572 @defvar imenu-generic-expression
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17278
diff changeset
1573 This variable, if non-@code{nil}, specifies regular expressions for
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17278
diff changeset
1574 finding definitions for Imenu. In the simplest case, elements should
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17278
diff changeset
1575 look like this:
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17278
diff changeset
1576
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17278
diff changeset
1577 @example
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17278
diff changeset
1578 (@var{menu-title} @var{regexp} @var{subexp})
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17278
diff changeset
1579 @end example
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17278
diff changeset
1580
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17278
diff changeset
1581 Here, if @var{menu-title} is non-@code{nil}, it says that the matches
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17278
diff changeset
1582 for this element should go in a submenu of the buffer index;
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17278
diff changeset
1583 @var{menu-title} itself specifies the name for the submenu. If
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17278
diff changeset
1584 @var{menu-title} is @code{nil}, the matches for this element go directly
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17278
diff changeset
1585 in the top level of the buffer index.
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17278
diff changeset
1586
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17278
diff changeset
1587 The second item in the list, @var{regexp}, is a regular expression
25751
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 24934
diff changeset
1588 (@pxref{Regular Expressions}); anything in the buffer that it matches is
25875
6a17c48b52ef *** empty log message ***
Phillip Rulon <pjr@gnu.org>
parents: 25751
diff changeset
1589 considered a definition, something to mention in the buffer index. The
6a17c48b52ef *** empty log message ***
Phillip Rulon <pjr@gnu.org>
parents: 25751
diff changeset
1590 third item, @var{subexp}, indicates which subexpression in @var{regexp}
25751
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 24934
diff changeset
1591 matches the definition's name.
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17278
diff changeset
1592
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17278
diff changeset
1593 An element can also look like this:
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17278
diff changeset
1594
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17278
diff changeset
1595 @example
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17278
diff changeset
1596 (@var{menu-title} @var{regexp} @var{index} @var{function} @var{arguments}@dots{})
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17278
diff changeset
1597 @end example
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17278
diff changeset
1598
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17278
diff changeset
1599 Each match for this element creates a special index item which, if
25875
6a17c48b52ef *** empty log message ***
Phillip Rulon <pjr@gnu.org>
parents: 25751
diff changeset
1600 selected by the user, calls @var{function} with arguments consisting of
6a17c48b52ef *** empty log message ***
Phillip Rulon <pjr@gnu.org>
parents: 25751
diff changeset
1601 the item name, the buffer position, and @var{arguments}.
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17278
diff changeset
1602
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17278
diff changeset
1603 For Emacs Lisp mode, @var{pattern} could look like this:
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17278
diff changeset
1604
22138
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
1605 @c should probably use imenu-syntax-alist and \\sw rather than [-A-Za-z0-9+]
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17278
diff changeset
1606 @example
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17278
diff changeset
1607 @group
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17278
diff changeset
1608 ((nil "^\\s-*(def\\(un\\|subst\\|macro\\|advice\\)\
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17278
diff changeset
1609 \\s-+\\([-A-Za-z0-9+]+\\)" 2)
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17278
diff changeset
1610 @end group
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17278
diff changeset
1611 @group
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17278
diff changeset
1612 ("*Vars*" "^\\s-*(def\\(var\\|const\\)\
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17278
diff changeset
1613 \\s-+\\([-A-Za-z0-9+]+\\)" 2)
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17278
diff changeset
1614 @end group
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17278
diff changeset
1615 @group
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17278
diff changeset
1616 ("*Types*"
22138
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
1617 "^\\s-*\
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
1618 (def\\(type\\|struct\\|class\\|ine-condition\\)\
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17278
diff changeset
1619 \\s-+\\([-A-Za-z0-9+]+\\)" 2))
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17278
diff changeset
1620 @end group
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17278
diff changeset
1621 @end example
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17278
diff changeset
1622
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1623 Setting this variable makes it buffer-local in the current buffer.
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17278
diff changeset
1624 @end defvar
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17278
diff changeset
1625
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17278
diff changeset
1626 @defvar imenu-case-fold-search
22138
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
1627 This variable controls whether matching against
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
1628 @var{imenu-generic-expression} is case-sensitive: @code{t}, the default,
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
1629 means matching should ignore case.
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
1630
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
1631 Setting this variable makes it buffer-local in the current buffer.
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
1632 @end defvar
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
1633
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
1634 @defvar imenu-syntax-alist
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
1635 This variable is an alist of syntax table modifiers to use while
22252
40089afa2b1d *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22138
diff changeset
1636 processing @code{imenu-generic-expression}, to override the syntax table
40089afa2b1d *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22138
diff changeset
1637 of the current buffer. Each element should have this form:
22138
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
1638
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
1639 @example
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
1640 (@var{characters} . @var{syntax-description})
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
1641 @end example
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
1642
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
1643 The @sc{car}, @var{characters}, can be either a character or a string.
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
1644 The element says to give that character or characters the syntax
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
1645 specified by @var{syntax-description}, which is passed to
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
1646 @code{modify-syntax-entry} (@pxref{Syntax Table Functions}).
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
1647
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
1648 This feature is typically used to give word syntax to characters which
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
1649 normally have symbol syntax, and thus to simplify
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
1650 @code{imenu-generic-expression} and speed up matching.
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
1651 For example, Fortran mode uses it this way:
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
1652
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
1653 @example
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
1654 (setq imenu-syntax-alist '(("_$" . "w")))
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
1655 @end example
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
1656
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
1657 The @code{imenu-generic-expression} patterns can then use @samp{\\sw+}
22252
40089afa2b1d *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22138
diff changeset
1658 instead of @samp{\\(\\sw\\|\\s_\\)+}. Note that this technique may be
25751
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 24934
diff changeset
1659 inconvenient when the mode needs to limit the initial character
22267
dfac7398266b *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22252
diff changeset
1660 of a name to a smaller set of characters than are allowed in the rest
dfac7398266b *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22252
diff changeset
1661 of a name.
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17278
diff changeset
1662
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1663 Setting this variable makes it buffer-local in the current buffer.
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17278
diff changeset
1664 @end defvar
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17278
diff changeset
1665
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17278
diff changeset
1666 Another way to customize Imenu for a major mode is to set the
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17278
diff changeset
1667 variables @code{imenu-prev-index-position-function} and
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1668 @code{imenu-extract-index-name-function}:
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17278
diff changeset
1669
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17278
diff changeset
1670 @defvar imenu-prev-index-position-function
27332
5cfe77eaff45 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 27189
diff changeset
1671 If this variable is non-@code{nil}, its value should be a function that
25875
6a17c48b52ef *** empty log message ***
Phillip Rulon <pjr@gnu.org>
parents: 25751
diff changeset
1672 finds the next ``definition'' to put in the buffer index, scanning
6a17c48b52ef *** empty log message ***
Phillip Rulon <pjr@gnu.org>
parents: 25751
diff changeset
1673 backward in the buffer from point. It should return @code{nil} if it
48700
df6767370b43 Fix typo.
Pavel Janík <Pavel@Janik.cz>
parents: 46914
diff changeset
1674 doesn't find another ``definition'' before point. Otherwise it should
25875
6a17c48b52ef *** empty log message ***
Phillip Rulon <pjr@gnu.org>
parents: 25751
diff changeset
1675 leave point at the place it finds a ``definition,'' and return any
6a17c48b52ef *** empty log message ***
Phillip Rulon <pjr@gnu.org>
parents: 25751
diff changeset
1676 non-@code{nil} value.
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17278
diff changeset
1677
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1678 Setting this variable makes it buffer-local in the current buffer.
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17278
diff changeset
1679 @end defvar
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17278
diff changeset
1680
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17278
diff changeset
1681 @defvar imenu-extract-index-name-function
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17278
diff changeset
1682 If this variable is non-@code{nil}, its value should be a function to
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1683 return the name for a definition, assuming point is in that definition
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1684 as the @code{imenu-prev-index-position-function} function would leave
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1685 it.
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17278
diff changeset
1686
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1687 Setting this variable makes it buffer-local in the current buffer.
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17278
diff changeset
1688 @end defvar
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17278
diff changeset
1689
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1690 The last way to customize Imenu for a major mode is to set the
25875
6a17c48b52ef *** empty log message ***
Phillip Rulon <pjr@gnu.org>
parents: 25751
diff changeset
1691 variable @code{imenu-create-index-function}:
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1692
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17278
diff changeset
1693 @defvar imenu-create-index-function
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17278
diff changeset
1694 This variable specifies the function to use for creating a buffer index.
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17278
diff changeset
1695 The function should take no arguments, and return an index for the
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17278
diff changeset
1696 current buffer. It is called within @code{save-excursion}, so where it
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17278
diff changeset
1697 leaves point makes no difference.
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17278
diff changeset
1698
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17278
diff changeset
1699 The default value is a function that uses
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17278
diff changeset
1700 @code{imenu-generic-expression} to produce the index alist. If you
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17278
diff changeset
1701 specify a different function, then @code{imenu-generic-expression} is
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17278
diff changeset
1702 not used.
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17278
diff changeset
1703
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1704 Setting this variable makes it buffer-local in the current buffer.
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17278
diff changeset
1705 @end defvar
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17278
diff changeset
1706
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17278
diff changeset
1707 @defvar imenu-index-alist
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17278
diff changeset
1708 This variable holds the index alist for the current buffer.
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1709 Setting it makes it buffer-local in the current buffer.
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17278
diff changeset
1710
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17278
diff changeset
1711 Simple elements in the alist look like @code{(@var{index-name}
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17278
diff changeset
1712 . @var{index-position})}. Selecting a simple element has the effect of
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17278
diff changeset
1713 moving to position @var{index-position} in the buffer.
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17278
diff changeset
1714
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17278
diff changeset
1715 Special elements look like @code{(@var{index-name} @var{position}
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17278
diff changeset
1716 @var{function} @var{arguments}@dots{})}. Selecting a special element
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17278
diff changeset
1717 performs
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17278
diff changeset
1718
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17278
diff changeset
1719 @example
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17278
diff changeset
1720 (funcall @var{function} @var{index-name} @var{position} @var{arguments}@dots{})
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17278
diff changeset
1721 @end example
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17278
diff changeset
1722
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17278
diff changeset
1723 A nested sub-alist element looks like @code{(@var{index-name}
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17278
diff changeset
1724 @var{sub-alist})}.
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17278
diff changeset
1725 @end defvar
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17278
diff changeset
1726
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17278
diff changeset
1727 @node Font Lock Mode
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17278
diff changeset
1728 @section Font Lock Mode
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17278
diff changeset
1729 @cindex Font Lock Mode
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17278
diff changeset
1730
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17278
diff changeset
1731 @dfn{Font Lock mode} is a feature that automatically attaches
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17278
diff changeset
1732 @code{face} properties to certain parts of the buffer based on their
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17278
diff changeset
1733 syntactic role. How it parses the buffer depends on the major mode;
25875
6a17c48b52ef *** empty log message ***
Phillip Rulon <pjr@gnu.org>
parents: 25751
diff changeset
1734 most major modes define syntactic criteria for which faces to use in
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1735 which contexts. This section explains how to customize Font Lock for a
25875
6a17c48b52ef *** empty log message ***
Phillip Rulon <pjr@gnu.org>
parents: 25751
diff changeset
1736 particular major mode.
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17278
diff changeset
1737
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17278
diff changeset
1738 Font Lock mode finds text to highlight in two ways: through syntactic
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17278
diff changeset
1739 parsing based on the syntax table, and through searching (usually for
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17278
diff changeset
1740 regular expressions). Syntactic fontification happens first; it finds
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17278
diff changeset
1741 comments and string constants, and highlights them using
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17278
diff changeset
1742 @code{font-lock-comment-face} and @code{font-lock-string-face}
25875
6a17c48b52ef *** empty log message ***
Phillip Rulon <pjr@gnu.org>
parents: 25751
diff changeset
1743 (@pxref{Faces for Font Lock}). Search-based fontification follows.
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17278
diff changeset
1744
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17278
diff changeset
1745 @menu
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17278
diff changeset
1746 * Font Lock Basics::
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17278
diff changeset
1747 * Search-based Fontification::
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17278
diff changeset
1748 * Other Font Lock Variables::
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17278
diff changeset
1749 * Levels of Font Lock::
45684
6f73f208b4ce (Precalcuated Fontification): New node, describing `font-lock-face'.
Colin Walters <walters@gnu.org>
parents: 43677
diff changeset
1750 * Precalculated Fontification::
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17278
diff changeset
1751 * Faces for Font Lock::
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1752 * Syntactic Font Lock::
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17278
diff changeset
1753 @end menu
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17278
diff changeset
1754
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17278
diff changeset
1755 @node Font Lock Basics
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17278
diff changeset
1756 @subsection Font Lock Basics
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17278
diff changeset
1757
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17278
diff changeset
1758 There are several variables that control how Font Lock mode highlights
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17278
diff changeset
1759 text. But major modes should not set any of these variables directly.
24934
f5e3b4ecd255 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 22274
diff changeset
1760 Instead, they should set @code{font-lock-defaults} as a buffer-local
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1761 variable. The value assigned to this variable is used, if and when Font
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1762 Lock mode is enabled, to set all the other variables.
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17278
diff changeset
1763
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17278
diff changeset
1764 @defvar font-lock-defaults
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17278
diff changeset
1765 This variable is set by major modes, as a buffer-local variable, to
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17278
diff changeset
1766 specify how to fontify text in that mode. The value should look like
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17278
diff changeset
1767 this:
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17278
diff changeset
1768
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17278
diff changeset
1769 @example
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17278
diff changeset
1770 (@var{keywords} @var{keywords-only} @var{case-fold}
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17278
diff changeset
1771 @var{syntax-alist} @var{syntax-begin} @var{other-vars}@dots{})
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17278
diff changeset
1772 @end example
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17278
diff changeset
1773
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17278
diff changeset
1774 The first element, @var{keywords}, indirectly specifies the value of
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17278
diff changeset
1775 @code{font-lock-keywords}. It can be a symbol, a variable whose value
25875
6a17c48b52ef *** empty log message ***
Phillip Rulon <pjr@gnu.org>
parents: 25751
diff changeset
1776 is the list to use for @code{font-lock-keywords}. It can also be a list of
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17278
diff changeset
1777 several such symbols, one for each possible level of fontification. The
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17278
diff changeset
1778 first symbol specifies how to do level 1 fontification, the second
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17278
diff changeset
1779 symbol how to do level 2, and so on.
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17278
diff changeset
1780
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17278
diff changeset
1781 The second element, @var{keywords-only}, specifies the value of the
22138
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
1782 variable @code{font-lock-keywords-only}. If this is non-@code{nil},
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1783 syntactic fontification (of strings and comments) is not performed.
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17278
diff changeset
1784
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17278
diff changeset
1785 The third element, @var{case-fold}, specifies the value of
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17278
diff changeset
1786 @code{font-lock-case-fold-search}. If it is non-@code{nil}, Font Lock
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1787 mode ignores case when searching as directed by
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1788 @code{font-lock-keywords}.
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17278
diff changeset
1789
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17278
diff changeset
1790 If the fourth element, @var{syntax-alist}, is non-@code{nil}, it should be
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17278
diff changeset
1791 a list of cons cells of the form @code{(@var{char-or-string}
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17278
diff changeset
1792 . @var{string})}. These are used to set up a syntax table for
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17278
diff changeset
1793 fontification (@pxref{Syntax Table Functions}). The resulting syntax
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17278
diff changeset
1794 table is stored in @code{font-lock-syntax-table}.
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17278
diff changeset
1795
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17278
diff changeset
1796 The fifth element, @var{syntax-begin}, specifies the value of
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1797 @code{font-lock-beginning-of-syntax-function} (see below).
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17278
diff changeset
1798
25875
6a17c48b52ef *** empty log message ***
Phillip Rulon <pjr@gnu.org>
parents: 25751
diff changeset
1799 All the remaining elements (if any) are collectively called
6a17c48b52ef *** empty log message ***
Phillip Rulon <pjr@gnu.org>
parents: 25751
diff changeset
1800 @var{other-vars}. Each of these elements should have the form
6a17c48b52ef *** empty log message ***
Phillip Rulon <pjr@gnu.org>
parents: 25751
diff changeset
1801 @code{(@var{variable} . @var{value})}---which means, make @var{variable}
6a17c48b52ef *** empty log message ***
Phillip Rulon <pjr@gnu.org>
parents: 25751
diff changeset
1802 buffer-local and then set it to @var{value}. You can use these
6a17c48b52ef *** empty log message ***
Phillip Rulon <pjr@gnu.org>
parents: 25751
diff changeset
1803 @var{other-vars} to set other variables that affect fontification,
6a17c48b52ef *** empty log message ***
Phillip Rulon <pjr@gnu.org>
parents: 25751
diff changeset
1804 aside from those you can control with the first five elements.
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17278
diff changeset
1805 @end defvar
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17278
diff changeset
1806
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17278
diff changeset
1807 @node Search-based Fontification
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17278
diff changeset
1808 @subsection Search-based Fontification
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17278
diff changeset
1809
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17278
diff changeset
1810 The most important variable for customizing Font Lock mode is
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17278
diff changeset
1811 @code{font-lock-keywords}. It specifies the search criteria for
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17278
diff changeset
1812 search-based fontification.
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17278
diff changeset
1813
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17278
diff changeset
1814 @defvar font-lock-keywords
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17278
diff changeset
1815 This variable's value is a list of the keywords to highlight. Be
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1816 careful when composing regular expressions for this list; a poorly
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1817 written pattern can dramatically slow things down!
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17278
diff changeset
1818 @end defvar
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17278
diff changeset
1819
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17278
diff changeset
1820 Each element of @code{font-lock-keywords} specifies how to find
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1821 certain cases of text, and how to highlight those cases. Font Lock mode
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1822 processes the elements of @code{font-lock-keywords} one by one, and for
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1823 each element, it finds and handles all matches. Ordinarily, once
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1824 part of the text has been fontified already, this cannot be overridden
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1825 by a subsequent match in the same text; but you can specify different
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1826 behavior using the @var{override} element of a @var{highlighter}.
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1827
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1828 Each element of @code{font-lock-keywords} should have one of these
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1829 forms:
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17278
diff changeset
1830
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17278
diff changeset
1831 @table @code
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17278
diff changeset
1832 @item @var{regexp}
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17278
diff changeset
1833 Highlight all matches for @var{regexp} using
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17278
diff changeset
1834 @code{font-lock-keyword-face}. For example,
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17278
diff changeset
1835
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17278
diff changeset
1836 @example
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17278
diff changeset
1837 ;; @r{Highlight discrete occurrences of @samp{foo}}
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17278
diff changeset
1838 ;; @r{using @code{font-lock-keyword-face}.}
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17278
diff changeset
1839 "\\<foo\\>"
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17278
diff changeset
1840 @end example
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17278
diff changeset
1841
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1842 The function @code{regexp-opt} (@pxref{Syntax of Regexps}) is useful for
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1843 calculating optimal regular expressions to match a number of different
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1844 keywords.
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17278
diff changeset
1845
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17278
diff changeset
1846 @item @var{function}
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17278
diff changeset
1847 Find text by calling @var{function}, and highlight the matches
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17278
diff changeset
1848 it finds using @code{font-lock-keyword-face}.
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17278
diff changeset
1849
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17278
diff changeset
1850 When @var{function} is called, it receives one argument, the limit of
41938
f8c0a921c536 Improve doc of font-lock-keywords.
Richard M. Stallman <rms@gnu.org>
parents: 40928
diff changeset
1851 the search; it should searching at point, and not search beyond the
f8c0a921c536 Improve doc of font-lock-keywords.
Richard M. Stallman <rms@gnu.org>
parents: 40928
diff changeset
1852 limit. It should return non-@code{nil} if it succeeds, and set the
f8c0a921c536 Improve doc of font-lock-keywords.
Richard M. Stallman <rms@gnu.org>
parents: 40928
diff changeset
1853 match data to describe the match that was found. Returning @code{nil}
f8c0a921c536 Improve doc of font-lock-keywords.
Richard M. Stallman <rms@gnu.org>
parents: 40928
diff changeset
1854 indicates failure of the search.
f8c0a921c536 Improve doc of font-lock-keywords.
Richard M. Stallman <rms@gnu.org>
parents: 40928
diff changeset
1855
f8c0a921c536 Improve doc of font-lock-keywords.
Richard M. Stallman <rms@gnu.org>
parents: 40928
diff changeset
1856 Fontification will call @var{function} repeatedly with the same limit,
f8c0a921c536 Improve doc of font-lock-keywords.
Richard M. Stallman <rms@gnu.org>
parents: 40928
diff changeset
1857 and with point where the previous invocation left it, until
f8c0a921c536 Improve doc of font-lock-keywords.
Richard M. Stallman <rms@gnu.org>
parents: 40928
diff changeset
1858 @var{function} fails. On failure, @var{function} need not reset point
f8c0a921c536 Improve doc of font-lock-keywords.
Richard M. Stallman <rms@gnu.org>
parents: 40928
diff changeset
1859 in any particular way.
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17278
diff changeset
1860
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17278
diff changeset
1861 @item (@var{matcher} . @var{match})
24934
f5e3b4ecd255 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 22274
diff changeset
1862 In this kind of element, @var{matcher} is either a regular
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17278
diff changeset
1863 expression or a function, as described above. The @sc{cdr},
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17278
diff changeset
1864 @var{match}, specifies which subexpression of @var{matcher} should be
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1865 highlighted (instead of the entire text that @var{matcher} matched).
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17278
diff changeset
1866
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17278
diff changeset
1867 @example
25751
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 24934
diff changeset
1868 ;; @r{Highlight the @samp{bar} in each occurrence of @samp{fubar},}
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17278
diff changeset
1869 ;; @r{using @code{font-lock-keyword-face}.}
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17278
diff changeset
1870 ("fu\\(bar\\)" . 1)
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17278
diff changeset
1871 @end example
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17278
diff changeset
1872
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1873 If you use @code{regexp-opt} to produce the regular expression
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17278
diff changeset
1874 @var{matcher}, then you can use @code{regexp-opt-depth} (@pxref{Syntax
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17278
diff changeset
1875 of Regexps}) to calculate the value for @var{match}.
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17278
diff changeset
1876
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17278
diff changeset
1877 @item (@var{matcher} . @var{facename})
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17278
diff changeset
1878 In this kind of element, @var{facename} is an expression whose value
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17278
diff changeset
1879 specifies the face name to use for highlighting.
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17278
diff changeset
1880
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17278
diff changeset
1881 @example
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17278
diff changeset
1882 ;; @r{Highlight occurrences of @samp{fubar},}
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17278
diff changeset
1883 ;; @r{using the face which is the value of @code{fubar-face}.}
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17278
diff changeset
1884 ("fubar" . fubar-face)
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17278
diff changeset
1885 @end example
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17278
diff changeset
1886
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17278
diff changeset
1887 @item (@var{matcher} . @var{highlighter})
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17278
diff changeset
1888 In this kind of element, @var{highlighter} is a list
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17278
diff changeset
1889 which specifies how to highlight matches found by @var{matcher}.
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17278
diff changeset
1890 It has the form
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17278
diff changeset
1891
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17278
diff changeset
1892 @example
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17278
diff changeset
1893 (@var{subexp} @var{facename} @var{override} @var{laxmatch})
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17278
diff changeset
1894 @end example
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17278
diff changeset
1895
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17278
diff changeset
1896 The @sc{car}, @var{subexp}, is an integer specifying which subexpression
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1897 of the match to fontify (0 means the entire matching text). The second
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1898 subelement, @var{facename}, specifies the face, as described above.
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17278
diff changeset
1899
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17278
diff changeset
1900 The last two values in @var{highlighter}, @var{override} and
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17278
diff changeset
1901 @var{laxmatch}, are flags. If @var{override} is @code{t}, this element
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17278
diff changeset
1902 can override existing fontification made by previous elements of
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17278
diff changeset
1903 @code{font-lock-keywords}. If it is @code{keep}, then each character is
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17278
diff changeset
1904 fontified if it has not been fontified already by some other element.
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17278
diff changeset
1905 If it is @code{prepend}, the face @var{facename} is added to the
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17278
diff changeset
1906 beginning of the @code{face} property. If it is @code{append}, the face
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17278
diff changeset
1907 @var{facename} is added to the end of the @code{face} property.
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17278
diff changeset
1908
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17278
diff changeset
1909 If @var{laxmatch} is non-@code{nil}, it means there should be no error
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17278
diff changeset
1910 if there is no subexpression numbered @var{subexp} in @var{matcher}.
25975
e368b754fe25 Add patch from rms around line 1870.
Gerd Moellmann <gerd@gnu.org>
parents: 25950
diff changeset
1911 Obviously, fontification of the subexpression numbered @var{subexp} will
e368b754fe25 Add patch from rms around line 1870.
Gerd Moellmann <gerd@gnu.org>
parents: 25950
diff changeset
1912 not occur. However, fontification of other subexpressions (and other
e368b754fe25 Add patch from rms around line 1870.
Gerd Moellmann <gerd@gnu.org>
parents: 25950
diff changeset
1913 regexps) will continue. If @var{laxmatch} is @code{nil}, and the
e368b754fe25 Add patch from rms around line 1870.
Gerd Moellmann <gerd@gnu.org>
parents: 25950
diff changeset
1914 specified subexpression is missing, then an error is signalled which
e368b754fe25 Add patch from rms around line 1870.
Gerd Moellmann <gerd@gnu.org>
parents: 25950
diff changeset
1915 terminates search-based fontification.
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17278
diff changeset
1916
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17278
diff changeset
1917 Here are some examples of elements of this kind, and what they do:
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17278
diff changeset
1918
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17278
diff changeset
1919 @smallexample
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17278
diff changeset
1920 ;; @r{Highlight occurrences of either @samp{foo} or @samp{bar},}
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17278
diff changeset
1921 ;; @r{using @code{foo-bar-face}, even if they have already been highlighted.}
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17278
diff changeset
1922 ;; @r{@code{foo-bar-face} should be a variable whose value is a face.}
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17278
diff changeset
1923 ("foo\\|bar" 0 foo-bar-face t)
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17278
diff changeset
1924
25751
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 24934
diff changeset
1925 ;; @r{Highlight the first subexpression within each occurrence}
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17278
diff changeset
1926 ;; @r{that the function @code{fubar-match} finds,}
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17278
diff changeset
1927 ;; @r{using the face which is the value of @code{fubar-face}.}
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17278
diff changeset
1928 (fubar-match 1 fubar-face)
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17278
diff changeset
1929 @end smallexample
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17278
diff changeset
1930
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17278
diff changeset
1931 @item (@var{matcher} @var{highlighters}@dots{})
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17278
diff changeset
1932 This sort of element specifies several @var{highlighter} lists for a
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17278
diff changeset
1933 single @var{matcher}. In order for this to be useful, each
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17278
diff changeset
1934 @var{highlighter} should have a different value of @var{subexp}; that is,
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17278
diff changeset
1935 each one should apply to a different subexpression of @var{matcher}.
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17278
diff changeset
1936
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17278
diff changeset
1937 @ignore
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17278
diff changeset
1938 @item (@var{matcher} . @var{anchored})
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17278
diff changeset
1939 In this kind of element, @var{anchored} acts much like a
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17278
diff changeset
1940 @var{highlighter}, but it is more complex and can specify multiple
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17278
diff changeset
1941 successive searches.
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17278
diff changeset
1942
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17278
diff changeset
1943 For highlighting single items, typically only @var{highlighter} is
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17278
diff changeset
1944 required. However, if an item or (typically) items are to be
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17278
diff changeset
1945 highlighted following the instance of another item (the anchor) then
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17278
diff changeset
1946 @var{anchored} may be required.
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17278
diff changeset
1947
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17278
diff changeset
1948 It has this format:
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17278
diff changeset
1949
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17278
diff changeset
1950 @example
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17278
diff changeset
1951 (@var{submatcher} @var{pre-match-form} @var{post-match-form} @var{highlighters}@dots{})
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17278
diff changeset
1952 @end example
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17278
diff changeset
1953
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17278
diff changeset
1954 @c I can't parse this text -- rms
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17278
diff changeset
1955 where @var{submatcher} is much like @var{matcher}, with one
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17278
diff changeset
1956 exception---see below. @var{pre-match-form} and @var{post-match-form}
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17278
diff changeset
1957 are evaluated before the first, and after the last, instance
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17278
diff changeset
1958 @var{anchored}'s @var{submatcher} is used. Therefore they can be used
22138
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
1959 to initialize before, and cleanup after, @var{submatcher} is used.
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17278
diff changeset
1960 Typically, @var{pre-match-form} is used to move to some position
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17278
diff changeset
1961 relative to the original @var{submatcher}, before starting with
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17278
diff changeset
1962 @var{anchored}'s @var{submatcher}. @var{post-match-form} might be used
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17278
diff changeset
1963 to move, before resuming with @var{anchored}'s parent's @var{matcher}.
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17278
diff changeset
1964
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17278
diff changeset
1965 For example, an element of the form highlights (if not already highlighted):
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17278
diff changeset
1966
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17278
diff changeset
1967 @example
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17278
diff changeset
1968 ("\\<anchor\\>" (0 anchor-face) ("\\<item\\>" nil nil (0 item-face)))
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17278
diff changeset
1969 @end example
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17278
diff changeset
1970
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17278
diff changeset
1971 Discrete occurrences of @samp{anchor} in the value of
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17278
diff changeset
1972 @code{anchor-face}, and subsequent discrete occurrences of @samp{item}
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17278
diff changeset
1973 (on the same line) in the value of @code{item-face}. (Here
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17278
diff changeset
1974 @var{pre-match-form} and @var{post-match-form} are @code{nil}.
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17278
diff changeset
1975 Therefore @samp{item} is initially searched for starting from the end of
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17278
diff changeset
1976 the match of @samp{anchor}, and searching for subsequent instance of
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17278
diff changeset
1977 @samp{anchor} resumes from where searching for @samp{item} concluded.)
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17278
diff changeset
1978
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17278
diff changeset
1979 The above-mentioned exception is as follows. The limit of the
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17278
diff changeset
1980 @var{submatcher} search defaults to the end of the line after
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17278
diff changeset
1981 @var{pre-match-form} is evaluated. However, if @var{pre-match-form}
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17278
diff changeset
1982 returns a position greater than the position after @var{pre-match-form}
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17278
diff changeset
1983 is evaluated, that position is used as the limit of the search. It is
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17278
diff changeset
1984 generally a bad idea to return a position greater than the end of the
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17278
diff changeset
1985 line; in other words, the @var{submatcher} search should not span lines.
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17278
diff changeset
1986
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17278
diff changeset
1987 @item (@var{matcher} @var{highlighters-or-anchoreds} ...)
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17278
diff changeset
1988 @end ignore
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17278
diff changeset
1989
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17278
diff changeset
1990 @item (eval . @var{form})
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1991 Here @var{form} is an expression to be evaluated the first time
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17278
diff changeset
1992 this value of @code{font-lock-keywords} is used in a buffer.
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1993 Its value should have one of the forms described in this table.
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17278
diff changeset
1994 @end table
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17278
diff changeset
1995
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17278
diff changeset
1996 @strong{Warning:} Do not design an element of @code{font-lock-keywords}
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17278
diff changeset
1997 to match text which spans lines; this does not work reliably. While
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17278
diff changeset
1998 @code{font-lock-fontify-buffer} handles multi-line patterns correctly,
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17278
diff changeset
1999 updating when you edit the buffer does not, since it considers text one
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17278
diff changeset
2000 line at a time.
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17278
diff changeset
2001
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17278
diff changeset
2002 @node Other Font Lock Variables
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17278
diff changeset
2003 @subsection Other Font Lock Variables
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17278
diff changeset
2004
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17278
diff changeset
2005 This section describes additional variables that a major mode
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17278
diff changeset
2006 can set by means of @code{font-lock-defaults}.
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17278
diff changeset
2007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17278
diff changeset
2008 @defvar font-lock-keywords-only
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17278
diff changeset
2009 Non-@code{nil} means Font Lock should not fontify comments or strings
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
2010 syntactically; it should only fontify based on
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
2011 @code{font-lock-keywords}.
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17278
diff changeset
2012 @end defvar
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17278
diff changeset
2013
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17278
diff changeset
2014 @ignore
22138
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
2015 Other variables include those for buffer-specialized fontification functions,
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17278
diff changeset
2016 `font-lock-fontify-buffer-function', `font-lock-unfontify-buffer-function',
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17278
diff changeset
2017 `font-lock-fontify-region-function', `font-lock-unfontify-region-function',
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17278
diff changeset
2018 `font-lock-inhibit-thing-lock' and `font-lock-maximum-size'.
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17278
diff changeset
2019 @end ignore
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17278
diff changeset
2020
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17278
diff changeset
2021 @defvar font-lock-keywords-case-fold-search
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
2022 Non-@code{nil} means that regular expression matching for the sake of
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
2023 @code{font-lock-keywords} should be case-insensitive.
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
2024 @end defvar
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
2025
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
2026 @defvar font-lock-syntax-table
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
2027 This variable specifies the syntax table to use for fontification of
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
2028 comments and strings.
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17278
diff changeset
2029 @end defvar
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17278
diff changeset
2030
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17278
diff changeset
2031 @defvar font-lock-beginning-of-syntax-function
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
2032 If this variable is non-@code{nil}, it should be a function to move
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
2033 point back to a position that is syntactically at ``top level'' and
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
2034 outside of strings or comments. Font Lock uses this when necessary
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
2035 to get the right results for syntactic fontification.
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17278
diff changeset
2036
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17278
diff changeset
2037 This function is called with no arguments. It should leave point at the
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17278
diff changeset
2038 beginning of any enclosing syntactic block. Typical values are
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17278
diff changeset
2039 @code{beginning-of-line} (i.e., the start of the line is known to be
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17278
diff changeset
2040 outside a syntactic block), or @code{beginning-of-defun} for programming
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17278
diff changeset
2041 modes or @code{backward-paragraph} for textual modes (i.e., the
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17278
diff changeset
2042 mode-dependent function is known to move outside a syntactic block).
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17278
diff changeset
2043
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17278
diff changeset
2044 If the value is @code{nil}, the beginning of the buffer is used as a
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
2045 position outside of a syntactic block. This cannot be wrong, but it can
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
2046 be slow.
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17278
diff changeset
2047 @end defvar
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17278
diff changeset
2048
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17278
diff changeset
2049 @defvar font-lock-mark-block-function
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
2050 If this variable is non-@code{nil}, it should be a function that is
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
2051 called with no arguments, to choose an enclosing range of text for
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
2052 refontification for the command @kbd{M-g M-g}
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
2053 (@code{font-lock-fontify-block}).
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17278
diff changeset
2054
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
2055 The function should report its choice by placing the region around it.
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
2056 A good choice is a range of text large enough to give proper results,
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
2057 but not too large so that refontification becomes slow. Typical values
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
2058 are @code{mark-defun} for programming modes or @code{mark-paragraph} for
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
2059 textual modes.
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17278
diff changeset
2060 @end defvar
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17278
diff changeset
2061
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17278
diff changeset
2062 @node Levels of Font Lock
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17278
diff changeset
2063 @subsection Levels of Font Lock
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17278
diff changeset
2064
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17278
diff changeset
2065 Many major modes offer three different levels of fontification. You
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17278
diff changeset
2066 can define multiple levels by using a list of symbols for @var{keywords}
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17278
diff changeset
2067 in @code{font-lock-defaults}. Each symbol specifies one level of
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17278
diff changeset
2068 fontification; it is up to the user to choose one of these levels. The
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17278
diff changeset
2069 chosen level's symbol value is used to initialize
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17278
diff changeset
2070 @code{font-lock-keywords}.
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17278
diff changeset
2071
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
2072 Here are the conventions for how to define the levels of
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
2073 fontification:
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
2074
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17278
diff changeset
2075 @itemize @bullet
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17278
diff changeset
2076 @item
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17278
diff changeset
2077 Level 1: highlight function declarations, file directives (such as include or
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17278
diff changeset
2078 import directives), strings and comments. The idea is speed, so only
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17278
diff changeset
2079 the most important and top-level components are fontified.
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17278
diff changeset
2080
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17278
diff changeset
2081 @item
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
2082 Level 2: in addition to level 1, highlight all language keywords,
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
2083 including type names that act like keywords, as well as named constant
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
2084 values. The idea is that all keywords (either syntactic or semantic)
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
2085 should be fontified appropriately.
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17278
diff changeset
2086
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17278
diff changeset
2087 @item
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
2088 Level 3: in addition to level 2, highlight the symbols being defined in
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
2089 function and variable declarations, and all builtin function names,
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
2090 wherever they appear.
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17278
diff changeset
2091 @end itemize
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17278
diff changeset
2092
45684
6f73f208b4ce (Precalcuated Fontification): New node, describing `font-lock-face'.
Colin Walters <walters@gnu.org>
parents: 43677
diff changeset
2093 @node Precalculated Fontification
6f73f208b4ce (Precalcuated Fontification): New node, describing `font-lock-face'.
Colin Walters <walters@gnu.org>
parents: 43677
diff changeset
2094 @subsection Precalculated Fontification
6f73f208b4ce (Precalcuated Fontification): New node, describing `font-lock-face'.
Colin Walters <walters@gnu.org>
parents: 43677
diff changeset
2095
6f73f208b4ce (Precalcuated Fontification): New node, describing `font-lock-face'.
Colin Walters <walters@gnu.org>
parents: 43677
diff changeset
2096 In addition to using @code{font-lock-defaults} for search-based
6f73f208b4ce (Precalcuated Fontification): New node, describing `font-lock-face'.
Colin Walters <walters@gnu.org>
parents: 43677
diff changeset
2097 fontification, you may use the special character property
6f73f208b4ce (Precalcuated Fontification): New node, describing `font-lock-face'.
Colin Walters <walters@gnu.org>
parents: 43677
diff changeset
2098 @code{font-lock-face} (@pxref{Special Properties}). This property
6f73f208b4ce (Precalcuated Fontification): New node, describing `font-lock-face'.
Colin Walters <walters@gnu.org>
parents: 43677
diff changeset
2099 acts just like the explicit @code{face} property, but its activation
6f73f208b4ce (Precalcuated Fontification): New node, describing `font-lock-face'.
Colin Walters <walters@gnu.org>
parents: 43677
diff changeset
2100 is toggled when the user calls @kbd{M-x font-lock-mode}. Using
6f73f208b4ce (Precalcuated Fontification): New node, describing `font-lock-face'.
Colin Walters <walters@gnu.org>
parents: 43677
diff changeset
2101 @code{font-lock-face} is especially conveninent for special modes
6f73f208b4ce (Precalcuated Fontification): New node, describing `font-lock-face'.
Colin Walters <walters@gnu.org>
parents: 43677
diff changeset
2102 which construct their text programmatically, such as
6f73f208b4ce (Precalcuated Fontification): New node, describing `font-lock-face'.
Colin Walters <walters@gnu.org>
parents: 43677
diff changeset
2103 @code{list-buffers} and @code{occur}.
6f73f208b4ce (Precalcuated Fontification): New node, describing `font-lock-face'.
Colin Walters <walters@gnu.org>
parents: 43677
diff changeset
2104
45714
7057566fa4c1 (Precalcuated Fontification): Note how to use `font-lock-core-only'.
Colin Walters <walters@gnu.org>
parents: 45684
diff changeset
2105 If your mode does not use any of the other machinery of Font Lock
7057566fa4c1 (Precalcuated Fontification): Note how to use `font-lock-core-only'.
Colin Walters <walters@gnu.org>
parents: 45684
diff changeset
2106 (i.e. it only uses the @code{font-lock-face} property), you can tell
7057566fa4c1 (Precalcuated Fontification): Note how to use `font-lock-core-only'.
Colin Walters <walters@gnu.org>
parents: 45684
diff changeset
2107 Emacs not to load all of font-lock.el (unless it's already loaded), by
7057566fa4c1 (Precalcuated Fontification): Note how to use `font-lock-core-only'.
Colin Walters <walters@gnu.org>
parents: 45684
diff changeset
2108 setting the variable @code{font-lock-core-only} to non-nil as part of
7057566fa4c1 (Precalcuated Fontification): Note how to use `font-lock-core-only'.
Colin Walters <walters@gnu.org>
parents: 45684
diff changeset
2109 the @code{font-lock-defaults} settings. Here is the canonical way to
7057566fa4c1 (Precalcuated Fontification): Note how to use `font-lock-core-only'.
Colin Walters <walters@gnu.org>
parents: 45684
diff changeset
2110 do this:
7057566fa4c1 (Precalcuated Fontification): Note how to use `font-lock-core-only'.
Colin Walters <walters@gnu.org>
parents: 45684
diff changeset
2111
7057566fa4c1 (Precalcuated Fontification): Note how to use `font-lock-core-only'.
Colin Walters <walters@gnu.org>
parents: 45684
diff changeset
2112 @example
7057566fa4c1 (Precalcuated Fontification): Note how to use `font-lock-core-only'.
Colin Walters <walters@gnu.org>
parents: 45684
diff changeset
2113 (set (make-local-variable 'font-lock-defaults)
7057566fa4c1 (Precalcuated Fontification): Note how to use `font-lock-core-only'.
Colin Walters <walters@gnu.org>
parents: 45684
diff changeset
2114 '(nil t nil nil nil (font-lock-core-only . t)))
7057566fa4c1 (Precalcuated Fontification): Note how to use `font-lock-core-only'.
Colin Walters <walters@gnu.org>
parents: 45684
diff changeset
2115 @end example
7057566fa4c1 (Precalcuated Fontification): Note how to use `font-lock-core-only'.
Colin Walters <walters@gnu.org>
parents: 45684
diff changeset
2116
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17278
diff changeset
2117 @node Faces for Font Lock
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17278
diff changeset
2118 @subsection Faces for Font Lock
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17278
diff changeset
2119
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17278
diff changeset
2120 You can make Font Lock mode use any face, but several faces are
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17278
diff changeset
2121 defined specifically for Font Lock mode. Each of these symbols is both
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17278
diff changeset
2122 a face name, and a variable whose default value is the symbol itself.
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17278
diff changeset
2123 Thus, the default value of @code{font-lock-comment-face} is
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17278
diff changeset
2124 @code{font-lock-comment-face}. This means you can write
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17278
diff changeset
2125 @code{font-lock-comment-face} in a context such as
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17278
diff changeset
2126 @code{font-lock-keywords} where a face-name-valued expression is used.
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17278
diff changeset
2127
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17278
diff changeset
2128 @table @code
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17278
diff changeset
2129 @item font-lock-comment-face
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17278
diff changeset
2130 @vindex font-lock-comment-face
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17278
diff changeset
2131 Used (typically) for comments.
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17278
diff changeset
2132
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17278
diff changeset
2133 @item font-lock-string-face
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17278
diff changeset
2134 @vindex font-lock-string-face
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17278
diff changeset
2135 Used (typically) for string constants.
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17278
diff changeset
2136
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17278
diff changeset
2137 @item font-lock-keyword-face
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17278
diff changeset
2138 @vindex font-lock-keyword-face
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17278
diff changeset
2139 Used (typically) for keywords---names that have special syntactic
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17278
diff changeset
2140 significance, like @code{for} and @code{if} in C.
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17278
diff changeset
2141
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17278
diff changeset
2142 @item font-lock-builtin-face
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17278
diff changeset
2143 @vindex font-lock-builtin-face
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17278
diff changeset
2144 Used (typically) for built-in function names.
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17278
diff changeset
2145
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17278
diff changeset
2146 @item font-lock-function-name-face
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17278
diff changeset
2147 @vindex font-lock-function-name-face
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17278
diff changeset
2148 Used (typically) for the name of a function being defined or declared,
49600
23a1cea22d13 Trailing whitespace deleted.
Juanma Barranquero <lekktu@gmail.com>
parents: 48700
diff changeset
2149 in a function definition or declaration.
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17278
diff changeset
2150
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17278
diff changeset
2151 @item font-lock-variable-name-face
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17278
diff changeset
2152 @vindex font-lock-variable-name-face
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17278
diff changeset
2153 Used (typically) for the name of a variable being defined or declared,
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17278
diff changeset
2154 in a variable definition or declaration.
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17278
diff changeset
2155
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17278
diff changeset
2156 @item font-lock-type-face
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17278
diff changeset
2157 @vindex font-lock-type-face
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17278
diff changeset
2158 Used (typically) for names of user-defined data types,
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17278
diff changeset
2159 where they are defined and where they are used.
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17278
diff changeset
2160
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17278
diff changeset
2161 @item font-lock-constant-face
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17278
diff changeset
2162 @vindex font-lock-constant-face
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17278
diff changeset
2163 Used (typically) for constant names.
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17278
diff changeset
2164
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17278
diff changeset
2165 @item font-lock-warning-face
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17278
diff changeset
2166 @vindex font-lock-warning-face
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17278
diff changeset
2167 Used (typically) for constructs that are peculiar, or that greatly
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17278
diff changeset
2168 change the meaning of other text. For example, this is used for
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17278
diff changeset
2169 @samp{;;;###autoload} cookies in Emacs Lisp, and for @code{#error}
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17278
diff changeset
2170 directives in C.
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17278
diff changeset
2171 @end table
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17278
diff changeset
2172
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
2173 @node Syntactic Font Lock
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
2174 @subsection Syntactic Font Lock
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
2175
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
2176 Font Lock mode can be used to update @code{syntax-table} properties
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
2177 automatically. This is useful in languages for which a single syntax
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
2178 table by itself is not sufficient.
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
2179
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
2180 @defvar font-lock-syntactic-keywords
50693
17c60796aa6a (font-lock-syntactic-keywords): Fix/expand description.
Dave Love <fx@gnu.org>
parents: 49600
diff changeset
2181 This variable enables and controls syntactic Font Lock. It is
17c60796aa6a (font-lock-syntactic-keywords): Fix/expand description.
Dave Love <fx@gnu.org>
parents: 49600
diff changeset
2182 normally set via @code{font-lock-defaults}. Its value should be a
17c60796aa6a (font-lock-syntactic-keywords): Fix/expand description.
Dave Love <fx@gnu.org>
parents: 49600
diff changeset
2183 list of elements of this form:
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
2184
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
2185 @example
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
2186 (@var{matcher} @var{subexp} @var{syntax} @var{override} @var{laxmatch})
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
2187 @end example
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
2188
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
2189 The parts of this element have the same meanings as in the corresponding
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
2190 sort of element of @code{font-lock-keywords},
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
2191
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
2192 @example
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
2193 (@var{matcher} @var{subexp} @var{facename} @var{override} @var{laxmatch})
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
2194 @end example
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
2195
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
2196 However, instead of specifying the value @var{facename} to use for the
50693
17c60796aa6a (font-lock-syntactic-keywords): Fix/expand description.
Dave Love <fx@gnu.org>
parents: 49600
diff changeset
2197 @code{face} property, it specifies the value @var{syntax} to use for
17c60796aa6a (font-lock-syntactic-keywords): Fix/expand description.
Dave Love <fx@gnu.org>
parents: 49600
diff changeset
2198 the @code{syntax-table} property. Here, @var{syntax} can be a string
17c60796aa6a (font-lock-syntactic-keywords): Fix/expand description.
Dave Love <fx@gnu.org>
parents: 49600
diff changeset
2199 (as taken by @code{modify-syntax-entry}), a syntax table, a cons cell
17c60796aa6a (font-lock-syntactic-keywords): Fix/expand description.
Dave Love <fx@gnu.org>
parents: 49600
diff changeset
2200 (as returned by @code{string-to-syntax}), or an expression whose value
17c60796aa6a (font-lock-syntactic-keywords): Fix/expand description.
Dave Love <fx@gnu.org>
parents: 49600
diff changeset
2201 is one of those two types. @var{override} cannot be @code{prepend} or
17c60796aa6a (font-lock-syntactic-keywords): Fix/expand description.
Dave Love <fx@gnu.org>
parents: 49600
diff changeset
2202 @code{append}.
17c60796aa6a (font-lock-syntactic-keywords): Fix/expand description.
Dave Love <fx@gnu.org>
parents: 49600
diff changeset
2203
17c60796aa6a (font-lock-syntactic-keywords): Fix/expand description.
Dave Love <fx@gnu.org>
parents: 49600
diff changeset
2204 For example, an element of the form:
17c60796aa6a (font-lock-syntactic-keywords): Fix/expand description.
Dave Love <fx@gnu.org>
parents: 49600
diff changeset
2205
17c60796aa6a (font-lock-syntactic-keywords): Fix/expand description.
Dave Love <fx@gnu.org>
parents: 49600
diff changeset
2206 @example
17c60796aa6a (font-lock-syntactic-keywords): Fix/expand description.
Dave Love <fx@gnu.org>
parents: 49600
diff changeset
2207 ("\\$\\(#\\)" 1 ".")
17c60796aa6a (font-lock-syntactic-keywords): Fix/expand description.
Dave Love <fx@gnu.org>
parents: 49600
diff changeset
2208 @end example
17c60796aa6a (font-lock-syntactic-keywords): Fix/expand description.
Dave Love <fx@gnu.org>
parents: 49600
diff changeset
2209
17c60796aa6a (font-lock-syntactic-keywords): Fix/expand description.
Dave Love <fx@gnu.org>
parents: 49600
diff changeset
2210 highlights syntactically a hash character when following a dollar
17c60796aa6a (font-lock-syntactic-keywords): Fix/expand description.
Dave Love <fx@gnu.org>
parents: 49600
diff changeset
2211 character, with a SYNTAX of @code{"."} (meaning punctuation syntax).
17c60796aa6a (font-lock-syntactic-keywords): Fix/expand description.
Dave Love <fx@gnu.org>
parents: 49600
diff changeset
2212 Assuming that the buffer syntax table specifies hash characters to
17c60796aa6a (font-lock-syntactic-keywords): Fix/expand description.
Dave Love <fx@gnu.org>
parents: 49600
diff changeset
2213 have comment start syntax, the element will only highlight hash
17c60796aa6a (font-lock-syntactic-keywords): Fix/expand description.
Dave Love <fx@gnu.org>
parents: 49600
diff changeset
2214 characters that do not follow dollar characters as comments
17c60796aa6a (font-lock-syntactic-keywords): Fix/expand description.
Dave Love <fx@gnu.org>
parents: 49600
diff changeset
2215 syntactically.
17c60796aa6a (font-lock-syntactic-keywords): Fix/expand description.
Dave Love <fx@gnu.org>
parents: 49600
diff changeset
2216
17c60796aa6a (font-lock-syntactic-keywords): Fix/expand description.
Dave Love <fx@gnu.org>
parents: 49600
diff changeset
2217 An element of the form:
17c60796aa6a (font-lock-syntactic-keywords): Fix/expand description.
Dave Love <fx@gnu.org>
parents: 49600
diff changeset
2218
17c60796aa6a (font-lock-syntactic-keywords): Fix/expand description.
Dave Love <fx@gnu.org>
parents: 49600
diff changeset
2219 @example
17c60796aa6a (font-lock-syntactic-keywords): Fix/expand description.
Dave Love <fx@gnu.org>
parents: 49600
diff changeset
2220 ("\\('\\).\\('\\)"
17c60796aa6a (font-lock-syntactic-keywords): Fix/expand description.
Dave Love <fx@gnu.org>
parents: 49600
diff changeset
2221 (1 "\"")
17c60796aa6a (font-lock-syntactic-keywords): Fix/expand description.
Dave Love <fx@gnu.org>
parents: 49600
diff changeset
2222 (2 "\""))
17c60796aa6a (font-lock-syntactic-keywords): Fix/expand description.
Dave Love <fx@gnu.org>
parents: 49600
diff changeset
2223 @end example
17c60796aa6a (font-lock-syntactic-keywords): Fix/expand description.
Dave Love <fx@gnu.org>
parents: 49600
diff changeset
2224
17c60796aa6a (font-lock-syntactic-keywords): Fix/expand description.
Dave Love <fx@gnu.org>
parents: 49600
diff changeset
2225 highlights syntactically both single quotes which surround a single
17c60796aa6a (font-lock-syntactic-keywords): Fix/expand description.
Dave Love <fx@gnu.org>
parents: 49600
diff changeset
2226 character, with a SYNTAX of @code{"\""} (meaning string quote syntax).
17c60796aa6a (font-lock-syntactic-keywords): Fix/expand description.
Dave Love <fx@gnu.org>
parents: 49600
diff changeset
2227 Assuming that the buffer syntax table does not specify single quotes
17c60796aa6a (font-lock-syntactic-keywords): Fix/expand description.
Dave Love <fx@gnu.org>
parents: 49600
diff changeset
2228 to have quote syntax, the element will only highlight single quotes of
17c60796aa6a (font-lock-syntactic-keywords): Fix/expand description.
Dave Love <fx@gnu.org>
parents: 49600
diff changeset
2229 the form @samp{'@var{c}'} as strings syntactically. Other forms, such
17c60796aa6a (font-lock-syntactic-keywords): Fix/expand description.
Dave Love <fx@gnu.org>
parents: 49600
diff changeset
2230 as @samp{foo'bar} or @samp{'fubar'}, will not be highlighted as
17c60796aa6a (font-lock-syntactic-keywords): Fix/expand description.
Dave Love <fx@gnu.org>
parents: 49600
diff changeset
2231 strings.
17c60796aa6a (font-lock-syntactic-keywords): Fix/expand description.
Dave Love <fx@gnu.org>
parents: 49600
diff changeset
2232
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
2233 @end defvar
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
2234
6451
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2235 @node Hooks
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2236 @section Hooks
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2237 @cindex hooks
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2238
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2239 A @dfn{hook} is a variable where you can store a function or functions
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2240 to be called on a particular occasion by an existing program. Emacs
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2241 provides hooks for the sake of customization. Most often, hooks are set
25875
6a17c48b52ef *** empty log message ***
Phillip Rulon <pjr@gnu.org>
parents: 25751
diff changeset
2242 up in the init file (@pxref{Init File}), but Lisp programs can set them also.
6451
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2243 @xref{Standard Hooks}, for a list of standard hook variables.
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2244
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17278
diff changeset
2245 @cindex normal hook
6451
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2246 Most of the hooks in Emacs are @dfn{normal hooks}. These variables
16056
bfe1d6597f08 Explain better about abnormal hooks.
Richard M. Stallman <rms@gnu.org>
parents: 12888
diff changeset
2247 contain lists of functions to be called with no arguments. When the
bfe1d6597f08 Explain better about abnormal hooks.
Richard M. Stallman <rms@gnu.org>
parents: 12888
diff changeset
2248 hook name ends in @samp{-hook}, that tells you it is normal. We try to
bfe1d6597f08 Explain better about abnormal hooks.
Richard M. Stallman <rms@gnu.org>
parents: 12888
diff changeset
2249 make all hooks normal, as much as possible, so that you can use them in
bfe1d6597f08 Explain better about abnormal hooks.
Richard M. Stallman <rms@gnu.org>
parents: 12888
diff changeset
2250 a uniform way.
bfe1d6597f08 Explain better about abnormal hooks.
Richard M. Stallman <rms@gnu.org>
parents: 12888
diff changeset
2251
bfe1d6597f08 Explain better about abnormal hooks.
Richard M. Stallman <rms@gnu.org>
parents: 12888
diff changeset
2252 Every major mode function is supposed to run a normal hook called the
bfe1d6597f08 Explain better about abnormal hooks.
Richard M. Stallman <rms@gnu.org>
parents: 12888
diff changeset
2253 @dfn{mode hook} as the last step of initialization. This makes it easy
bfe1d6597f08 Explain better about abnormal hooks.
Richard M. Stallman <rms@gnu.org>
parents: 12888
diff changeset
2254 for a user to customize the behavior of the mode, by overriding the
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
2255 buffer-local variable assignments already made by the mode. But hooks
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
2256 are used in other contexts too. For example, the hook
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
2257 @code{suspend-hook} runs just before Emacs suspends itself
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
2258 (@pxref{Suspending Emacs}).
6451
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2259
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2260 The recommended way to add a hook function to a normal hook is by
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2261 calling @code{add-hook} (see below). The hook functions may be any of
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2262 the valid kinds of functions that @code{funcall} accepts (@pxref{What Is
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2263 a Function}). Most normal hook variables are initially void;
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2264 @code{add-hook} knows how to deal with this.
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2265
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17278
diff changeset
2266 @cindex abnormal hook
16056
bfe1d6597f08 Explain better about abnormal hooks.
Richard M. Stallman <rms@gnu.org>
parents: 12888
diff changeset
2267 If the hook variable's name does not end with @samp{-hook}, that
25875
6a17c48b52ef *** empty log message ***
Phillip Rulon <pjr@gnu.org>
parents: 25751
diff changeset
2268 indicates it is probably an @dfn{abnormal hook}. Then you should look at its
16056
bfe1d6597f08 Explain better about abnormal hooks.
Richard M. Stallman <rms@gnu.org>
parents: 12888
diff changeset
2269 documentation to see how to use the hook properly.
6451
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2270
16056
bfe1d6597f08 Explain better about abnormal hooks.
Richard M. Stallman <rms@gnu.org>
parents: 12888
diff changeset
2271 If the variable's name ends in @samp{-functions} or @samp{-hooks},
bfe1d6597f08 Explain better about abnormal hooks.
Richard M. Stallman <rms@gnu.org>
parents: 12888
diff changeset
2272 then the value is a list of functions, but it is abnormal in that either
bfe1d6597f08 Explain better about abnormal hooks.
Richard M. Stallman <rms@gnu.org>
parents: 12888
diff changeset
2273 these functions are called with arguments or their values are used in
bfe1d6597f08 Explain better about abnormal hooks.
Richard M. Stallman <rms@gnu.org>
parents: 12888
diff changeset
2274 some way. You can use @code{add-hook} to add a function to the list,
bfe1d6597f08 Explain better about abnormal hooks.
Richard M. Stallman <rms@gnu.org>
parents: 12888
diff changeset
2275 but you must take care in writing the function. (A few of these
43264
91a36592ab22 *** empty log message ***
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 42866
diff changeset
2276 variables, notably those ending in @samp{-hooks}, are actually
91a36592ab22 *** empty log message ***
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 42866
diff changeset
2277 normal hooks which were named before we established the convention of
91a36592ab22 *** empty log message ***
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 42866
diff changeset
2278 using @samp{-hook} for them.)
16056
bfe1d6597f08 Explain better about abnormal hooks.
Richard M. Stallman <rms@gnu.org>
parents: 12888
diff changeset
2279
bfe1d6597f08 Explain better about abnormal hooks.
Richard M. Stallman <rms@gnu.org>
parents: 12888
diff changeset
2280 If the variable's name ends in @samp{-function}, then its value
bfe1d6597f08 Explain better about abnormal hooks.
Richard M. Stallman <rms@gnu.org>
parents: 12888
diff changeset
2281 is just a single function, not a list of functions.
6451
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2282
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
2283 Here's an example that uses a mode hook to turn on Auto Fill mode when
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
2284 in Lisp Interaction mode:
6451
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2285
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2286 @example
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2287 (add-hook 'lisp-interaction-mode-hook 'turn-on-auto-fill)
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2288 @end example
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2289
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2290 At the appropriate time, Emacs uses the @code{run-hooks} function to
12098
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
2291 run particular hooks. This function calls the hook functions that have
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
2292 been added with @code{add-hook}.
6451
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2293
25875
6a17c48b52ef *** empty log message ***
Phillip Rulon <pjr@gnu.org>
parents: 25751
diff changeset
2294 @defun run-hooks &rest hookvars
6451
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2295 This function takes one or more hook variable names as arguments, and
25875
6a17c48b52ef *** empty log message ***
Phillip Rulon <pjr@gnu.org>
parents: 25751
diff changeset
2296 runs each hook in turn. Each argument should be a symbol that is a hook
6a17c48b52ef *** empty log message ***
Phillip Rulon <pjr@gnu.org>
parents: 25751
diff changeset
2297 variable. These arguments are processed in the order specified.
6451
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2298
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2299 If a hook variable has a non-@code{nil} value, that value may be a
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2300 function or a list of functions. If the value is a function (either a
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17278
diff changeset
2301 lambda expression or a symbol with a function definition), it is called.
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17278
diff changeset
2302 If it is a list, the elements are called, in order. The hook functions
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17278
diff changeset
2303 are called with no arguments. Nowadays, storing a single function in
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17278
diff changeset
2304 the hook variable is semi-obsolete; you should always use a list of
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17278
diff changeset
2305 functions.
6451
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2306
12098
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
2307 For example, here's how @code{emacs-lisp-mode} runs its mode hook:
6451
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2308
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2309 @example
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2310 (run-hooks 'emacs-lisp-mode-hook)
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2311 @end example
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2312 @end defun
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2313
22138
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
2314 @defun run-hook-with-args hook &rest args
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
2315 This function is the way to run an abnormal hook which passes arguments
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
2316 to the hook functions. It calls each of the hook functions, passing
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
2317 each of them the arguments @var{args}.
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
2318 @end defun
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
2319
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
2320 @defun run-hook-with-args-until-failure hook &rest args
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
2321 This function is the way to run an abnormal hook which passes arguments
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
2322 to the hook functions, and stops as soon as any hook function fails. It
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
2323 calls each of the hook functions, passing each of them the arguments
22252
40089afa2b1d *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22138
diff changeset
2324 @var{args}, until some hook function returns @code{nil}. Then it stops,
25875
6a17c48b52ef *** empty log message ***
Phillip Rulon <pjr@gnu.org>
parents: 25751
diff changeset
2325 and returns @code{nil} if some hook function returned @code{nil}.
6a17c48b52ef *** empty log message ***
Phillip Rulon <pjr@gnu.org>
parents: 25751
diff changeset
2326 Otherwise it returns a non-@code{nil} value.
22138
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
2327 @end defun
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
2328
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
2329 @defun run-hook-with-args-until-success hook &rest args
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
2330 This function is the way to run an abnormal hook which passes arguments
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
2331 to the hook functions, and stops as soon as any hook function succeeds.
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
2332 It calls each of the hook functions, passing each of them the arguments
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
2333 @var{args}, until some hook function returns non-@code{nil}. Then it
22252
40089afa2b1d *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22138
diff changeset
2334 stops, and returns whatever was returned by the last hook function
40089afa2b1d *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22138
diff changeset
2335 that was called.
22138
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
2336 @end defun
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
2337
12067
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 8960
diff changeset
2338 @defun add-hook hook function &optional append local
6451
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2339 This function is the handy way to add function @var{function} to hook
7253
6ba87aed7836 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6451
diff changeset
2340 variable @var{hook}. The argument @var{function} may be any valid Lisp
6ba87aed7836 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6451
diff changeset
2341 function with the proper number of arguments. For example,
6451
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2342
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2343 @example
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2344 (add-hook 'text-mode-hook 'my-text-hook-function)
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2345 @end example
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2346
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2347 @noindent
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2348 adds @code{my-text-hook-function} to the hook called @code{text-mode-hook}.
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2349
7253
6ba87aed7836 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6451
diff changeset
2350 You can use @code{add-hook} for abnormal hooks as well as for normal
6ba87aed7836 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6451
diff changeset
2351 hooks.
6ba87aed7836 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6451
diff changeset
2352
6451
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2353 It is best to design your hook functions so that the order in which they
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2354 are executed does not matter. Any dependence on the order is ``asking
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2355 for trouble.'' However, the order is predictable: normally,
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2356 @var{function} goes at the front of the hook list, so it will be
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
2357 executed first (barring another @code{add-hook} call). If the optional
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
2358 argument @var{append} is non-@code{nil}, the new hook function goes at
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
2359 the end of the hook list and will be executed last.
6451
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2360
43264
91a36592ab22 *** empty log message ***
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 42866
diff changeset
2361 If @var{local} is non-@code{nil}, that says to add @var{function}
91a36592ab22 *** empty log message ***
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 42866
diff changeset
2362 to the buffer-local hook list instead of to the global hook list.
6451
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2363 @end defun
8929
d7dc9a5b8c70 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 8505
diff changeset
2364
12067
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 8960
diff changeset
2365 @defun remove-hook hook function &optional local
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 8960
diff changeset
2366 This function removes @var{function} from the hook variable @var{hook}.
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 8960
diff changeset
2367
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 8960
diff changeset
2368 If @var{local} is non-@code{nil}, that says to remove @var{function}
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
2369 from the buffer-local hook list instead of from the global hook list.
12067
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 8960
diff changeset
2370 @end defun