annotate lispref/modes.texi @ 62432:fc93171e5d7c

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