annotate lispref/modes.texi @ 58708:60340bd28043

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