annotate lispref/modes.texi @ 16842:72276b334084 before-thomas-posix1996 glibc-2_0_2 libc-970108 libc-970109 libc-970110 libc-970111 libc-970112 libc-970113 libc-970114 libc-970115 libc-970116 libc-970117 libc-970118 libc-970119 libc-970120 libc-970121 libc-970122 libc-970123 libc-970124 libc-970125 libc-970126 libc-970127 libc-970128 libc-970129 libc-970130 libc-970131 libc-970201 libc-970202 libc-970203 libc-970204 libc-970205 libc-970206 libc-970207 libc-970208 libc-970209 libc-970210 libc-970211 libc-970212 libc-970213 libc-970214 libc-970215 libc-970216 libc-970217 libc-970218 libc-970219 libc-970220 libc-970221 libc-970222 libc-970223 libc-970224 libc-970225 libc-970226 libc-970227 libc-970228 libc-970301 libc-970302 libc-970303 libc-970304 libc-970305 libc-970306 libc-970307 libc-970308 libc-970309 libc-970310 libc-970311 libc-970312 libc-970313 libc-970314 libc-970315 libc-970316 libc-970317 libc-970318 libc-970319 libc-970320 libc-970321 libc-970322 libc-970323 libc-970324 libc20x-970306 libc20x-97031 libc20x-970316 libc20x-970318 libc20x-970319 libc20x-970404 root-libc-2_0_x-branch

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