annotate lispref/modes.texi @ 83583:c933949cdadb

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