annotate doc/lispref/modes.texi @ 112453:06719a229a46 default tip

* calc/calc.el (calc-default-power-reference-level) (calc-default-field-reference-level): New variables. * calc/calc-units.el (math-standard-units): Add dB and Np. (math-logunits): New variable. (math-extract-logunits, math-logcombine, calcFunc-luplus) (calcFunc-luminus, calc-luplus, calc-luminus, math-logunit-level) (calcFunc-fieldlevel, calcFunc-powerlevel, calc-level): New functions. (math-find-base-units-rec): Add entry for ln(10). * calc/calc-help.el (calc-u-prefix-help): Add logarithmic help. (calc-ul-prefix-help): New function. * calc/calc-ext.el (calc-init-extensions): Autoload new units functions. Add keybindings for new units functions.
author Jay Belanger <jay.p.belanger@gmail.com>
date Sun, 23 Jan 2011 23:08:04 -0600
parents 417b1e4d63cd
children
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
84089
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1 @c -*-texinfo-*-
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2 @c This is part of the GNU Emacs Lisp Reference Manual.
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3 @c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998, 1999, 2001,
112218
376148b31b5e Add 2011 to FSF/AIST copyright years.
Glenn Morris <rgm@gnu.org>
parents: 112075
diff changeset
4 @c 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011 Free Software Foundation, Inc.
84089
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5 @c See the file elisp.texi for copying conditions.
84116
0ba80d073e27 (setfilename): Go up one more level to ../../info.
Glenn Morris <rgm@gnu.org>
parents: 84089
diff changeset
6 @setfilename ../../info/modes
84089
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7 @node Modes, Documentation, Keymaps, Top
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8 @chapter Major and Minor Modes
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9 @cindex mode
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11 A @dfn{mode} is a set of definitions that customize Emacs and can be
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12 turned on and off while you edit. There are two varieties of modes:
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13 @dfn{major modes}, which are mutually exclusive and used for editing
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14 particular kinds of text, and @dfn{minor modes}, which provide features
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15 that users can enable individually.
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17 This chapter describes how to write both major and minor modes, how to
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18 indicate them in the mode line, and how they run hooks supplied by the
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19 user. For related topics such as keymaps and syntax tables, see
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20 @ref{Keymaps}, and @ref{Syntax Tables}.
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22 @menu
111887
0eb10986b8f2 * doc/lispref/backups.texi (Making Backups):
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 109948
diff changeset
23 * Hooks:: How to use hooks; how to write code that provides hooks.
0eb10986b8f2 * doc/lispref/backups.texi (Making Backups):
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 109948
diff changeset
24 * Major Modes:: Defining major modes.
0eb10986b8f2 * doc/lispref/backups.texi (Making Backups):
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 109948
diff changeset
25 * Minor Modes:: Defining minor modes.
0eb10986b8f2 * doc/lispref/backups.texi (Making Backups):
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 109948
diff changeset
26 * Mode Line Format:: Customizing the text that appears in the mode line.
111918
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
27 * Imenu:: How a mode can provide a menu
84089
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
28 of definitions in the buffer.
111918
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
29 * Font Lock Mode:: How modes can highlight text according to syntax.
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
30 * Auto-Indentation:: How to teach Emacs to indent for a major mode.
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
31 * Desktop Save Mode:: How modes can have buffer state saved between
84089
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
32 Emacs sessions.
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
33 @end menu
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
34
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
35 @node Hooks
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
36 @section Hooks
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
37 @cindex hooks
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
38
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
39 A @dfn{hook} is a variable where you can store a function or functions
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
40 to be called on a particular occasion by an existing program. Emacs
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
41 provides hooks for the sake of customization. Most often, hooks are set
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
42 up in the init file (@pxref{Init File}), but Lisp programs can set them also.
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
43 @xref{Standard Hooks}, for a list of standard hook variables.
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
44
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
45 @cindex normal hook
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
46 Most of the hooks in Emacs are @dfn{normal hooks}. These variables
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
47 contain lists of functions to be called with no arguments. By
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
48 convention, whenever the hook name ends in @samp{-hook}, that tells
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
49 you it is normal. We try to make all hooks normal, as much as
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
50 possible, so that you can use them in a uniform way.
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
51
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
52 Every major mode function is supposed to run a normal hook called
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
53 the @dfn{mode hook} as the one of the last steps of initialization.
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
54 This makes it easy for a user to customize the behavior of the mode,
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
55 by overriding the buffer-local variable assignments already made by
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
56 the mode. Most minor mode functions also run a mode hook at the end.
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
57 But hooks are used in other contexts too. For example, the hook
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
58 @code{suspend-hook} runs just before Emacs suspends itself
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
59 (@pxref{Suspending Emacs}).
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
60
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
61 The recommended way to add a hook function to a normal hook is by
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
62 calling @code{add-hook} (see below). The hook functions may be any of
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
63 the valid kinds of functions that @code{funcall} accepts (@pxref{What
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
64 Is a Function}). Most normal hook variables are initially void;
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
65 @code{add-hook} knows how to deal with this. You can add hooks either
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
66 globally or buffer-locally with @code{add-hook}.
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
67
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
68 @cindex abnormal hook
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
69 If the hook variable's name does not end with @samp{-hook}, that
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
70 indicates it is probably an @dfn{abnormal hook}. That means the hook
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
71 functions are called with arguments, or their return values are used
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
72 in some way. The hook's documentation says how the functions are
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
73 called. You can use @code{add-hook} to add a function to an abnormal
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
74 hook, but you must write the function to follow the hook's calling
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
75 convention.
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
76
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
77 By convention, abnormal hook names end in @samp{-functions} or
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
78 @samp{-hooks}. If the variable's name ends in @samp{-function}, then
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
79 its value is just a single function, not a list of functions.
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
80
87981
8eba27dae69a (Running Hooks, Setting Hooks): New nodes.
Richard M. Stallman <rms@gnu.org>
parents: 87649
diff changeset
81 @menu
111887
0eb10986b8f2 * doc/lispref/backups.texi (Making Backups):
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 109948
diff changeset
82 * Running Hooks:: How to run a hook.
0eb10986b8f2 * doc/lispref/backups.texi (Making Backups):
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 109948
diff changeset
83 * Setting Hooks:: How to put functions on a hook, or remove them.
87981
8eba27dae69a (Running Hooks, Setting Hooks): New nodes.
Richard M. Stallman <rms@gnu.org>
parents: 87649
diff changeset
84 @end menu
8eba27dae69a (Running Hooks, Setting Hooks): New nodes.
Richard M. Stallman <rms@gnu.org>
parents: 87649
diff changeset
85
8eba27dae69a (Running Hooks, Setting Hooks): New nodes.
Richard M. Stallman <rms@gnu.org>
parents: 87649
diff changeset
86 @node Running Hooks
8eba27dae69a (Running Hooks, Setting Hooks): New nodes.
Richard M. Stallman <rms@gnu.org>
parents: 87649
diff changeset
87 @subsection Running Hooks
8eba27dae69a (Running Hooks, Setting Hooks): New nodes.
Richard M. Stallman <rms@gnu.org>
parents: 87649
diff changeset
88
8eba27dae69a (Running Hooks, Setting Hooks): New nodes.
Richard M. Stallman <rms@gnu.org>
parents: 87649
diff changeset
89 At the appropriate times, Emacs uses the @code{run-hooks} function
8eba27dae69a (Running Hooks, Setting Hooks): New nodes.
Richard M. Stallman <rms@gnu.org>
parents: 87649
diff changeset
90 and the other functions below to run particular hooks.
84089
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
91
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
92 @defun run-hooks &rest hookvars
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
93 This function takes one or more normal hook variable names as
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
94 arguments, and runs each hook in turn. Each argument should be a
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
95 symbol that is a normal hook variable. These arguments are processed
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
96 in the order specified.
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
97
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
98 If a hook variable has a non-@code{nil} value, that value should be a
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
99 list of functions. @code{run-hooks} calls all the functions, one by
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
100 one, with no arguments.
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
101
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
102 The hook variable's value can also be a single function---either a
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
103 lambda expression or a symbol with a function definition---which
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
104 @code{run-hooks} calls. But this usage is obsolete.
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
105 @end defun
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
106
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
107 @defun run-hook-with-args hook &rest args
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
108 This function is the way to run an abnormal hook and always call all
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
109 of the hook functions. It calls each of the hook functions one by
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
110 one, passing each of them the arguments @var{args}.
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
111 @end defun
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
112
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
113 @defun run-hook-with-args-until-failure hook &rest args
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
114 This function is the way to run an abnormal hook until one of the hook
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
115 functions fails. It calls each of the hook functions, passing each of
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
116 them the arguments @var{args}, until some hook function returns
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
117 @code{nil}. It then stops and returns @code{nil}. If none of the
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
118 hook functions return @code{nil}, it returns a non-@code{nil} value.
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
119 @end defun
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
120
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
121 @defun run-hook-with-args-until-success hook &rest args
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
122 This function is the way to run an abnormal hook until a hook function
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
123 succeeds. It calls each of the hook functions, passing each of them
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
124 the arguments @var{args}, until some hook function returns
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
125 non-@code{nil}. Then it stops, and returns whatever was returned by
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
126 the last hook function that was called. If all hook functions return
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
127 @code{nil}, it returns @code{nil} as well.
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
128 @end defun
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
129
87981
8eba27dae69a (Running Hooks, Setting Hooks): New nodes.
Richard M. Stallman <rms@gnu.org>
parents: 87649
diff changeset
130 @node Setting Hooks
8eba27dae69a (Running Hooks, Setting Hooks): New nodes.
Richard M. Stallman <rms@gnu.org>
parents: 87649
diff changeset
131 @subsection Setting Hooks
8eba27dae69a (Running Hooks, Setting Hooks): New nodes.
Richard M. Stallman <rms@gnu.org>
parents: 87649
diff changeset
132
8eba27dae69a (Running Hooks, Setting Hooks): New nodes.
Richard M. Stallman <rms@gnu.org>
parents: 87649
diff changeset
133 Here's an example that uses a mode hook to turn on Auto Fill mode when
8eba27dae69a (Running Hooks, Setting Hooks): New nodes.
Richard M. Stallman <rms@gnu.org>
parents: 87649
diff changeset
134 in Lisp Interaction mode:
8eba27dae69a (Running Hooks, Setting Hooks): New nodes.
Richard M. Stallman <rms@gnu.org>
parents: 87649
diff changeset
135
8eba27dae69a (Running Hooks, Setting Hooks): New nodes.
Richard M. Stallman <rms@gnu.org>
parents: 87649
diff changeset
136 @example
8eba27dae69a (Running Hooks, Setting Hooks): New nodes.
Richard M. Stallman <rms@gnu.org>
parents: 87649
diff changeset
137 (add-hook 'lisp-interaction-mode-hook 'turn-on-auto-fill)
8eba27dae69a (Running Hooks, Setting Hooks): New nodes.
Richard M. Stallman <rms@gnu.org>
parents: 87649
diff changeset
138 @end example
8eba27dae69a (Running Hooks, Setting Hooks): New nodes.
Richard M. Stallman <rms@gnu.org>
parents: 87649
diff changeset
139
84089
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
140 @defun add-hook hook function &optional append local
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
141 This function is the handy way to add function @var{function} to hook
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
142 variable @var{hook}. You can use it for abnormal hooks as well as for
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
143 normal hooks. @var{function} can be any Lisp function that can accept
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
144 the proper number of arguments for @var{hook}. For example,
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
145
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
146 @example
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
147 (add-hook 'text-mode-hook 'my-text-hook-function)
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
148 @end example
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
149
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
150 @noindent
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
151 adds @code{my-text-hook-function} to the hook called @code{text-mode-hook}.
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
152
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
153 If @var{function} is already present in @var{hook} (comparing using
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
154 @code{equal}), then @code{add-hook} does not add it a second time.
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
155
87981
8eba27dae69a (Running Hooks, Setting Hooks): New nodes.
Richard M. Stallman <rms@gnu.org>
parents: 87649
diff changeset
156 If @var{function} has a non-@code{nil} property
8eba27dae69a (Running Hooks, Setting Hooks): New nodes.
Richard M. Stallman <rms@gnu.org>
parents: 87649
diff changeset
157 @code{permanent-local-hook}, then @code{kill-all-local-variables} (or
8eba27dae69a (Running Hooks, Setting Hooks): New nodes.
Richard M. Stallman <rms@gnu.org>
parents: 87649
diff changeset
158 changing major modes) won't delete it from the hook variable's local
8eba27dae69a (Running Hooks, Setting Hooks): New nodes.
Richard M. Stallman <rms@gnu.org>
parents: 87649
diff changeset
159 value.
8eba27dae69a (Running Hooks, Setting Hooks): New nodes.
Richard M. Stallman <rms@gnu.org>
parents: 87649
diff changeset
160
102763
e81a0c5f14b1 (Major Mode Conventions): Note that specialness is inherited.
Chong Yidong <cyd@stupidchicken.com>
parents: 102151
diff changeset
161 It is best to design your hook functions so that the order in which
e81a0c5f14b1 (Major Mode Conventions): Note that specialness is inherited.
Chong Yidong <cyd@stupidchicken.com>
parents: 102151
diff changeset
162 they are executed does not matter. Any dependence on the order is
e81a0c5f14b1 (Major Mode Conventions): Note that specialness is inherited.
Chong Yidong <cyd@stupidchicken.com>
parents: 102151
diff changeset
163 asking for trouble. However, the order is predictable: normally,
84089
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
164 @var{function} goes at the front of the hook list, so it will be
102763
e81a0c5f14b1 (Major Mode Conventions): Note that specialness is inherited.
Chong Yidong <cyd@stupidchicken.com>
parents: 102151
diff changeset
165 executed first (barring another @code{add-hook} call). If the
e81a0c5f14b1 (Major Mode Conventions): Note that specialness is inherited.
Chong Yidong <cyd@stupidchicken.com>
parents: 102151
diff changeset
166 optional argument @var{append} is non-@code{nil}, the new hook
e81a0c5f14b1 (Major Mode Conventions): Note that specialness is inherited.
Chong Yidong <cyd@stupidchicken.com>
parents: 102151
diff changeset
167 function goes at the end of the hook list and will be executed last.
84089
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
168
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
169 @code{add-hook} can handle the cases where @var{hook} is void or its
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
170 value is a single function; it sets or changes the value to a list of
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
171 functions.
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
172
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
173 If @var{local} is non-@code{nil}, that says to add @var{function} to
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
174 the buffer-local hook list instead of to the global hook list. If
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
175 needed, this makes the hook buffer-local and adds @code{t} to the
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
176 buffer-local value. The latter acts as a flag to run the hook
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
177 functions in the default value as well as in the local value.
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
178 @end defun
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
179
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
180 @defun remove-hook hook function &optional local
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
181 This function removes @var{function} from the hook variable
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
182 @var{hook}. It compares @var{function} with elements of @var{hook}
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
183 using @code{equal}, so it works for both symbols and lambda
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
184 expressions.
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
185
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
186 If @var{local} is non-@code{nil}, that says to remove @var{function}
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
187 from the buffer-local hook list instead of from the global hook list.
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
188 @end defun
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
189
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
190 @node Major Modes
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
191 @section Major Modes
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
192 @cindex major mode
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
193
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
194 Major modes specialize Emacs for editing particular kinds of text.
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
195 Each buffer has only one major mode at a time. For each major mode
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
196 there is a function to switch to that mode in the current buffer; its
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
197 name should end in @samp{-mode}. These functions work by setting
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
198 buffer-local variable bindings and other data associated with the
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
199 buffer, such as a local keymap. The effect lasts until you switch
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
200 to another major mode in the same buffer.
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
201
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
202 @menu
111887
0eb10986b8f2 * doc/lispref/backups.texi (Making Backups):
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 109948
diff changeset
203 * Major Mode Basics::
0eb10986b8f2 * doc/lispref/backups.texi (Making Backups):
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 109948
diff changeset
204 * Major Mode Conventions:: Coding conventions for keymaps, etc.
0eb10986b8f2 * doc/lispref/backups.texi (Making Backups):
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 109948
diff changeset
205 * Auto Major Mode:: How Emacs chooses the major mode automatically.
0eb10986b8f2 * doc/lispref/backups.texi (Making Backups):
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 109948
diff changeset
206 * Mode Help:: Finding out how to use a mode.
0eb10986b8f2 * doc/lispref/backups.texi (Making Backups):
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 109948
diff changeset
207 * Derived Modes:: Defining a new major mode based on another major
84089
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
208 mode.
111887
0eb10986b8f2 * doc/lispref/backups.texi (Making Backups):
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 109948
diff changeset
209 * Generic Modes:: Defining a simple major mode that supports
84089
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
210 comment syntax and Font Lock mode.
111887
0eb10986b8f2 * doc/lispref/backups.texi (Making Backups):
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 109948
diff changeset
211 * Mode Hooks:: Hooks run at the end of major mode functions.
0eb10986b8f2 * doc/lispref/backups.texi (Making Backups):
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 109948
diff changeset
212 * Example Major Modes:: Text mode and Lisp modes.
84089
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
213 @end menu
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
214
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
215 @node Major Mode Basics
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
216 @subsection Major Mode Basics
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
217 @cindex Fundamental mode
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
218
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
219 The least specialized major mode is called @dfn{Fundamental mode}.
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
220 This mode has no mode-specific definitions or variable settings, so each
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
221 Emacs command behaves in its default manner, and each option is in its
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
222 default state. All other major modes redefine various keys and options.
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
223 For example, Lisp Interaction mode provides special key bindings for
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
224 @kbd{C-j} (@code{eval-print-last-sexp}), @key{TAB}
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
225 (@code{lisp-indent-line}), and other keys.
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
226
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
227 When you need to write several editing commands to help you perform a
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
228 specialized editing task, creating a new major mode is usually a good
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
229 idea. In practice, writing a major mode is easy (in contrast to
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
230 writing a minor mode, which is often difficult).
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
231
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
232 If the new mode is similar to an old one, it is often unwise to
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
233 modify the old one to serve two purposes, since it may become harder
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
234 to use and maintain. Instead, copy and rename an existing major mode
102763
e81a0c5f14b1 (Major Mode Conventions): Note that specialness is inherited.
Chong Yidong <cyd@stupidchicken.com>
parents: 102151
diff changeset
235 definition and alter the copy---or use the @code{define-derived-mode}
e81a0c5f14b1 (Major Mode Conventions): Note that specialness is inherited.
Chong Yidong <cyd@stupidchicken.com>
parents: 102151
diff changeset
236 macro to define a @dfn{derived mode} (@pxref{Derived Modes}). For
e81a0c5f14b1 (Major Mode Conventions): Note that specialness is inherited.
Chong Yidong <cyd@stupidchicken.com>
parents: 102151
diff changeset
237 example, Rmail Edit mode is a major mode that is very similar to Text
e81a0c5f14b1 (Major Mode Conventions): Note that specialness is inherited.
Chong Yidong <cyd@stupidchicken.com>
parents: 102151
diff changeset
238 mode except that it provides two additional commands. Its definition
e81a0c5f14b1 (Major Mode Conventions): Note that specialness is inherited.
Chong Yidong <cyd@stupidchicken.com>
parents: 102151
diff changeset
239 is distinct from that of Text mode, but uses that of Text mode.
84089
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
240
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
241 Even if the new mode is not an obvious derivative of any other mode,
111887
0eb10986b8f2 * doc/lispref/backups.texi (Making Backups):
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 109948
diff changeset
242 we recommend to use @code{define-derived-mode}, since it automatically
0eb10986b8f2 * doc/lispref/backups.texi (Making Backups):
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 109948
diff changeset
243 enforces the most important coding conventions for you.
84089
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
244
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
245 For a very simple programming language major mode that handles
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
246 comments and fontification, you can use @code{define-generic-mode}.
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
247 @xref{Generic Modes}.
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
248
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
249 Rmail Edit mode offers an example of changing the major mode
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
250 temporarily for a buffer, so it can be edited in a different way (with
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
251 ordinary Emacs commands rather than Rmail commands). In such cases, the
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
252 temporary major mode usually provides a command to switch back to the
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
253 buffer's usual mode (Rmail mode, in this case). You might be tempted to
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
254 present the temporary redefinitions inside a recursive edit and restore
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
255 the usual ones when the user exits; but this is a bad idea because it
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
256 constrains the user's options when it is done in more than one buffer:
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
257 recursive edits must be exited most-recently-entered first. Using an
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
258 alternative major mode avoids this limitation. @xref{Recursive
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
259 Editing}.
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
260
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
261 The standard GNU Emacs Lisp library directory tree contains the code
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
262 for several major modes, in files such as @file{text-mode.el},
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
263 @file{texinfo.el}, @file{lisp-mode.el}, @file{c-mode.el}, and
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
264 @file{rmail.el}. They are found in various subdirectories of the
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
265 @file{lisp} directory. You can study these libraries to see how modes
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
266 are written. Text mode is perhaps the simplest major mode aside from
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
267 Fundamental mode. Rmail mode is a complicated and specialized mode.
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
268
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
269 @node Major Mode Conventions
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
270 @subsection Major Mode Conventions
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
271 @cindex major mode conventions
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
272 @cindex conventions for writing major modes
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
273
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
274 The code for existing major modes follows various coding conventions,
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
275 including conventions for local keymap and syntax table initialization,
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
276 global names, and hooks. Please follow these conventions when you
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
277 define a new major mode. (Fundamental mode is an exception to many
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
278 of these conventions, because its definition is to present the global
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
279 state of Emacs.)
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
280
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
281 This list of conventions is only partial, because each major mode
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
282 should aim for consistency in general with other Emacs major modes.
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
283 This makes Emacs as a whole more coherent. It is impossible to list
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
284 here all the possible points where this issue might come up; if the
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
285 Emacs developers point out an area where your major mode deviates from
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
286 the usual conventions, please make it compatible.
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
287
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
288 @itemize @bullet
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
289 @item
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
290 Define a command whose name ends in @samp{-mode}, with no arguments,
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
291 that switches to the new mode in the current buffer. This command
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
292 should set up the keymap, syntax table, and buffer-local variables in an
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
293 existing buffer, without changing the buffer's contents.
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
294
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
295 @item
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
296 Write a documentation string for this command that describes the
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
297 special commands available in this mode. @kbd{C-h m}
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
298 (@code{describe-mode}) in your mode will display this string.
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
299
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
300 The documentation string may include the special documentation
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
301 substrings, @samp{\[@var{command}]}, @samp{\@{@var{keymap}@}}, and
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
302 @samp{\<@var{keymap}>}, which enable the documentation to adapt
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
303 automatically to the user's own key bindings. @xref{Keys in
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
304 Documentation}.
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
305
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
306 @item
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
307 The major mode command should start by calling
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
308 @code{kill-all-local-variables}. This runs the normal hook
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
309 @code{change-major-mode-hook}, then gets rid of the buffer-local
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
310 variables of the major mode previously in effect. @xref{Creating
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
311 Buffer-Local}.
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
312
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
313 @item
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
314 The major mode command should set the variable @code{major-mode} to the
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
315 major mode command symbol. This is how @code{describe-mode} discovers
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
316 which documentation to print.
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
317
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
318 @item
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
319 The major mode command should set the variable @code{mode-name} to the
98729
a0397c75f952 (Major Mode Conventions, Mode Line Variables): `mode-name' need not be a
Eli Zaretskii <eliz@gnu.org>
parents: 87981
diff changeset
320 ``pretty'' name of the mode, usually a string (but see @ref{Mode Line
a0397c75f952 (Major Mode Conventions, Mode Line Variables): `mode-name' need not be a
Eli Zaretskii <eliz@gnu.org>
parents: 87981
diff changeset
321 Data}, for other possible forms). The name of the mode appears
a0397c75f952 (Major Mode Conventions, Mode Line Variables): `mode-name' need not be a
Eli Zaretskii <eliz@gnu.org>
parents: 87981
diff changeset
322 in the mode line.
84089
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
323
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
324 @item
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
325 @cindex functions in modes
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
326 Since all global names are in the same name space, all the global
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
327 variables, constants, and functions that are part of the mode should
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
328 have names that start with the major mode name (or with an abbreviation
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
329 of it if the name is long). @xref{Coding Conventions}.
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
330
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
331 @item
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
332 In a major mode for editing some kind of structured text, such as a
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
333 programming language, indentation of text according to structure is
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
334 probably useful. So the mode should set @code{indent-line-function}
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
335 to a suitable function, and probably customize other variables
111918
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
336 for indentation. @xref{Auto-Indentation}.
84089
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
337
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
338 @item
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
339 @cindex keymaps in modes
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
340 The major mode should usually have its own keymap, which is used as the
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
341 local keymap in all buffers in that mode. The major mode command should
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
342 call @code{use-local-map} to install this local map. @xref{Active
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
343 Keymaps}, for more information.
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
344
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
345 This keymap should be stored permanently in a global variable named
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
346 @code{@var{modename}-mode-map}. Normally the library that defines the
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
347 mode sets this variable.
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
348
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
349 @xref{Tips for Defining}, for advice about how to write the code to set
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
350 up the mode's keymap variable.
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
351
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
352 @item
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
353 The key sequences bound in a major mode keymap should usually start with
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
354 @kbd{C-c}, followed by a control character, a digit, or @kbd{@{},
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
355 @kbd{@}}, @kbd{<}, @kbd{>}, @kbd{:} or @kbd{;}. The other punctuation
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
356 characters are reserved for minor modes, and ordinary letters are
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
357 reserved for users.
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
358
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
359 A major mode can also rebind the keys @kbd{M-n}, @kbd{M-p} and
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
360 @kbd{M-s}. The bindings for @kbd{M-n} and @kbd{M-p} should normally
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
361 be some kind of ``moving forward and backward,'' but this does not
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
362 necessarily mean cursor motion.
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
363
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
364 It is legitimate for a major mode to rebind a standard key sequence if
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
365 it provides a command that does ``the same job'' in a way better
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
366 suited to the text this mode is used for. For example, a major mode
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
367 for editing a programming language might redefine @kbd{C-M-a} to
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
368 ``move to the beginning of a function'' in a way that works better for
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
369 that language.
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
370
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
371 It is also legitimate for a major mode to rebind a standard key
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
372 sequence whose standard meaning is rarely useful in that mode. For
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
373 instance, minibuffer modes rebind @kbd{M-r}, whose standard meaning is
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
374 rarely of any use in the minibuffer. Major modes such as Dired or
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
375 Rmail that do not allow self-insertion of text can reasonably redefine
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
376 letters and other printing characters as special commands.
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
377
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
378 @item
102151
328f4b370b74 Remove duplicate words.
Juanma Barranquero <lekktu@gmail.com>
parents: 101567
diff changeset
379 Major modes for editing text should not define @key{RET} to do
84089
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
380 anything other than insert a newline. However, it is ok for
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
381 specialized modes for text that users don't directly edit, such as
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
382 Dired and Info modes, to redefine @key{RET} to do something entirely
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
383 different.
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
384
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
385 @item
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
386 Major modes should not alter options that are primarily a matter of user
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
387 preference, such as whether Auto-Fill mode is enabled. Leave this to
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
388 each user to decide. However, a major mode should customize other
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
389 variables so that Auto-Fill mode will work usefully @emph{if} the user
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
390 decides to use it.
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
391
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
392 @item
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
393 @cindex syntax tables in modes
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
394 The mode may have its own syntax table or may share one with other
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
395 related modes. If it has its own syntax table, it should store this in
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
396 a variable named @code{@var{modename}-mode-syntax-table}. @xref{Syntax
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
397 Tables}.
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
398
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
399 @item
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
400 If the mode handles a language that has a syntax for comments, it should
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
401 set the variables that define the comment syntax. @xref{Options for
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
402 Comments,, Options Controlling Comments, emacs, The GNU Emacs Manual}.
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
403
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
404 @item
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
405 @cindex abbrev tables in modes
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
406 The mode may have its own abbrev table or may share one with other
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
407 related modes. If it has its own abbrev table, it should store this
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
408 in a variable named @code{@var{modename}-mode-abbrev-table}. If the
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
409 major mode command defines any abbrevs itself, it should pass @code{t}
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
410 for the @var{system-flag} argument to @code{define-abbrev}.
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
411 @xref{Defining Abbrevs}.
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
412
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
413 @item
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
414 The mode should specify how to do highlighting for Font Lock mode, by
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
415 setting up a buffer-local value for the variable
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
416 @code{font-lock-defaults} (@pxref{Font Lock Mode}).
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
417
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
418 @item
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
419 The mode should specify how Imenu should find the definitions or
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
420 sections of a buffer, by setting up a buffer-local value for the
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
421 variable @code{imenu-generic-expression}, for the two variables
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
422 @code{imenu-prev-index-position-function} and
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
423 @code{imenu-extract-index-name-function}, or for the variable
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
424 @code{imenu-create-index-function} (@pxref{Imenu}).
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
425
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
426 @item
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
427 The mode can specify a local value for
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
428 @code{eldoc-documentation-function} to tell ElDoc mode how to handle
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
429 this mode.
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
430
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
431 @item
111887
0eb10986b8f2 * doc/lispref/backups.texi (Making Backups):
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 109948
diff changeset
432 The mode can specify how to complete various keywords by adding
0eb10986b8f2 * doc/lispref/backups.texi (Making Backups):
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 109948
diff changeset
433 to the special hook @code{completion-at-point-functions}.
0eb10986b8f2 * doc/lispref/backups.texi (Making Backups):
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 109948
diff changeset
434
0eb10986b8f2 * doc/lispref/backups.texi (Making Backups):
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 109948
diff changeset
435 @item
84089
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
436 Use @code{defvar} or @code{defcustom} to set mode-related variables, so
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
437 that they are not reinitialized if they already have a value. (Such
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
438 reinitialization could discard customizations made by the user.)
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
439
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
440 @item
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
441 @cindex buffer-local variables in modes
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
442 To make a buffer-local binding for an Emacs customization variable, use
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
443 @code{make-local-variable} in the major mode command, not
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
444 @code{make-variable-buffer-local}. The latter function would make the
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
445 variable local to every buffer in which it is subsequently set, which
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
446 would affect buffers that do not use this mode. It is undesirable for a
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
447 mode to have such global effects. @xref{Buffer-Local Variables}.
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
448
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
449 With rare exceptions, the only reasonable way to use
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
450 @code{make-variable-buffer-local} in a Lisp package is for a variable
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
451 which is used only within that package. Using it on a variable used by
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
452 other packages would interfere with them.
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
453
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
454 @item
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
455 @cindex mode hook
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
456 @cindex major mode hook
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
457 Each major mode should have a normal @dfn{mode hook} named
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
458 @code{@var{modename}-mode-hook}. The very last thing the major mode command
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
459 should do is to call @code{run-mode-hooks}. This runs the mode hook,
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
460 and then runs the normal hook @code{after-change-major-mode-hook}.
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
461 @xref{Mode Hooks}.
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
462
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
463 @item
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
464 The major mode command may start by calling some other major mode
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
465 command (called the @dfn{parent mode}) and then alter some of its
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
466 settings. A mode that does this is called a @dfn{derived mode}. The
102763
e81a0c5f14b1 (Major Mode Conventions): Note that specialness is inherited.
Chong Yidong <cyd@stupidchicken.com>
parents: 102151
diff changeset
467 recommended way to define one is to use the @code{define-derived-mode}
e81a0c5f14b1 (Major Mode Conventions): Note that specialness is inherited.
Chong Yidong <cyd@stupidchicken.com>
parents: 102151
diff changeset
468 macro, but this is not required. Such a mode should call the parent
e81a0c5f14b1 (Major Mode Conventions): Note that specialness is inherited.
Chong Yidong <cyd@stupidchicken.com>
parents: 102151
diff changeset
469 mode command inside a @code{delay-mode-hooks} form. (Using
84089
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
470 @code{define-derived-mode} does this automatically.) @xref{Derived
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
471 Modes}, and @ref{Mode Hooks}.
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
472
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
473 @item
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
474 If something special should be done if the user switches a buffer from
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
475 this mode to any other major mode, this mode can set up a buffer-local
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
476 value for @code{change-major-mode-hook} (@pxref{Creating Buffer-Local}).
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
477
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
478 @item
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
479 If this mode is appropriate only for specially-prepared text, then the
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
480 major mode command symbol should have a property named @code{mode-class}
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
481 with value @code{special}, put on as follows:
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
482
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
483 @kindex mode-class @r{(property)}
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
484 @cindex @code{special}
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
485 @example
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
486 (put 'funny-mode 'mode-class 'special)
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
487 @end example
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
488
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
489 @noindent
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
490 This tells Emacs that new buffers created while the current buffer is
104626
caa79498564a * subr.el (default-mode-line-format, default-header-line-format)
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 103821
diff changeset
491 in Funny mode should not inherit Funny mode, in case the default value
caa79498564a * subr.el (default-mode-line-format, default-header-line-format)
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 103821
diff changeset
492 of @code{major-mode} is @code{nil}. Modes such as Dired, Rmail,
84089
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
493 and Buffer List use this feature.
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
494
102763
e81a0c5f14b1 (Major Mode Conventions): Note that specialness is inherited.
Chong Yidong <cyd@stupidchicken.com>
parents: 102151
diff changeset
495 The @code{define-derived-mode} macro automatically marks the derived
e81a0c5f14b1 (Major Mode Conventions): Note that specialness is inherited.
Chong Yidong <cyd@stupidchicken.com>
parents: 102151
diff changeset
496 mode as special if the parent mode is special. The special mode
e81a0c5f14b1 (Major Mode Conventions): Note that specialness is inherited.
Chong Yidong <cyd@stupidchicken.com>
parents: 102151
diff changeset
497 @code{special-mode} provides a convenient parent for other special
e81a0c5f14b1 (Major Mode Conventions): Note that specialness is inherited.
Chong Yidong <cyd@stupidchicken.com>
parents: 102151
diff changeset
498 modes to inherit from; it sets @code{buffer-read-only} to @code{t},
111887
0eb10986b8f2 * doc/lispref/backups.texi (Making Backups):
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 109948
diff changeset
499 and does little else.
102763
e81a0c5f14b1 (Major Mode Conventions): Note that specialness is inherited.
Chong Yidong <cyd@stupidchicken.com>
parents: 102151
diff changeset
500
84089
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
501 @item
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
502 If you want to make the new mode the default for files with certain
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
503 recognizable names, add an element to @code{auto-mode-alist} to select
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
504 the mode for those file names (@pxref{Auto Major Mode}). If you
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
505 define the mode command to autoload, you should add this element in
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
506 the same file that calls @code{autoload}. If you use an autoload
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
507 cookie for the mode command, you can also use an autoload cookie for
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
508 the form that adds the element (@pxref{autoload cookie}). If you do
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
509 not autoload the mode command, it is sufficient to add the element in
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
510 the file that contains the mode definition.
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
511
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
512 @item
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
513 In the comments that document the file, you should provide a sample
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
514 @code{autoload} form and an example of how to add to
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
515 @code{auto-mode-alist}, that users can include in their init files
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
516 (@pxref{Init File}).
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
517
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
518 @item
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
519 @cindex mode loading
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
520 The top-level forms in the file defining the mode should be written so
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
521 that they may be evaluated more than once without adverse consequences.
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
522 Even if you never load the file more than once, someone else will.
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
523 @end itemize
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
524
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
525 @node Auto Major Mode
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
526 @subsection How Emacs Chooses a Major Mode
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
527 @cindex major mode, automatic selection
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
528
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
529 Based on information in the file name or in the file itself, Emacs
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
530 automatically selects a major mode for the new buffer when a file is
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
531 visited. It also processes local variables specified in the file text.
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
532
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
533 @deffn Command fundamental-mode
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
534 Fundamental mode is a major mode that is not specialized for anything
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
535 in particular. Other major modes are defined in effect by comparison
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
536 with this one---their definitions say what to change, starting from
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
537 Fundamental mode. The @code{fundamental-mode} function does @emph{not}
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
538 run any mode hooks; you're not supposed to customize it. (If you want Emacs
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
539 to behave differently in Fundamental mode, change the @emph{global}
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
540 state of Emacs.)
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
541 @end deffn
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
542
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
543 @deffn Command normal-mode &optional find-file
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
544 This function establishes the proper major mode and buffer-local variable
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
545 bindings for the current buffer. First it calls @code{set-auto-mode}
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
546 (see below), then it runs @code{hack-local-variables} to parse, and
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
547 bind or evaluate as appropriate, the file's local variables
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
548 (@pxref{File Local Variables}).
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
549
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
550 If the @var{find-file} argument to @code{normal-mode} is non-@code{nil},
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
551 @code{normal-mode} assumes that the @code{find-file} function is calling
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
552 it. In this case, it may process local variables in the @samp{-*-}
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
553 line or at the end of the file. The variable
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
554 @code{enable-local-variables} controls whether to do so. @xref{File
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
555 Variables, , Local Variables in Files, emacs, The GNU Emacs Manual},
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
556 for the syntax of the local variables section of a file.
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
557
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
558 If you run @code{normal-mode} interactively, the argument
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
559 @var{find-file} is normally @code{nil}. In this case,
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
560 @code{normal-mode} unconditionally processes any file local variables.
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
561
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
562 If @code{normal-mode} processes the local variables list and this list
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
563 specifies a major mode, that mode overrides any mode chosen by
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
564 @code{set-auto-mode}. If neither @code{set-auto-mode} nor
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
565 @code{hack-local-variables} specify a major mode, the buffer stays in
104626
caa79498564a * subr.el (default-mode-line-format, default-header-line-format)
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 103821
diff changeset
566 the major mode determined by the default value of @code{major-mode}
caa79498564a * subr.el (default-mode-line-format, default-header-line-format)
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 103821
diff changeset
567 (see below).
84089
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
568
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
569 @cindex file mode specification error
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
570 @code{normal-mode} uses @code{condition-case} around the call to the
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
571 major mode function, so errors are caught and reported as a @samp{File
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
572 mode specification error}, followed by the original error message.
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
573 @end deffn
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
574
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
575 @defun set-auto-mode &optional keep-mode-if-same
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
576 @cindex visited file mode
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
577 This function selects the major mode that is appropriate for the
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
578 current buffer. It bases its decision (in order of precedence) on
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
579 the @w{@samp{-*-}} line, on the @w{@samp{#!}} line (using
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
580 @code{interpreter-mode-alist}), on the text at the beginning of the
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
581 buffer (using @code{magic-mode-alist}), and finally on the visited
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
582 file name (using @code{auto-mode-alist}). @xref{Choosing Modes, , How
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
583 Major Modes are Chosen, emacs, The GNU Emacs Manual}. However, this
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
584 function does not look for the @samp{mode:} local variable near the
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
585 end of a file; the @code{hack-local-variables} function does that.
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
586 If @code{enable-local-variables} is @code{nil}, @code{set-auto-mode}
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
587 does not check the @w{@samp{-*-}} line for a mode tag either.
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
588
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
589 If @var{keep-mode-if-same} is non-@code{nil}, this function does not
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
590 call the mode command if the buffer is already in the proper major
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
591 mode. For instance, @code{set-visited-file-name} sets this to
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
592 @code{t} to avoid killing buffer local variables that the user may
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
593 have set.
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
594 @end defun
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
595
104626
caa79498564a * subr.el (default-mode-line-format, default-header-line-format)
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 103821
diff changeset
596 @defopt major-mode
caa79498564a * subr.el (default-mode-line-format, default-header-line-format)
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 103821
diff changeset
597 The buffer-local value of this variable holds the major mode
caa79498564a * subr.el (default-mode-line-format, default-header-line-format)
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 103821
diff changeset
598 currently active. The default value of this variable holds the
caa79498564a * subr.el (default-mode-line-format, default-header-line-format)
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 103821
diff changeset
599 default major mode for new buffers. The standard default value is
caa79498564a * subr.el (default-mode-line-format, default-header-line-format)
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 103821
diff changeset
600 @code{fundamental-mode}.
caa79498564a * subr.el (default-mode-line-format, default-header-line-format)
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 103821
diff changeset
601
caa79498564a * subr.el (default-mode-line-format, default-header-line-format)
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 103821
diff changeset
602 If the default value of @code{major-mode} is @code{nil}, Emacs uses
84089
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
603 the (previously) current buffer's major mode as the default major mode
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
604 of a new buffer. However, if that major mode symbol has a @code{mode-class}
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
605 property with value @code{special}, then it is not used for new buffers;
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
606 Fundamental mode is used instead. The modes that have this property are
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
607 those such as Dired and Rmail that are useful only with text that has
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
608 been specially prepared.
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
609 @end defopt
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
610
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
611 @defun set-buffer-major-mode buffer
104626
caa79498564a * subr.el (default-mode-line-format, default-header-line-format)
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 103821
diff changeset
612 This function sets the major mode of @var{buffer} to the default value of
caa79498564a * subr.el (default-mode-line-format, default-header-line-format)
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 103821
diff changeset
613 @code{major-mode}; if that is @code{nil}, it uses the
84089
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
614 current buffer's major mode (if that is suitable). As an exception,
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
615 if @var{buffer}'s name is @samp{*scratch*}, it sets the mode to
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
616 @code{initial-major-mode}.
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
617
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
618 The low-level primitives for creating buffers do not use this function,
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
619 but medium-level commands such as @code{switch-to-buffer} and
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
620 @code{find-file-noselect} use it whenever they create buffers.
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
621 @end defun
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
622
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
623 @defopt initial-major-mode
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
624 @cindex @samp{*scratch*}
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
625 The value of this variable determines the major mode of the initial
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
626 @samp{*scratch*} buffer. The value should be a symbol that is a major
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
627 mode command. The default value is @code{lisp-interaction-mode}.
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
628 @end defopt
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
629
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
630 @defvar interpreter-mode-alist
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
631 This variable specifies major modes to use for scripts that specify a
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
632 command interpreter in a @samp{#!} line. Its value is an alist with
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
633 elements of the form @code{(@var{interpreter} . @var{mode})}; for
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
634 example, @code{("perl" . perl-mode)} is one element present by
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
635 default. The element says to use mode @var{mode} if the file
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
636 specifies an interpreter which matches @var{interpreter}.
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
637 @end defvar
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
638
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
639 @defvar magic-mode-alist
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
640 This variable's value is an alist with elements of the form
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
641 @code{(@var{regexp} . @var{function})}, where @var{regexp} is a
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
642 regular expression and @var{function} is a function or @code{nil}.
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
643 After visiting a file, @code{set-auto-mode} calls @var{function} if
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
644 the text at the beginning of the buffer matches @var{regexp} and
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
645 @var{function} is non-@code{nil}; if @var{function} is @code{nil},
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
646 @code{auto-mode-alist} gets to decide the mode.
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
647 @end defvar
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
648
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
649 @defvar magic-fallback-mode-alist
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
650 This works like @code{magic-mode-alist}, except that it is handled
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
651 only if @code{auto-mode-alist} does not specify a mode for this file.
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
652 @end defvar
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
653
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
654 @defvar auto-mode-alist
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
655 This variable contains an association list of file name patterns
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
656 (regular expressions) and corresponding major mode commands. Usually,
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
657 the file name patterns test for suffixes, such as @samp{.el} and
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
658 @samp{.c}, but this need not be the case. An ordinary element of the
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
659 alist looks like @code{(@var{regexp} . @var{mode-function})}.
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
660
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
661 For example,
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
662
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
663 @smallexample
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
664 @group
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
665 (("\\`/tmp/fol/" . text-mode)
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
666 ("\\.texinfo\\'" . texinfo-mode)
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
667 ("\\.texi\\'" . texinfo-mode)
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
668 @end group
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
669 @group
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
670 ("\\.el\\'" . emacs-lisp-mode)
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
671 ("\\.c\\'" . c-mode)
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
672 ("\\.h\\'" . c-mode)
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
673 @dots{})
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
674 @end group
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
675 @end smallexample
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
676
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
677 When you visit a file whose expanded file name (@pxref{File Name
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
678 Expansion}), with version numbers and backup suffixes removed using
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
679 @code{file-name-sans-versions} (@pxref{File Name Components}), matches
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
680 a @var{regexp}, @code{set-auto-mode} calls the corresponding
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
681 @var{mode-function}. This feature enables Emacs to select the proper
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
682 major mode for most files.
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
683
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
684 If an element of @code{auto-mode-alist} has the form @code{(@var{regexp}
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
685 @var{function} t)}, then after calling @var{function}, Emacs searches
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
686 @code{auto-mode-alist} again for a match against the portion of the file
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
687 name that did not match before. This feature is useful for
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
688 uncompression packages: an entry of the form @code{("\\.gz\\'"
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
689 @var{function} t)} can uncompress the file and then put the uncompressed
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
690 file in the proper mode according to the name sans @samp{.gz}.
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
691
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
692 Here is an example of how to prepend several pattern pairs to
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
693 @code{auto-mode-alist}. (You might use this sort of expression in your
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
694 init file.)
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
695
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
696 @smallexample
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
697 @group
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
698 (setq auto-mode-alist
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
699 (append
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
700 ;; @r{File name (within directory) starts with a dot.}
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
701 '(("/\\.[^/]*\\'" . fundamental-mode)
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
702 ;; @r{File name has no dot.}
99965
df75ffc11cac (Auto Major Mode): Fix example.
Chong Yidong <cyd@stupidchicken.com>
parents: 99694
diff changeset
703 ("/[^\\./]*\\'" . fundamental-mode)
84089
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
704 ;; @r{File name ends in @samp{.C}.}
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
705 ("\\.C\\'" . c++-mode))
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
706 auto-mode-alist))
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
707 @end group
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
708 @end smallexample
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
709 @end defvar
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
710
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
711 @node Mode Help
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
712 @subsection Getting Help about a Major Mode
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
713 @cindex mode help
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
714 @cindex help for major mode
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
715 @cindex documentation for major mode
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
716
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
717 The @code{describe-mode} function is used to provide information
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
718 about major modes. It is normally called with @kbd{C-h m}. The
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
719 @code{describe-mode} function uses the value of @code{major-mode},
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
720 which is why every major mode function needs to set the
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
721 @code{major-mode} variable.
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
722
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
723 @deffn Command describe-mode
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
724 This function displays the documentation of the current major mode.
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
725
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
726 The @code{describe-mode} function calls the @code{documentation}
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
727 function using the value of @code{major-mode} as an argument. Thus, it
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
728 displays the documentation string of the major mode function.
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
729 (@xref{Accessing Documentation}.)
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
730 @end deffn
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
731
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
732 @defvar major-mode
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
733 This buffer-local variable holds the symbol for the current buffer's
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
734 major mode. This symbol should have a function definition that is the
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
735 command to switch to that major mode. The @code{describe-mode}
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
736 function uses the documentation string of the function as the
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
737 documentation of the major mode.
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
738 @end defvar
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
739
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
740 @node Derived Modes
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
741 @subsection Defining Derived Modes
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
742 @cindex derived mode
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
743
111887
0eb10986b8f2 * doc/lispref/backups.texi (Making Backups):
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 109948
diff changeset
744 The recommended way to define a new major mode is to derive it
0eb10986b8f2 * doc/lispref/backups.texi (Making Backups):
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 109948
diff changeset
745 from an existing one using @code{define-derived-mode}. If there is no
0eb10986b8f2 * doc/lispref/backups.texi (Making Backups):
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 109948
diff changeset
746 closely related mode, you can inherit from @code{text-mode},
111995
b4939a7142b0 * doc/lispref/keymaps.texi (Simple Menu Items, Extended Menu Items):
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111945
diff changeset
747 @code{special-mode}, @code{prog-mode}, or in the worst case
b4939a7142b0 * doc/lispref/keymaps.texi (Simple Menu Items, Extended Menu Items):
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111945
diff changeset
748 @code{fundamental-mode}.
84089
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
749
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
750 @defmac define-derived-mode variant parent name docstring keyword-args@dots{} body@dots{}
102766
0862f6b10c6b (Derived Modes): Note that define-derive-mode sets the mode-class
Chong Yidong <cyd@stupidchicken.com>
parents: 102763
diff changeset
751 This macro defines @var{variant} as a major mode command, using
84089
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
752 @var{name} as the string form of the mode name. @var{variant} and
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
753 @var{parent} should be unquoted symbols.
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
754
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
755 The new command @var{variant} is defined to call the function
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
756 @var{parent}, then override certain aspects of that parent mode:
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
757
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
758 @itemize @bullet
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
759 @item
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
760 The new mode has its own sparse keymap, named
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
761 @code{@var{variant}-map}. @code{define-derived-mode}
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
762 makes the parent mode's keymap the parent of the new map, unless
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
763 @code{@var{variant}-map} is already set and already has a parent.
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
764
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
765 @item
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
766 The new mode has its own syntax table, kept in the variable
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
767 @code{@var{variant}-syntax-table}, unless you override this using the
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
768 @code{:syntax-table} keyword (see below). @code{define-derived-mode}
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
769 makes the parent mode's syntax-table the parent of
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
770 @code{@var{variant}-syntax-table}, unless the latter is already set
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
771 and already has a parent different from the standard syntax table.
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
772
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
773 @item
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
774 The new mode has its own abbrev table, kept in the variable
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
775 @code{@var{variant}-abbrev-table}, unless you override this using the
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
776 @code{:abbrev-table} keyword (see below).
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
777
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
778 @item
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
779 The new mode has its own mode hook, @code{@var{variant}-hook}. It
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
780 runs this hook, after running the hooks of its ancestor modes, with
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
781 @code{run-mode-hooks}, as the last thing it does. @xref{Mode Hooks}.
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
782 @end itemize
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
783
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
784 In addition, you can specify how to override other aspects of
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
785 @var{parent} with @var{body}. The command @var{variant}
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
786 evaluates the forms in @var{body} after setting up all its usual
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
787 overrides, just before running the mode hooks.
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
788
102766
0862f6b10c6b (Derived Modes): Note that define-derive-mode sets the mode-class
Chong Yidong <cyd@stupidchicken.com>
parents: 102763
diff changeset
789 If @var{parent} has a non-@code{nil} @code{mode-class} symbol
0862f6b10c6b (Derived Modes): Note that define-derive-mode sets the mode-class
Chong Yidong <cyd@stupidchicken.com>
parents: 102763
diff changeset
790 property, then @code{define-derived-mode} sets the @code{mode-class}
0862f6b10c6b (Derived Modes): Note that define-derive-mode sets the mode-class
Chong Yidong <cyd@stupidchicken.com>
parents: 102763
diff changeset
791 property of @var{variant} to the same value. This ensures, for
0862f6b10c6b (Derived Modes): Note that define-derive-mode sets the mode-class
Chong Yidong <cyd@stupidchicken.com>
parents: 102763
diff changeset
792 example, that if @var{parent} is a special mode, then @var{variant} is
0862f6b10c6b (Derived Modes): Note that define-derive-mode sets the mode-class
Chong Yidong <cyd@stupidchicken.com>
parents: 102763
diff changeset
793 also a special mode (@pxref{Major Mode Conventions}).
0862f6b10c6b (Derived Modes): Note that define-derive-mode sets the mode-class
Chong Yidong <cyd@stupidchicken.com>
parents: 102763
diff changeset
794
84089
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
795 You can also specify @code{nil} for @var{parent}. This gives the new
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
796 mode no parent. Then @code{define-derived-mode} behaves as described
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
797 above, but, of course, omits all actions connected with @var{parent}.
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
798
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
799 The argument @var{docstring} specifies the documentation string for
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
800 the new mode. @code{define-derived-mode} adds some general
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
801 information about the mode's hook, followed by the mode's keymap, at
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
802 the end of this docstring. If you omit @var{docstring},
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
803 @code{define-derived-mode} generates a documentation string.
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
804
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
805 The @var{keyword-args} are pairs of keywords and values. The values
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
806 are evaluated. The following keywords are currently supported:
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
807
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
808 @table @code
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
809 @item :syntax-table
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
810 You can use this to explicitly specify a syntax table for the new
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
811 mode. If you specify a @code{nil} value, the new mode uses the same
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
812 syntax table as @var{parent}, or the standard syntax table if
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
813 @var{parent} is @code{nil}. (Note that this does @emph{not} follow
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
814 the convention used for non-keyword arguments that a @code{nil} value
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
815 is equivalent with not specifying the argument.)
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
816
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
817 @item :abbrev-table
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
818 You can use this to explicitly specify an abbrev table for the new
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
819 mode. If you specify a @code{nil} value, the new mode uses the same
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
820 abbrev table as @var{parent}, or @code{fundamental-mode-abbrev-table}
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
821 if @var{parent} is @code{nil}. (Again, a @code{nil} value is
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
822 @emph{not} equivalent to not specifying this keyword.)
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
823
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
824 @item :group
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
825 If this is specified, the value should be the customization group for
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
826 this mode. (Not all major modes have one.) Only the (still
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
827 experimental and unadvertised) command @code{customize-mode} currently
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
828 uses this. @code{define-derived-mode} does @emph{not} automatically
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
829 define the specified customization group.
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
830 @end table
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
831
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
832 Here is a hypothetical example:
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
833
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
834 @example
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
835 (define-derived-mode hypertext-mode
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
836 text-mode "Hypertext"
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
837 "Major mode for hypertext.
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
838 \\@{hypertext-mode-map@}"
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
839 (setq case-fold-search nil))
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
840
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
841 (define-key hypertext-mode-map
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
842 [down-mouse-3] 'do-hyper-link)
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
843 @end example
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
844
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
845 Do not write an @code{interactive} spec in the definition;
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
846 @code{define-derived-mode} does that automatically.
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
847 @end defmac
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
848
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
849 @node Generic Modes
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
850 @subsection Generic Modes
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
851 @cindex generic mode
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
852
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
853 @dfn{Generic modes} are simple major modes with basic support for
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
854 comment syntax and Font Lock mode. To define a generic mode, use the
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
855 macro @code{define-generic-mode}. See the file @file{generic-x.el}
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
856 for some examples of the use of @code{define-generic-mode}.
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
857
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
858 @defmac define-generic-mode mode comment-list keyword-list font-lock-list auto-mode-list function-list &optional docstring
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
859 This macro defines a generic mode command named @var{mode} (a symbol,
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
860 not quoted). The optional argument @var{docstring} is the
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
861 documentation for the mode command. If you do not supply it,
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
862 @code{define-generic-mode} generates one by default.
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
863
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
864 The argument @var{comment-list} is a list in which each element is
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
865 either a character, a string of one or two characters, or a cons cell.
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
866 A character or a string is set up in the mode's syntax table as a
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
867 ``comment starter.'' If the entry is a cons cell, the @sc{car} is set
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
868 up as a ``comment starter'' and the @sc{cdr} as a ``comment ender.''
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
869 (Use @code{nil} for the latter if you want comments to end at the end
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
870 of the line.) Note that the syntax table mechanism has limitations
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
871 about what comment starters and enders are actually possible.
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
872 @xref{Syntax Tables}.
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
873
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
874 The argument @var{keyword-list} is a list of keywords to highlight
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
875 with @code{font-lock-keyword-face}. Each keyword should be a string.
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
876 Meanwhile, @var{font-lock-list} is a list of additional expressions to
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
877 highlight. Each element of this list should have the same form as an
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
878 element of @code{font-lock-keywords}. @xref{Search-based
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
879 Fontification}.
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
880
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
881 The argument @var{auto-mode-list} is a list of regular expressions to
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
882 add to the variable @code{auto-mode-alist}. They are added by the execution
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
883 of the @code{define-generic-mode} form, not by expanding the macro call.
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
884
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
885 Finally, @var{function-list} is a list of functions for the mode
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
886 command to call for additional setup. It calls these functions just
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
887 before it runs the mode hook variable @code{@var{mode}-hook}.
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
888 @end defmac
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
889
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
890 @node Mode Hooks
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
891 @subsection Mode Hooks
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
892
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
893 Every major mode function should finish by running its mode hook and
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
894 the mode-independent normal hook @code{after-change-major-mode-hook}.
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
895 It does this by calling @code{run-mode-hooks}. If the major mode is a
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
896 derived mode, that is if it calls another major mode (the parent mode)
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
897 in its body, it should do this inside @code{delay-mode-hooks} so that
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
898 the parent won't run these hooks itself. Instead, the derived mode's
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
899 call to @code{run-mode-hooks} runs the parent's mode hook too.
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
900 @xref{Major Mode Conventions}.
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
901
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
902 Emacs versions before Emacs 22 did not have @code{delay-mode-hooks}.
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
903 When user-implemented major modes have not been updated to use it,
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
904 they won't entirely follow these conventions: they may run the
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
905 parent's mode hook too early, or fail to run
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
906 @code{after-change-major-mode-hook}. If you encounter such a major
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
907 mode, please correct it to follow these conventions.
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
908
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
909 When you defined a major mode using @code{define-derived-mode}, it
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
910 automatically makes sure these conventions are followed. If you
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
911 define a major mode ``by hand,'' not using @code{define-derived-mode},
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
912 use the following functions to handle these conventions automatically.
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
913
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
914 @defun run-mode-hooks &rest hookvars
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
915 Major modes should run their mode hook using this function. It is
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
916 similar to @code{run-hooks} (@pxref{Hooks}), but it also runs
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
917 @code{after-change-major-mode-hook}.
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
918
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
919 When this function is called during the execution of a
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
920 @code{delay-mode-hooks} form, it does not run the hooks immediately.
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
921 Instead, it arranges for the next call to @code{run-mode-hooks} to run
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
922 them.
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
923 @end defun
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
924
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
925 @defmac delay-mode-hooks body@dots{}
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
926 When one major mode command calls another, it should do so inside of
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
927 @code{delay-mode-hooks}.
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
928
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
929 This macro executes @var{body}, but tells all @code{run-mode-hooks}
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
930 calls during the execution of @var{body} to delay running their hooks.
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
931 The hooks will actually run during the next call to
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
932 @code{run-mode-hooks} after the end of the @code{delay-mode-hooks}
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
933 construct.
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
934 @end defmac
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
935
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
936 @defvar after-change-major-mode-hook
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
937 This is a normal hook run by @code{run-mode-hooks}. It is run at the
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
938 very end of every properly-written major mode function.
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
939 @end defvar
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
940
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
941 @node Example Major Modes
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
942 @subsection Major Mode Examples
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
943
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
944 Text mode is perhaps the simplest mode besides Fundamental mode.
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
945 Here are excerpts from @file{text-mode.el} that illustrate many of
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
946 the conventions listed above:
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
947
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
948 @smallexample
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
949 @group
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
950 ;; @r{Create the syntax table for this mode.}
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
951 (defvar text-mode-syntax-table
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
952 (let ((st (make-syntax-table)))
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
953 (modify-syntax-entry ?\" ". " st)
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
954 (modify-syntax-entry ?\\ ". " st)
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
955 ;; Add `p' so M-c on `hello' leads to `Hello', not `hello'.
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
956 (modify-syntax-entry ?' "w p" st)
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
957 st)
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
958 "Syntax table used while in `text-mode'.")
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
959 @end group
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
960
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
961 ;; @r{Create the keymap for this mode.}
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
962 @group
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
963 (defvar text-mode-map
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
964 (let ((map (make-sparse-keymap)))
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
965 (define-key map "\e\t" 'ispell-complete-word)
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
966 (define-key map "\es" 'center-line)
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
967 (define-key map "\eS" 'center-paragraph)
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
968 map)
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
969 "Keymap for `text-mode'.
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
970 Many other modes, such as Mail mode, Outline mode
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
971 and Indented Text mode, inherit all the commands
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
972 defined in this map.")
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
973 @end group
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
974 @end smallexample
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
975
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
976 Here is how the actual mode command is defined now:
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
977
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
978 @smallexample
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
979 @group
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
980 (define-derived-mode text-mode nil "Text"
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
981 "Major mode for editing text written for humans to read.
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
982 In this mode, paragraphs are delimited only by blank or white lines.
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
983 You can thus get the full benefit of adaptive filling
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
984 (see the variable `adaptive-fill-mode').
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
985 \\@{text-mode-map@}
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
986 Turning on Text mode runs the normal hook `text-mode-hook'."
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
987 @end group
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
988 @group
111887
0eb10986b8f2 * doc/lispref/backups.texi (Making Backups):
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 109948
diff changeset
989 (set (make-local-variable 'text-mode-variant) t)
84089
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
990 ;; @r{These two lines are a feature added recently.}
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
991 (set (make-local-variable 'require-final-newline)
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
992 mode-require-final-newline)
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
993 (set (make-local-variable 'indent-line-function) 'indent-relative))
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
994 @end group
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
995 @end smallexample
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
996
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
997 @noindent
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
998 (The last line is redundant nowadays, since @code{indent-relative} is
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
999 the default value, and we'll delete it in a future version.)
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1000
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1001 Here is how it was defined formerly, before
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1002 @code{define-derived-mode} existed:
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1003
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1004 @smallexample
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1005 @group
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1006 ;; @r{This isn't needed nowadays, since @code{define-derived-mode} does it.}
111887
0eb10986b8f2 * doc/lispref/backups.texi (Making Backups):
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 109948
diff changeset
1007 (define-abbrev-table 'text-mode-abbrev-table ()
84089
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1008 "Abbrev table used while in text mode.")
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1009 @end group
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1010
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1011 @group
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1012 (defun text-mode ()
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1013 "Major mode for editing text intended for humans to read...
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1014 Special commands: \\@{text-mode-map@}
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1015 @end group
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1016 @group
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1017 Turning on text-mode runs the hook `text-mode-hook'."
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1018 (interactive)
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1019 (kill-all-local-variables)
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1020 (use-local-map text-mode-map)
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1021 @end group
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1022 @group
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1023 (setq local-abbrev-table text-mode-abbrev-table)
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1024 (set-syntax-table text-mode-syntax-table)
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1025 @end group
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1026 @group
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1027 ;; @r{These four lines are absent from the current version}
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1028 ;; @r{not because this is done some other way, but rather}
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1029 ;; @r{because nowadays Text mode uses the normal definition of paragraphs.}
111887
0eb10986b8f2 * doc/lispref/backups.texi (Making Backups):
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 109948
diff changeset
1030 (set (make-local-variable 'paragraph-start)
0eb10986b8f2 * doc/lispref/backups.texi (Making Backups):
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 109948
diff changeset
1031 (concat "[ \t]*$\\|" page-delimiter))
0eb10986b8f2 * doc/lispref/backups.texi (Making Backups):
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 109948
diff changeset
1032 (set (make-local-variable 'paragraph-separate) paragraph-start)
0eb10986b8f2 * doc/lispref/backups.texi (Making Backups):
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 109948
diff changeset
1033 (set (make-local-variable 'indent-line-function) 'indent-relative-maybe)
84089
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1034 @end group
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1035 @group
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1036 (setq mode-name "Text")
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1037 (setq major-mode 'text-mode)
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1038 (run-mode-hooks 'text-mode-hook)) ; @r{Finally, this permits the user to}
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1039 ; @r{customize the mode with a hook.}
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1040 @end group
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1041 @end smallexample
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1042
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1043 @cindex @file{lisp-mode.el}
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1044 The three Lisp modes (Lisp mode, Emacs Lisp mode, and Lisp
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1045 Interaction mode) have more features than Text mode and the code is
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1046 correspondingly more complicated. Here are excerpts from
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1047 @file{lisp-mode.el} that illustrate how these modes are written.
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1048
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1049 @cindex syntax table example
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1050 @smallexample
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1051 @group
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1052 ;; @r{Create mode-specific table variables.}
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1053 (defvar lisp-mode-syntax-table nil "")
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1054 (defvar lisp-mode-abbrev-table nil "")
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1055 @end group
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1056
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1057 @group
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1058 (defvar emacs-lisp-mode-syntax-table
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1059 (let ((table (make-syntax-table)))
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1060 (let ((i 0))
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1061 @end group
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1062
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1063 @group
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1064 ;; @r{Set syntax of chars up to @samp{0} to say they are}
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1065 ;; @r{part of symbol names but not words.}
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1066 ;; @r{(The digit @samp{0} is @code{48} in the @acronym{ASCII} character set.)}
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1067 (while (< i ?0)
106718
afc2be124e6e modes.texi (Example Major Modes): Fix indentation. (Bug#5195)
Eli Zaretskii <eliz@gnu.org>
parents: 104652
diff changeset
1068 (modify-syntax-entry i "_ " table)
afc2be124e6e modes.texi (Example Major Modes): Fix indentation. (Bug#5195)
Eli Zaretskii <eliz@gnu.org>
parents: 104652
diff changeset
1069 (setq i (1+ i)))
84089
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1070 ;; @r{@dots{} similar code follows for other character ranges.}
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1071 @end group
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1072 @group
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1073 ;; @r{Then set the syntax codes for characters that are special in Lisp.}
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1074 (modify-syntax-entry ? " " table)
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1075 (modify-syntax-entry ?\t " " table)
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1076 (modify-syntax-entry ?\f " " table)
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1077 (modify-syntax-entry ?\n "> " table)
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1078 @end group
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1079 @group
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1080 ;; @r{Give CR the same syntax as newline, for selective-display.}
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1081 (modify-syntax-entry ?\^m "> " table)
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1082 (modify-syntax-entry ?\; "< " table)
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1083 (modify-syntax-entry ?` "' " table)
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1084 (modify-syntax-entry ?' "' " table)
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1085 (modify-syntax-entry ?, "' " table)
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1086 @end group
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1087 @group
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1088 ;; @r{@dots{}likewise for many other characters@dots{}}
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1089 (modify-syntax-entry ?\( "() " table)
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1090 (modify-syntax-entry ?\) ")( " table)
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1091 (modify-syntax-entry ?\[ "(] " table)
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1092 (modify-syntax-entry ?\] ")[ " table))
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1093 table))
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1094 @end group
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1095 @group
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1096 ;; @r{Create an abbrev table for lisp-mode.}
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1097 (define-abbrev-table 'lisp-mode-abbrev-table ())
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1098 @end group
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1099 @end smallexample
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1100
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1101 The three modes for Lisp share much of their code. For instance,
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1102 each calls the following function to set various variables:
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1103
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1104 @smallexample
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1105 @group
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1106 (defun lisp-mode-variables (lisp-syntax)
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1107 (when lisp-syntax
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1108 (set-syntax-table lisp-mode-syntax-table))
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1109 (setq local-abbrev-table lisp-mode-abbrev-table)
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1110 @dots{}
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1111 @end group
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1112 @end smallexample
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1113
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1114 In Lisp and most programming languages, we want the paragraph
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1115 commands to treat only blank lines as paragraph separators. And the
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1116 modes should understand the Lisp conventions for comments. The rest of
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1117 @code{lisp-mode-variables} sets this up:
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1118
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1119 @smallexample
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1120 @group
111887
0eb10986b8f2 * doc/lispref/backups.texi (Making Backups):
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 109948
diff changeset
1121 (set (make-local-variable 'paragraph-start) (concat page-delimiter "\\|$" ))
0eb10986b8f2 * doc/lispref/backups.texi (Making Backups):
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 109948
diff changeset
1122 (set (make-local-variable 'paragraph-separate) paragraph-start)
84089
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1123 @dots{}
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1124 @end group
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1125 @group
111887
0eb10986b8f2 * doc/lispref/backups.texi (Making Backups):
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 109948
diff changeset
1126 (set (make-local-variable 'comment-indent-function) 'lisp-comment-indent))
84089
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1127 @dots{}
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1128 @end group
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1129 @end smallexample
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1130
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1131 Each of the different Lisp modes has a slightly different keymap. For
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1132 example, Lisp mode binds @kbd{C-c C-z} to @code{run-lisp}, but the other
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1133 Lisp modes do not. However, all Lisp modes have some commands in
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1134 common. The following code sets up the common commands:
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1135
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1136 @smallexample
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1137 @group
111887
0eb10986b8f2 * doc/lispref/backups.texi (Making Backups):
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 109948
diff changeset
1138 (defvar shared-lisp-mode-map
0eb10986b8f2 * doc/lispref/backups.texi (Making Backups):
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 109948
diff changeset
1139 (let ((map (make-sparse-keymap)))
0eb10986b8f2 * doc/lispref/backups.texi (Making Backups):
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 109948
diff changeset
1140 (define-key shared-lisp-mode-map "\e\C-q" 'indent-sexp)
0eb10986b8f2 * doc/lispref/backups.texi (Making Backups):
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 109948
diff changeset
1141 (define-key shared-lisp-mode-map "\177"
0eb10986b8f2 * doc/lispref/backups.texi (Making Backups):
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 109948
diff changeset
1142 'backward-delete-char-untabify)
0eb10986b8f2 * doc/lispref/backups.texi (Making Backups):
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 109948
diff changeset
1143 map)
84089
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1144 "Keymap for commands shared by all sorts of Lisp modes.")
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1145 @end group
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1146 @end smallexample
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1147
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1148 @noindent
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1149 And here is the code to set up the keymap for Lisp mode:
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1150
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1151 @smallexample
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1152 @group
111887
0eb10986b8f2 * doc/lispref/backups.texi (Making Backups):
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 109948
diff changeset
1153 (defvar lisp-mode-map
0eb10986b8f2 * doc/lispref/backups.texi (Making Backups):
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 109948
diff changeset
1154 (let ((map (make-sparse-keymap)))
0eb10986b8f2 * doc/lispref/backups.texi (Making Backups):
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 109948
diff changeset
1155 (set-keymap-parent map shared-lisp-mode-map)
0eb10986b8f2 * doc/lispref/backups.texi (Making Backups):
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 109948
diff changeset
1156 (define-key map "\e\C-x" 'lisp-eval-defun)
0eb10986b8f2 * doc/lispref/backups.texi (Making Backups):
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 109948
diff changeset
1157 (define-key map "\C-c\C-z" 'run-lisp)
0eb10986b8f2 * doc/lispref/backups.texi (Making Backups):
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 109948
diff changeset
1158 map)
84089
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1159 "Keymap for ordinary Lisp mode...")
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1160 @end group
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1161 @end smallexample
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1162
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1163 Finally, here is the complete major mode function definition for
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1164 Lisp mode.
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1165
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1166 @smallexample
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1167 @group
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1168 (defun lisp-mode ()
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1169 "Major mode for editing Lisp code for Lisps other than GNU Emacs Lisp.
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1170 Commands:
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1171 Delete converts tabs to spaces as it moves back.
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1172 Blank lines separate paragraphs. Semicolons start comments.
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1173 \\@{lisp-mode-map@}
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1174 Note that `run-lisp' may be used either to start an inferior Lisp job
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1175 or to switch back to an existing one.
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1176 @end group
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1177
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1178 @group
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1179 Entry to this mode calls the value of `lisp-mode-hook'
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1180 if that value is non-nil."
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1181 (interactive)
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1182 (kill-all-local-variables)
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1183 @end group
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1184 @group
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1185 (use-local-map lisp-mode-map) ; @r{Select the mode's keymap.}
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1186 (setq major-mode 'lisp-mode) ; @r{This is how @code{describe-mode}}
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1187 ; @r{finds out what to describe.}
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1188 (setq mode-name "Lisp") ; @r{This goes into the mode line.}
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1189 (lisp-mode-variables t) ; @r{This defines various variables.}
111887
0eb10986b8f2 * doc/lispref/backups.texi (Making Backups):
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 109948
diff changeset
1190 (set (make-local-variable 'comment-start-skip)
0eb10986b8f2 * doc/lispref/backups.texi (Making Backups):
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 109948
diff changeset
1191 "\\(\\(^\\|[^\\\\\n]\\)\\(\\\\\\\\\\)*\\)\\(;+\\|#|\\) *")
0eb10986b8f2 * doc/lispref/backups.texi (Making Backups):
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 109948
diff changeset
1192 (set (make-local-variable 'font-lock-keywords-case-fold-search) t)
84089
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1193 @end group
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1194 @group
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1195 (setq imenu-case-fold-search t)
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1196 (set-syntax-table lisp-mode-syntax-table)
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1197 (run-mode-hooks 'lisp-mode-hook)) ; @r{This permits the user to use a}
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1198 ; @r{hook to customize the mode.}
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1199 @end group
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1200 @end smallexample
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1201
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1202 @node Minor Modes
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1203 @section Minor Modes
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1204 @cindex minor mode
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1205
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1206 A @dfn{minor mode} provides features that users may enable or disable
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1207 independently of the choice of major mode. Minor modes can be enabled
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1208 individually or in combination. Minor modes would be better named
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1209 ``generally available, optional feature modes,'' except that such a name
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1210 would be unwieldy.
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1211
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1212 A minor mode is not usually meant as a variation of a single major mode.
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1213 Usually they are general and can apply to many major modes. For
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1214 example, Auto Fill mode works with any major mode that permits text
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1215 insertion. To be general, a minor mode must be effectively independent
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1216 of the things major modes do.
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1217
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1218 A minor mode is often much more difficult to implement than a major
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1219 mode. One reason is that you should be able to activate and deactivate
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1220 minor modes in any order. A minor mode should be able to have its
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1221 desired effect regardless of the major mode and regardless of the other
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1222 minor modes in effect.
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1223
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1224 Often the biggest problem in implementing a minor mode is finding a
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1225 way to insert the necessary hook into the rest of Emacs. Minor mode
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1226 keymaps make this easier than it used to be.
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1227
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1228 @defvar minor-mode-list
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1229 The value of this variable is a list of all minor mode commands.
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1230 @end defvar
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1231
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1232 @menu
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1233 * Minor Mode Conventions:: Tips for writing a minor mode.
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1234 * Keymaps and Minor Modes:: How a minor mode can have its own keymap.
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1235 * Defining Minor Modes:: A convenient facility for defining minor modes.
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1236 @end menu
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1237
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1238 @node Minor Mode Conventions
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1239 @subsection Conventions for Writing Minor Modes
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1240 @cindex minor mode conventions
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1241 @cindex conventions for writing minor modes
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1242
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1243 There are conventions for writing minor modes just as there are for
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1244 major modes. Several of the major mode conventions apply to minor
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1245 modes as well: those regarding the name of the mode initialization
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1246 function, the names of global symbols, the use of a hook at the end of
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1247 the initialization function, and the use of keymaps and other tables.
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1248
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1249 In addition, there are several conventions that are specific to
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1250 minor modes. (The easiest way to follow all the conventions is to use
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1251 the macro @code{define-minor-mode}; @ref{Defining Minor Modes}.)
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1252
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1253 @itemize @bullet
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1254 @item
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1255 @cindex mode variable
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1256 Make a variable whose name ends in @samp{-mode} to control the minor
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1257 mode. We call this the @dfn{mode variable}. The minor mode command
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1258 should set this variable (@code{nil} to disable; anything else to
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1259 enable).
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1260
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1261 If possible, implement the mode so that setting the variable
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1262 automatically enables or disables the mode. Then the minor mode command
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1263 does not need to do anything except set the variable.
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1264
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1265 This variable is used in conjunction with the @code{minor-mode-alist} to
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1266 display the minor mode name in the mode line. It can also enable
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1267 or disable a minor mode keymap. Individual commands or hooks can also
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1268 check the variable's value.
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1269
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1270 If you want the minor mode to be enabled separately in each buffer,
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1271 make the variable buffer-local.
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1272
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1273 @item
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1274 Define a command whose name is the same as the mode variable.
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1275 Its job is to enable and disable the mode by setting the variable.
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1276
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1277 The command should accept one optional argument. If the argument is
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1278 @code{nil}, it should toggle the mode (turn it on if it is off, and
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1279 off if it is on). It should turn the mode on if the argument is a
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1280 positive integer, the symbol @code{t}, or a list whose @sc{car} is one
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1281 of those. It should turn the mode off if the argument is a negative
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1282 integer or zero, the symbol @code{-}, or a list whose @sc{car} is a
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1283 negative integer or zero. The meaning of other arguments is not
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1284 specified.
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1285
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1286 Here is an example taken from the definition of @code{transient-mark-mode}.
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1287 It shows the use of @code{transient-mark-mode} as a variable that enables or
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1288 disables the mode's behavior, and also shows the proper way to toggle,
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1289 enable or disable the minor mode based on the raw prefix argument value.
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1290
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1291 @smallexample
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1292 @group
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1293 (setq transient-mark-mode
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1294 (if (null arg) (not transient-mark-mode)
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1295 (> (prefix-numeric-value arg) 0)))
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1296 @end group
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1297 @end smallexample
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1298
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1299 @item
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1300 Add an element to @code{minor-mode-alist} for each minor mode
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1301 (@pxref{Definition of minor-mode-alist}), if you want to indicate the
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1302 minor mode in the mode line. This element should be a list of the
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1303 following form:
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1304
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1305 @smallexample
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1306 (@var{mode-variable} @var{string})
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1307 @end smallexample
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1308
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1309 Here @var{mode-variable} is the variable that controls enabling of the
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1310 minor mode, and @var{string} is a short string, starting with a space,
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1311 to represent the mode in the mode line. These strings must be short so
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1312 that there is room for several of them at once.
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1313
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1314 When you add an element to @code{minor-mode-alist}, use @code{assq} to
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1315 check for an existing element, to avoid duplication. For example:
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1316
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1317 @smallexample
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1318 @group
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1319 (unless (assq 'leif-mode minor-mode-alist)
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1320 (setq minor-mode-alist
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1321 (cons '(leif-mode " Leif") minor-mode-alist)))
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1322 @end group
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1323 @end smallexample
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1324
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1325 @noindent
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1326 or like this, using @code{add-to-list} (@pxref{List Variables}):
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1327
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1328 @smallexample
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1329 @group
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1330 (add-to-list 'minor-mode-alist '(leif-mode " Leif"))
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1331 @end group
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1332 @end smallexample
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1333 @end itemize
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1334
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1335 Global minor modes distributed with Emacs should if possible support
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1336 enabling and disabling via Custom (@pxref{Customization}). To do this,
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1337 the first step is to define the mode variable with @code{defcustom}, and
109250
d3b4a3311253 * modes.texi (Minor Mode Conventions): Fix typo (Bug#6477).
Chong Yidong <cyd@stupidchicken.com>
parents: 106815
diff changeset
1338 specify @code{:type 'boolean}.
84089
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1339
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1340 If just setting the variable is not sufficient to enable the mode, you
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1341 should also specify a @code{:set} method which enables the mode by
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1342 invoking the mode command. Note in the variable's documentation string that
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1343 setting the variable other than via Custom may not take effect.
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1344
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1345 Also mark the definition with an autoload cookie (@pxref{autoload cookie}),
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1346 and specify a @code{:require} so that customizing the variable will load
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1347 the library that defines the mode. This will copy suitable definitions
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1348 into @file{loaddefs.el} so that users can use @code{customize-option} to
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1349 enable the mode. For example:
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1350
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1351 @smallexample
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1352 @group
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1353
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1354 ;;;###autoload
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1355 (defcustom msb-mode nil
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1356 "Toggle msb-mode.
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1357 Setting this variable directly does not take effect;
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1358 use either \\[customize] or the function `msb-mode'."
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1359 :set 'custom-set-minor-mode
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1360 :initialize 'custom-initialize-default
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1361 :version "20.4"
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1362 :type 'boolean
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1363 :group 'msb
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1364 :require 'msb)
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1365 @end group
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1366 @end smallexample
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1367
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1368 @node Keymaps and Minor Modes
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1369 @subsection Keymaps and Minor Modes
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1370
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1371 Each minor mode can have its own keymap, which is active when the mode
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1372 is enabled. To set up a keymap for a minor mode, add an element to the
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1373 alist @code{minor-mode-map-alist}. @xref{Definition of minor-mode-map-alist}.
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1374
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1375 @cindex @code{self-insert-command}, minor modes
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1376 One use of minor mode keymaps is to modify the behavior of certain
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1377 self-inserting characters so that they do something else as well as
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1378 self-insert. In general, this is the only way to do that, since the
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1379 facilities for customizing @code{self-insert-command} are limited to
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1380 special cases (designed for abbrevs and Auto Fill mode). (Do not try
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1381 substituting your own definition of @code{self-insert-command} for the
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1382 standard one. The editor command loop handles this function specially.)
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1383
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1384 The key sequences bound in a minor mode should consist of @kbd{C-c}
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1385 followed by one of @kbd{.,/?`'"[]\|~!#$%^&*()-_+=}. (The other
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1386 punctuation characters are reserved for major modes.)
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1387
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1388 @node Defining Minor Modes
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1389 @subsection Defining Minor Modes
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1390
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1391 The macro @code{define-minor-mode} offers a convenient way of
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1392 implementing a mode in one self-contained definition.
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1393
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1394 @defmac define-minor-mode mode doc [init-value [lighter [keymap]]] keyword-args@dots{} body@dots{}
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1395 This macro defines a new minor mode whose name is @var{mode} (a
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1396 symbol). It defines a command named @var{mode} to toggle the minor
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1397 mode, with @var{doc} as its documentation string. It also defines a
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1398 variable named @var{mode}, which is set to @code{t} or @code{nil} by
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1399 enabling or disabling the mode. The variable is initialized to
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1400 @var{init-value}. Except in unusual circumstances (see below), this
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1401 value must be @code{nil}.
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1402
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1403 The string @var{lighter} says what to display in the mode line
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1404 when the mode is enabled; if it is @code{nil}, the mode is not displayed
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1405 in the mode line.
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1406
109948
c66428d4b9ed Doc fix for define-minor-mode (Bug#6880).
Chong Yidong <cyd@stupidchicken.com>
parents: 109694
diff changeset
1407 The optional argument @var{keymap} specifies the keymap for the minor
c66428d4b9ed Doc fix for define-minor-mode (Bug#6880).
Chong Yidong <cyd@stupidchicken.com>
parents: 109694
diff changeset
1408 mode. If non-@code{nil}, it should be a variable name (whose value is
c66428d4b9ed Doc fix for define-minor-mode (Bug#6880).
Chong Yidong <cyd@stupidchicken.com>
parents: 109694
diff changeset
1409 a keymap), a keymap, or an alist of the form
84089
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1410
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1411 @example
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1412 (@var{key-sequence} . @var{definition})
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1413 @end example
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1414
109948
c66428d4b9ed Doc fix for define-minor-mode (Bug#6880).
Chong Yidong <cyd@stupidchicken.com>
parents: 109694
diff changeset
1415 @noindent
c66428d4b9ed Doc fix for define-minor-mode (Bug#6880).
Chong Yidong <cyd@stupidchicken.com>
parents: 109694
diff changeset
1416 where each @var{key-sequence} and @var{definition} are arguments
c66428d4b9ed Doc fix for define-minor-mode (Bug#6880).
Chong Yidong <cyd@stupidchicken.com>
parents: 109694
diff changeset
1417 suitable for passing to @code{define-key} (@pxref{Changing Key
c66428d4b9ed Doc fix for define-minor-mode (Bug#6880).
Chong Yidong <cyd@stupidchicken.com>
parents: 109694
diff changeset
1418 Bindings}). If @var{keymap} is a keymap or an alist, this also
c66428d4b9ed Doc fix for define-minor-mode (Bug#6880).
Chong Yidong <cyd@stupidchicken.com>
parents: 109694
diff changeset
1419 defines the variable @code{@var{mode}-map}.
c66428d4b9ed Doc fix for define-minor-mode (Bug#6880).
Chong Yidong <cyd@stupidchicken.com>
parents: 109694
diff changeset
1420
84089
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1421 The above three arguments @var{init-value}, @var{lighter}, and
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1422 @var{keymap} can be (partially) omitted when @var{keyword-args} are
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1423 used. The @var{keyword-args} consist of keywords followed by
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1424 corresponding values. A few keywords have special meanings:
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1425
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1426 @table @code
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1427 @item :group @var{group}
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1428 Custom group name to use in all generated @code{defcustom} forms.
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1429 Defaults to @var{mode} without the possible trailing @samp{-mode}.
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1430 @strong{Warning:} don't use this default group name unless you have
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1431 written a @code{defgroup} to define that group properly. @xref{Group
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1432 Definitions}.
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1433
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1434 @item :global @var{global}
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1435 If non-@code{nil}, this specifies that the minor mode should be global
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1436 rather than buffer-local. It defaults to @code{nil}.
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1437
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1438 One of the effects of making a minor mode global is that the
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1439 @var{mode} variable becomes a customization variable. Toggling it
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1440 through the Custom interface turns the mode on and off, and its value
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1441 can be saved for future Emacs sessions (@pxref{Saving
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1442 Customizations,,, emacs, The GNU Emacs Manual}. For the saved
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1443 variable to work, you should ensure that the @code{define-minor-mode}
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1444 form is evaluated each time Emacs starts; for packages that are not
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1445 part of Emacs, the easiest way to do this is to specify a
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1446 @code{:require} keyword.
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1447
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1448 @item :init-value @var{init-value}
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1449 This is equivalent to specifying @var{init-value} positionally.
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1450
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1451 @item :lighter @var{lighter}
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1452 This is equivalent to specifying @var{lighter} positionally.
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1453
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1454 @item :keymap @var{keymap}
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1455 This is equivalent to specifying @var{keymap} positionally.
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1456 @end table
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1457
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1458 Any other keyword arguments are passed directly to the
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1459 @code{defcustom} generated for the variable @var{mode}.
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1460
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1461 The command named @var{mode} first performs the standard actions such
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1462 as setting the variable named @var{mode} and then executes the
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1463 @var{body} forms, if any. It finishes by running the mode hook
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1464 variable @code{@var{mode}-hook}.
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1465 @end defmac
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1466
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1467 The initial value must be @code{nil} except in cases where (1) the
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1468 mode is preloaded in Emacs, or (2) it is painless for loading to
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1469 enable the mode even though the user did not request it. For
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1470 instance, if the mode has no effect unless something else is enabled,
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1471 and will always be loaded by that time, enabling it by default is
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1472 harmless. But these are unusual circumstances. Normally, the
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1473 initial value must be @code{nil}.
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1474
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1475 @findex easy-mmode-define-minor-mode
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1476 The name @code{easy-mmode-define-minor-mode} is an alias
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1477 for this macro.
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1478
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1479 Here is an example of using @code{define-minor-mode}:
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1480
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1481 @smallexample
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1482 (define-minor-mode hungry-mode
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1483 "Toggle Hungry mode.
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1484 With no argument, this command toggles the mode.
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1485 Non-null prefix argument turns on the mode.
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1486 Null prefix argument turns off the mode.
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1487
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1488 When Hungry mode is enabled, the control delete key
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1489 gobbles all preceding whitespace except the last.
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1490 See the command \\[hungry-electric-delete]."
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1491 ;; The initial value.
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1492 nil
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1493 ;; The indicator for the mode line.
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1494 " Hungry"
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1495 ;; The minor mode bindings.
109694
0208d138c2be * doc/lispref/modes.texi (Defining Minor Modes): Use C-backspace, not C-delete.
Juanma Barranquero <lekktu@gmail.com>
parents: 109347
diff changeset
1496 '(([C-backspace] . hungry-electric-delete))
84089
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1497 :group 'hunger)
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1498 @end smallexample
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1499
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1500 @noindent
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1501 This defines a minor mode named ``Hungry mode,'' a command named
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1502 @code{hungry-mode} to toggle it, a variable named @code{hungry-mode}
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1503 which indicates whether the mode is enabled, and a variable named
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1504 @code{hungry-mode-map} which holds the keymap that is active when the
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1505 mode is enabled. It initializes the keymap with a key binding for
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1506 @kbd{C-@key{DEL}}. It puts the variable @code{hungry-mode} into
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1507 custom group @code{hunger}. There are no @var{body} forms---many
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1508 minor modes don't need any.
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1509
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1510 Here's an equivalent way to write it:
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1511
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1512 @smallexample
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1513 (define-minor-mode hungry-mode
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1514 "Toggle Hungry mode.
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1515 With no argument, this command toggles the mode.
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1516 Non-null prefix argument turns on the mode.
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1517 Null prefix argument turns off the mode.
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1518
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1519 When Hungry mode is enabled, the control delete key
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1520 gobbles all preceding whitespace except the last.
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1521 See the command \\[hungry-electric-delete]."
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1522 ;; The initial value.
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1523 :init-value nil
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1524 ;; The indicator for the mode line.
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1525 :lighter " Hungry"
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1526 ;; The minor mode bindings.
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1527 :keymap
109694
0208d138c2be * doc/lispref/modes.texi (Defining Minor Modes): Use C-backspace, not C-delete.
Juanma Barranquero <lekktu@gmail.com>
parents: 109347
diff changeset
1528 '(([C-backspace] . hungry-electric-delete)
0208d138c2be * doc/lispref/modes.texi (Defining Minor Modes): Use C-backspace, not C-delete.
Juanma Barranquero <lekktu@gmail.com>
parents: 109347
diff changeset
1529 ([C-M-backspace]
84089
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1530 . (lambda ()
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1531 (interactive)
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1532 (hungry-electric-delete t))))
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1533 :group 'hunger)
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1534 @end smallexample
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1535
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1536 @defmac define-globalized-minor-mode global-mode mode turn-on keyword-args@dots{}
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1537 This defines a global toggle named @var{global-mode} whose meaning is
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1538 to enable or disable the buffer-local minor mode @var{mode} in all
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1539 buffers. To turn on the minor mode in a buffer, it uses the function
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1540 @var{turn-on}; to turn off the minor mode, it calls @code{mode} with
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1541 @minus{}1 as argument.
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1542
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1543 Globally enabling the mode also affects buffers subsequently created
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1544 by visiting files, and buffers that use a major mode other than
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1545 Fundamental mode; but it does not detect the creation of a new buffer
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1546 in Fundamental mode.
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1547
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1548 This defines the customization option @var{global-mode} (@pxref{Customization}),
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1549 which can be toggled in the Custom interface to turn the minor mode on
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1550 and off. As with @code{define-minor-mode}, you should ensure that the
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1551 @code{define-globalized-minor-mode} form is evaluated each time Emacs
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1552 starts, for example by providing a @code{:require} keyword.
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1553
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1554 Use @code{:group @var{group}} in @var{keyword-args} to specify the
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1555 custom group for the mode variable of the global minor mode.
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1556 @end defmac
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1557
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1558 @node Mode Line Format
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1559 @section Mode-Line Format
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1560 @cindex mode line
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1561
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1562 Each Emacs window (aside from minibuffer windows) typically has a mode
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1563 line at the bottom, which displays status information about the buffer
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1564 displayed in the window. The mode line contains information about the
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1565 buffer, such as its name, associated file, depth of recursive editing,
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1566 and major and minor modes. A window can also have a @dfn{header
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1567 line}, which is much like the mode line but appears at the top of the
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1568 window.
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1569
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1570 This section describes how to control the contents of the mode line
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1571 and header line. We include it in this chapter because much of the
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1572 information displayed in the mode line relates to the enabled major and
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1573 minor modes.
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1574
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1575 @menu
111887
0eb10986b8f2 * doc/lispref/backups.texi (Making Backups):
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 109948
diff changeset
1576 * Base: Mode Line Basics. Basic ideas of mode line control.
0eb10986b8f2 * doc/lispref/backups.texi (Making Backups):
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 109948
diff changeset
1577 * Data: Mode Line Data. The data structure that controls the mode line.
0eb10986b8f2 * doc/lispref/backups.texi (Making Backups):
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 109948
diff changeset
1578 * Top: Mode Line Top. The top level variable, mode-line-format.
0eb10986b8f2 * doc/lispref/backups.texi (Making Backups):
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 109948
diff changeset
1579 * Mode Line Variables:: Variables used in that data structure.
0eb10986b8f2 * doc/lispref/backups.texi (Making Backups):
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 109948
diff changeset
1580 * %-Constructs:: Putting information into a mode line.
0eb10986b8f2 * doc/lispref/backups.texi (Making Backups):
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 109948
diff changeset
1581 * Properties in Mode:: Using text properties in the mode line.
0eb10986b8f2 * doc/lispref/backups.texi (Making Backups):
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 109948
diff changeset
1582 * Header Lines:: Like a mode line, but at the top.
0eb10986b8f2 * doc/lispref/backups.texi (Making Backups):
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 109948
diff changeset
1583 * Emulating Mode Line:: Formatting text as the mode line would.
84089
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1584 @end menu
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1585
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1586 @node Mode Line Basics
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1587 @subsection Mode Line Basics
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1588
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1589 @code{mode-line-format} is a buffer-local variable that holds a
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1590 @dfn{mode line construct}, a kind of template, which controls what is
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1591 displayed on the mode line of the current buffer. The value of
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1592 @code{header-line-format} specifies the buffer's header line in the
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1593 same way. All windows for the same buffer use the same
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1594 @code{mode-line-format} and @code{header-line-format}.
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1595
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1596 For efficiency, Emacs does not continuously recompute the mode
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1597 line and header line of a window. It does so when circumstances
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1598 appear to call for it---for instance, if you change the window
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1599 configuration, switch buffers, narrow or widen the buffer, scroll, or
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1600 change the buffer's modification status. If you modify any of the
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1601 variables referenced by @code{mode-line-format} (@pxref{Mode Line
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1602 Variables}), or any other variables and data structures that affect
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1603 how text is displayed (@pxref{Display}), you may want to force an
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1604 update of the mode line so as to display the new information or
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1605 display it in the new way.
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1606
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1607 @defun force-mode-line-update &optional all
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1608 Force redisplay of the current buffer's mode line and header line.
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1609 The next redisplay will update the mode line and header line based on
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1610 the latest values of all relevant variables. With optional
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1611 non-@code{nil} @var{all}, force redisplay of all mode lines and header
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1612 lines.
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1613
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1614 This function also forces recomputation of the menu bar menus
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1615 and the frame title.
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1616 @end defun
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1617
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1618 The selected window's mode line is usually displayed in a different
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1619 color using the face @code{mode-line}. Other windows' mode lines
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1620 appear in the face @code{mode-line-inactive} instead. @xref{Faces}.
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1621
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1622 @node Mode Line Data
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1623 @subsection The Data Structure of the Mode Line
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1624 @cindex mode-line construct
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1625
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1626 The mode-line contents are controlled by a data structure called a
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1627 @dfn{mode-line construct}, made up of lists, strings, symbols, and
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1628 numbers kept in buffer-local variables. Each data type has a specific
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1629 meaning for the mode-line appearance, as described below. The same
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1630 data structure is used for constructing frame titles (@pxref{Frame
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1631 Titles}) and header lines (@pxref{Header Lines}).
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1632
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1633 A mode-line construct may be as simple as a fixed string of text,
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1634 but it usually specifies how to combine fixed strings with variables'
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1635 values to construct the text. Many of these variables are themselves
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1636 defined to have mode-line constructs as their values.
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1637
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1638 Here are the meanings of various data types as mode-line constructs:
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1639
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1640 @table @code
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1641 @cindex percent symbol in mode line
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1642 @item @var{string}
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1643 A string as a mode-line construct appears verbatim except for
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1644 @dfn{@code{%}-constructs} in it. These stand for substitution of
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1645 other data; see @ref{%-Constructs}.
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1646
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1647 If parts of the string have @code{face} properties, they control
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1648 display of the text just as they would text in the buffer. Any
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1649 characters which have no @code{face} properties are displayed, by
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1650 default, in the face @code{mode-line} or @code{mode-line-inactive}
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1651 (@pxref{Standard Faces,,, emacs, The GNU Emacs Manual}). The
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1652 @code{help-echo} and @code{local-map} properties in @var{string} have
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1653 special meanings. @xref{Properties in Mode}.
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1654
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1655 @item @var{symbol}
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1656 A symbol as a mode-line construct stands for its value. The value of
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1657 @var{symbol} is used as a mode-line construct, in place of @var{symbol}.
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1658 However, the symbols @code{t} and @code{nil} are ignored, as is any
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1659 symbol whose value is void.
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1660
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1661 There is one exception: if the value of @var{symbol} is a string, it is
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1662 displayed verbatim: the @code{%}-constructs are not recognized.
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1663
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1664 Unless @var{symbol} is marked as ``risky'' (i.e., it has a
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1665 non-@code{nil} @code{risky-local-variable} property), all text
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1666 properties specified in @var{symbol}'s value are ignored. This
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1667 includes the text properties of strings in @var{symbol}'s value, as
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1668 well as all @code{:eval} and @code{:propertize} forms in it. (The
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1669 reason for this is security: non-risky variables could be set
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1670 automatically from file variables without prompting the user.)
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1671
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1672 @item (@var{string} @var{rest}@dots{})
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1673 @itemx (@var{list} @var{rest}@dots{})
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1674 A list whose first element is a string or list means to process all the
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1675 elements recursively and concatenate the results. This is the most
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1676 common form of mode-line construct.
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1677
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1678 @item (:eval @var{form})
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1679 A list whose first element is the symbol @code{:eval} says to evaluate
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1680 @var{form}, and use the result as a string to display. Make sure this
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1681 evaluation cannot load any files, as doing so could cause infinite
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1682 recursion.
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1683
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1684 @item (:propertize @var{elt} @var{props}@dots{})
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1685 A list whose first element is the symbol @code{:propertize} says to
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1686 process the mode-line construct @var{elt} recursively, then add the text
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1687 properties specified by @var{props} to the result. The argument
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1688 @var{props} should consist of zero or more pairs @var{text-property}
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1689 @var{value}. (This feature is new as of Emacs 22.1.)
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1690
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1691 @item (@var{symbol} @var{then} @var{else})
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1692 A list whose first element is a symbol that is not a keyword specifies
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1693 a conditional. Its meaning depends on the value of @var{symbol}. If
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1694 @var{symbol} has a non-@code{nil} value, the second element,
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1695 @var{then}, is processed recursively as a mode-line element.
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1696 Otherwise, the third element, @var{else}, is processed recursively.
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1697 You may omit @var{else}; then the mode-line element displays nothing
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1698 if the value of @var{symbol} is @code{nil} or void.
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1699
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1700 @item (@var{width} @var{rest}@dots{})
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1701 A list whose first element is an integer specifies truncation or
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1702 padding of the results of @var{rest}. The remaining elements
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1703 @var{rest} are processed recursively as mode-line constructs and
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1704 concatenated together. When @var{width} is positive, the result is
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1705 space filled on the right if its width is less than @var{width}. When
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1706 @var{width} is negative, the result is truncated on the right to
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1707 @minus{}@var{width} columns if its width exceeds @minus{}@var{width}.
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1708
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1709 For example, the usual way to show what percentage of a buffer is above
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1710 the top of the window is to use a list like this: @code{(-3 "%p")}.
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1711 @end table
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1712
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1713 @node Mode Line Top
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1714 @subsection The Top Level of Mode Line Control
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1715
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1716 The variable in overall control of the mode line is
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1717 @code{mode-line-format}.
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1718
103273
c32ec20d0ab5 * abbrevs.texi (Abbrev Mode): abbrev-mode is an option.
Martin Rudalics <rudalics@gmx.at>
parents: 103238
diff changeset
1719 @defopt mode-line-format
84089
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1720 The value of this variable is a mode-line construct that controls the
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1721 contents of the mode-line. It is always buffer-local in all buffers.
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1722
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1723 If you set this variable to @code{nil} in a buffer, that buffer does
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1724 not have a mode line. (A window that is just one line tall never
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1725 displays a mode line.)
103273
c32ec20d0ab5 * abbrevs.texi (Abbrev Mode): abbrev-mode is an option.
Martin Rudalics <rudalics@gmx.at>
parents: 103238
diff changeset
1726 @end defopt
84089
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1727
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1728 The default value of @code{mode-line-format} is designed to use the
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1729 values of other variables such as @code{mode-line-position} and
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1730 @code{mode-line-modes} (which in turn incorporates the values of the
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1731 variables @code{mode-name} and @code{minor-mode-alist}). Very few
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1732 modes need to alter @code{mode-line-format} itself. For most
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1733 purposes, it is sufficient to alter some of the variables that
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1734 @code{mode-line-format} either directly or indirectly refers to.
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1735
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1736 If you do alter @code{mode-line-format} itself, the new value should
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1737 use the same variables that appear in the default value (@pxref{Mode
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1738 Line Variables}), rather than duplicating their contents or displaying
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1739 the information in another fashion. This way, customizations made by
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1740 the user or by Lisp programs (such as @code{display-time} and major
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1741 modes) via changes to those variables remain effective.
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1742
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1743 Here is an example of a @code{mode-line-format} that might be
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1744 useful for @code{shell-mode}, since it contains the host name and default
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1745 directory.
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1746
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1747 @example
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1748 @group
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1749 (setq mode-line-format
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1750 (list "-"
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1751 'mode-line-mule-info
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1752 'mode-line-modified
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1753 'mode-line-frame-identification
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1754 "%b--"
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1755 @end group
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1756 @group
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1757 ;; @r{Note that this is evaluated while making the list.}
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1758 ;; @r{It makes a mode-line construct which is just a string.}
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1759 (getenv "HOST")
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1760 @end group
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1761 ":"
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1762 'default-directory
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1763 " "
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1764 'global-mode-string
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1765 " %[("
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1766 '(:eval (mode-line-mode-name))
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1767 'mode-line-process
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1768 'minor-mode-alist
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1769 "%n"
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1770 ")%]--"
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1771 @group
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1772 '(which-func-mode ("" which-func-format "--"))
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1773 '(line-number-mode "L%l--")
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1774 '(column-number-mode "C%c--")
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1775 '(-3 "%p")
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1776 "-%-"))
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1777 @end group
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1778 @end example
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1779
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1780 @noindent
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1781 (The variables @code{line-number-mode}, @code{column-number-mode}
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1782 and @code{which-func-mode} enable particular minor modes; as usual,
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1783 these variable names are also the minor mode command names.)
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1784
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1785 @node Mode Line Variables
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1786 @subsection Variables Used in the Mode Line
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1787
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1788 This section describes variables incorporated by the standard value
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1789 of @code{mode-line-format} into the text of the mode line. There is
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1790 nothing inherently special about these variables; any other variables
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1791 could have the same effects on the mode line if
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1792 @code{mode-line-format}'s value were changed to use them. However,
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1793 various parts of Emacs set these variables on the understanding that
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1794 they will control parts of the mode line; therefore, practically
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1795 speaking, it is essential for the mode line to use them.
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1796
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1797 @defvar mode-line-mule-info
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1798 This variable holds the value of the mode-line construct that displays
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1799 information about the language environment, buffer coding system, and
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1800 current input method. @xref{Non-ASCII Characters}.
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1801 @end defvar
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1802
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1803 @defvar mode-line-modified
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1804 This variable holds the value of the mode-line construct that displays
102775
58dbb2780124 (Mode Line Variables): The default values of the mode
Chong Yidong <cyd@stupidchicken.com>
parents: 102766
diff changeset
1805 whether the current buffer is modified. Its default value displays
58dbb2780124 (Mode Line Variables): The default values of the mode
Chong Yidong <cyd@stupidchicken.com>
parents: 102766
diff changeset
1806 @samp{**} if the buffer is modified, @samp{--} if the buffer is not
58dbb2780124 (Mode Line Variables): The default values of the mode
Chong Yidong <cyd@stupidchicken.com>
parents: 102766
diff changeset
1807 modified, @samp{%%} if the buffer is read only, and @samp{%*} if the
58dbb2780124 (Mode Line Variables): The default values of the mode
Chong Yidong <cyd@stupidchicken.com>
parents: 102766
diff changeset
1808 buffer is read only and modified.
84089
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1809
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1810 Changing this variable does not force an update of the mode line.
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1811 @end defvar
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1812
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1813 @defvar mode-line-frame-identification
102775
58dbb2780124 (Mode Line Variables): The default values of the mode
Chong Yidong <cyd@stupidchicken.com>
parents: 102766
diff changeset
1814 This variable identifies the current frame. Its default value
58dbb2780124 (Mode Line Variables): The default values of the mode
Chong Yidong <cyd@stupidchicken.com>
parents: 102766
diff changeset
1815 displays @code{" "} if you are using a window system which can show
58dbb2780124 (Mode Line Variables): The default values of the mode
Chong Yidong <cyd@stupidchicken.com>
parents: 102766
diff changeset
1816 multiple frames, or @code{"-%F "} on an ordinary terminal which shows
58dbb2780124 (Mode Line Variables): The default values of the mode
Chong Yidong <cyd@stupidchicken.com>
parents: 102766
diff changeset
1817 only one frame at a time.
84089
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1818 @end defvar
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1819
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1820 @defvar mode-line-buffer-identification
102775
58dbb2780124 (Mode Line Variables): The default values of the mode
Chong Yidong <cyd@stupidchicken.com>
parents: 102766
diff changeset
1821 This variable identifies the buffer being displayed in the window.
58dbb2780124 (Mode Line Variables): The default values of the mode
Chong Yidong <cyd@stupidchicken.com>
parents: 102766
diff changeset
1822 Its default value displays the buffer name, padded with spaces to at
58dbb2780124 (Mode Line Variables): The default values of the mode
Chong Yidong <cyd@stupidchicken.com>
parents: 102766
diff changeset
1823 least 12 columns.
84089
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1824 @end defvar
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1825
103273
c32ec20d0ab5 * abbrevs.texi (Abbrev Mode): abbrev-mode is an option.
Martin Rudalics <rudalics@gmx.at>
parents: 103238
diff changeset
1826 @defopt mode-line-position
102775
58dbb2780124 (Mode Line Variables): The default values of the mode
Chong Yidong <cyd@stupidchicken.com>
parents: 102766
diff changeset
1827 This variable indicates the position in the buffer. Its default value
58dbb2780124 (Mode Line Variables): The default values of the mode
Chong Yidong <cyd@stupidchicken.com>
parents: 102766
diff changeset
1828 displays the buffer percentage and, optionally, the buffer size, the
58dbb2780124 (Mode Line Variables): The default values of the mode
Chong Yidong <cyd@stupidchicken.com>
parents: 102766
diff changeset
1829 line number and the column number.
103273
c32ec20d0ab5 * abbrevs.texi (Abbrev Mode): abbrev-mode is an option.
Martin Rudalics <rudalics@gmx.at>
parents: 103238
diff changeset
1830 @end defopt
84089
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1831
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1832 @defvar vc-mode
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1833 The variable @code{vc-mode}, buffer-local in each buffer, records
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1834 whether the buffer's visited file is maintained with version control,
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1835 and, if so, which kind. Its value is a string that appears in the mode
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1836 line, or @code{nil} for no version control.
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1837 @end defvar
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1838
103273
c32ec20d0ab5 * abbrevs.texi (Abbrev Mode): abbrev-mode is an option.
Martin Rudalics <rudalics@gmx.at>
parents: 103238
diff changeset
1839 @defopt mode-line-modes
102775
58dbb2780124 (Mode Line Variables): The default values of the mode
Chong Yidong <cyd@stupidchicken.com>
parents: 102766
diff changeset
1840 This variable displays the buffer's major and minor modes. Its
58dbb2780124 (Mode Line Variables): The default values of the mode
Chong Yidong <cyd@stupidchicken.com>
parents: 102766
diff changeset
1841 default value also displays the recursive editing level, information
58dbb2780124 (Mode Line Variables): The default values of the mode
Chong Yidong <cyd@stupidchicken.com>
parents: 102766
diff changeset
1842 on the process status, and whether narrowing is in effect.
103273
c32ec20d0ab5 * abbrevs.texi (Abbrev Mode): abbrev-mode is an option.
Martin Rudalics <rudalics@gmx.at>
parents: 103238
diff changeset
1843 @end defopt
84089
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1844
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1845 The following three variables are used in @code{mode-line-modes}:
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1846
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1847 @defvar mode-name
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1848 This buffer-local variable holds the ``pretty'' name of the current
98729
a0397c75f952 (Major Mode Conventions, Mode Line Variables): `mode-name' need not be a
Eli Zaretskii <eliz@gnu.org>
parents: 87981
diff changeset
1849 buffer's major mode. Each major mode should set this variable so that
a0397c75f952 (Major Mode Conventions, Mode Line Variables): `mode-name' need not be a
Eli Zaretskii <eliz@gnu.org>
parents: 87981
diff changeset
1850 the mode name will appear in the mode line. The value does not have
a0397c75f952 (Major Mode Conventions, Mode Line Variables): `mode-name' need not be a
Eli Zaretskii <eliz@gnu.org>
parents: 87981
diff changeset
1851 to be a string, but can use any of the data types valid in a mode-line
a0397c75f952 (Major Mode Conventions, Mode Line Variables): `mode-name' need not be a
Eli Zaretskii <eliz@gnu.org>
parents: 87981
diff changeset
1852 construct (@pxref{Mode Line Data}). To compute the string that will
a0397c75f952 (Major Mode Conventions, Mode Line Variables): `mode-name' need not be a
Eli Zaretskii <eliz@gnu.org>
parents: 87981
diff changeset
1853 identify the mode name in the mode line, use @code{format-mode-line}
a0397c75f952 (Major Mode Conventions, Mode Line Variables): `mode-name' need not be a
Eli Zaretskii <eliz@gnu.org>
parents: 87981
diff changeset
1854 (@pxref{Emulating Mode Line}).
84089
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1855 @end defvar
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1856
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1857 @defvar mode-line-process
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1858 This buffer-local variable contains the mode-line information on process
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1859 status in modes used for communicating with subprocesses. It is
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1860 displayed immediately following the major mode name, with no intervening
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1861 space. For example, its value in the @samp{*shell*} buffer is
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1862 @code{(":%s")}, which allows the shell to display its status along
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1863 with the major mode as: @samp{(Shell:run)}. Normally this variable
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1864 is @code{nil}.
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1865 @end defvar
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1866
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1867 @defvar minor-mode-alist
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1868 @anchor{Definition of minor-mode-alist}
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1869 This variable holds an association list whose elements specify how the
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1870 mode line should indicate that a minor mode is active. Each element of
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1871 the @code{minor-mode-alist} should be a two-element list:
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1872
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1873 @example
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1874 (@var{minor-mode-variable} @var{mode-line-string})
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1875 @end example
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1876
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1877 More generally, @var{mode-line-string} can be any mode-line spec. It
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1878 appears in the mode line when the value of @var{minor-mode-variable}
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1879 is non-@code{nil}, and not otherwise. These strings should begin with
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1880 spaces so that they don't run together. Conventionally, the
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1881 @var{minor-mode-variable} for a specific mode is set to a
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1882 non-@code{nil} value when that minor mode is activated.
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1883
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1884 @code{minor-mode-alist} itself is not buffer-local. Each variable
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1885 mentioned in the alist should be buffer-local if its minor mode can be
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1886 enabled separately in each buffer.
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1887 @end defvar
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1888
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1889 @defvar global-mode-string
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1890 This variable holds a mode-line spec that, by default, appears in the
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1891 mode line just after the @code{which-func-mode} minor mode if set,
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1892 else after @code{mode-line-modes}. The command @code{display-time}
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1893 sets @code{global-mode-string} to refer to the variable
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1894 @code{display-time-string}, which holds a string containing the time
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1895 and load information.
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1896
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1897 The @samp{%M} construct substitutes the value of
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1898 @code{global-mode-string}, but that is obsolete, since the variable is
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1899 included in the mode line from @code{mode-line-format}.
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1900 @end defvar
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1901
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1902 Here is a simplified version of the default value of
104626
caa79498564a * subr.el (default-mode-line-format, default-header-line-format)
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 103821
diff changeset
1903 @code{mode-line-format}. The real default value also
84089
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1904 specifies addition of text properties.
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1905
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1906 @example
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1907 @group
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1908 ("-"
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1909 mode-line-mule-info
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1910 mode-line-modified
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1911 mode-line-frame-identification
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1912 mode-line-buffer-identification
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1913 @end group
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1914 " "
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1915 mode-line-position
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1916 (vc-mode vc-mode)
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1917 " "
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1918 @group
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1919 mode-line-modes
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1920 (which-func-mode ("" which-func-format "--"))
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1921 (global-mode-string ("--" global-mode-string))
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1922 "-%-")
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1923 @end group
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1924 @end example
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1925
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1926 @node %-Constructs
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1927 @subsection @code{%}-Constructs in the Mode Line
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1928
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1929 Strings used as mode-line constructs can use certain
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1930 @code{%}-constructs to substitute various kinds of data. Here is a
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1931 list of the defined @code{%}-constructs, and what they mean. In any
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1932 construct except @samp{%%}, you can add a decimal integer after the
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1933 @samp{%} to specify a minimum field width. If the width is less, the
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1934 field is padded with spaces to the right.
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1935
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1936 @table @code
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1937 @item %b
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1938 The current buffer name, obtained with the @code{buffer-name} function.
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1939 @xref{Buffer Names}.
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1940
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1941 @item %c
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1942 The current column number of point.
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1943
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1944 @item %e
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1945 When Emacs is nearly out of memory for Lisp objects, a brief message
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1946 saying so. Otherwise, this is empty.
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1947
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1948 @item %f
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1949 The visited file name, obtained with the @code{buffer-file-name}
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1950 function. @xref{Buffer File Name}.
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1951
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1952 @item %F
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1953 The title (only on a window system) or the name of the selected frame.
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1954 @xref{Basic Parameters}.
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1955
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1956 @item %i
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1957 The size of the accessible part of the current buffer; basically
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1958 @code{(- (point-max) (point-min))}.
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1959
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1960 @item %I
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1961 Like @samp{%i}, but the size is printed in a more readable way by using
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1962 @samp{k} for 10^3, @samp{M} for 10^6, @samp{G} for 10^9, etc., to
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1963 abbreviate.
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1964
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1965 @item %l
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1966 The current line number of point, counting within the accessible portion
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1967 of the buffer.
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1968
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1969 @item %n
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1970 @samp{Narrow} when narrowing is in effect; nothing otherwise (see
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1971 @code{narrow-to-region} in @ref{Narrowing}).
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1972
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1973 @item %p
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1974 The percentage of the buffer text above the @strong{top} of window, or
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1975 @samp{Top}, @samp{Bottom} or @samp{All}. Note that the default
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1976 mode-line specification truncates this to three characters.
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1977
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1978 @item %P
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1979 The percentage of the buffer text that is above the @strong{bottom} of
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1980 the window (which includes the text visible in the window, as well as
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1981 the text above the top), plus @samp{Top} if the top of the buffer is
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1982 visible on screen; or @samp{Bottom} or @samp{All}.
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1983
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1984 @item %s
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1985 The status of the subprocess belonging to the current buffer, obtained with
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1986 @code{process-status}. @xref{Process Information}.
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1987
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1988 @item %t
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1989 Whether the visited file is a text file or a binary file. This is a
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1990 meaningful distinction only on certain operating systems (@pxref{MS-DOS
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1991 File Types}).
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1992
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1993 @item %z
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1994 The mnemonics of keyboard, terminal, and buffer coding systems.
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1995
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1996 @item %Z
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1997 Like @samp{%z}, but including the end-of-line format.
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1998
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1999 @item %*
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2000 @samp{%} if the buffer is read only (see @code{buffer-read-only}); @*
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2001 @samp{*} if the buffer is modified (see @code{buffer-modified-p}); @*
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2002 @samp{-} otherwise. @xref{Buffer Modification}.
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2003
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2004 @item %+
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2005 @samp{*} if the buffer is modified (see @code{buffer-modified-p}); @*
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2006 @samp{%} if the buffer is read only (see @code{buffer-read-only}); @*
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2007 @samp{-} otherwise. This differs from @samp{%*} only for a modified
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2008 read-only buffer. @xref{Buffer Modification}.
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2009
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2010 @item %&
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2011 @samp{*} if the buffer is modified, and @samp{-} otherwise.
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2012
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2013 @item %[
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2014 An indication of the depth of recursive editing levels (not counting
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2015 minibuffer levels): one @samp{[} for each editing level.
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2016 @xref{Recursive Editing}.
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2017
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2018 @item %]
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2019 One @samp{]} for each recursive editing level (not counting minibuffer
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2020 levels).
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2021
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2022 @item %-
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2023 Dashes sufficient to fill the remainder of the mode line.
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2024
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2025 @item %%
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2026 The character @samp{%}---this is how to include a literal @samp{%} in a
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2027 string in which @code{%}-constructs are allowed.
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2028 @end table
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2029
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2030 The following two @code{%}-constructs are still supported, but they are
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2031 obsolete, since you can get the same results with the variables
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2032 @code{mode-name} and @code{global-mode-string}.
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2033
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2034 @table @code
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2035 @item %m
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2036 The value of @code{mode-name}.
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2037
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2038 @item %M
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2039 The value of @code{global-mode-string}.
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2040 @end table
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2041
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2042 @node Properties in Mode
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2043 @subsection Properties in the Mode Line
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2044 @cindex text properties in the mode line
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2045
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2046 Certain text properties are meaningful in the
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2047 mode line. The @code{face} property affects the appearance of text; the
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2048 @code{help-echo} property associates help strings with the text, and
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2049 @code{local-map} can make the text mouse-sensitive.
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2050
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2051 There are four ways to specify text properties for text in the mode
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2052 line:
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2053
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2054 @enumerate
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2055 @item
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2056 Put a string with a text property directly into the mode-line data
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2057 structure.
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2058
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2059 @item
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2060 Put a text property on a mode-line %-construct such as @samp{%12b}; then
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2061 the expansion of the %-construct will have that same text property.
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2062
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2063 @item
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2064 Use a @code{(:propertize @var{elt} @var{props}@dots{})} construct to
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2065 give @var{elt} a text property specified by @var{props}.
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2066
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2067 @item
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2068 Use a list containing @code{:eval @var{form}} in the mode-line data
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2069 structure, and make @var{form} evaluate to a string that has a text
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2070 property.
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2071 @end enumerate
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2072
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2073 You can use the @code{local-map} property to specify a keymap. This
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2074 keymap only takes real effect for mouse clicks; binding character keys
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2075 and function keys to it has no effect, since it is impossible to move
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2076 point into the mode line.
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2077
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2078 When the mode line refers to a variable which does not have a
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2079 non-@code{nil} @code{risky-local-variable} property, any text
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2080 properties given or specified within that variable's values are
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2081 ignored. This is because such properties could otherwise specify
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2082 functions to be called, and those functions could come from file
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2083 local variables.
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2084
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2085 @node Header Lines
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2086 @subsection Window Header Lines
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2087 @cindex header line (of a window)
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2088 @cindex window header line
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2089
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2090 A window can have a @dfn{header line} at the
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2091 top, just as it can have a mode line at the bottom. The header line
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2092 feature works just like the mode-line feature, except that it's
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2093 controlled by different variables.
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2094
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2095 @defvar header-line-format
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2096 This variable, local in every buffer, specifies how to display the
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2097 header line, for windows displaying the buffer. The format of the value
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2098 is the same as for @code{mode-line-format} (@pxref{Mode Line Data}).
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2099 It is normally @code{nil}, so that ordinary buffers have no header line.
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2100 @end defvar
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2101
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2102 A window that is just one line tall never displays a header line. A
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2103 window that is two lines tall cannot display both a mode line and a
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2104 header line at once; if it has a mode line, then it does not display a
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2105 header line.
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2106
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2107 @node Emulating Mode Line
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2108 @subsection Emulating Mode-Line Formatting
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2109
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2110 You can use the function @code{format-mode-line} to compute
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2111 the text that would appear in a mode line or header line
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2112 based on a certain mode-line specification.
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2113
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2114 @defun format-mode-line format &optional face window buffer
112057
60e7c5827df3 Fallout from fixing bug #7587.
Eli Zaretskii <eliz@gnu.org>
parents: 111918
diff changeset
2115 This function formats a line of text according to @var{format} as if it
60e7c5827df3 Fallout from fixing bug #7587.
Eli Zaretskii <eliz@gnu.org>
parents: 111918
diff changeset
2116 were generating the mode line for @var{window}, but it also returns the
60e7c5827df3 Fallout from fixing bug #7587.
Eli Zaretskii <eliz@gnu.org>
parents: 111918
diff changeset
2117 text as a string. The argument @var{window} defaults to the selected
60e7c5827df3 Fallout from fixing bug #7587.
Eli Zaretskii <eliz@gnu.org>
parents: 111918
diff changeset
2118 window. If @var{buffer} is non-@code{nil}, all the information used is
60e7c5827df3 Fallout from fixing bug #7587.
Eli Zaretskii <eliz@gnu.org>
parents: 111918
diff changeset
2119 taken from @var{buffer}; by default, it comes from @var{window}'s
60e7c5827df3 Fallout from fixing bug #7587.
Eli Zaretskii <eliz@gnu.org>
parents: 111918
diff changeset
2120 buffer.
84089
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2121
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2122 The value string normally has text properties that correspond to the
112075
9546b9e764b9 More fallout from fixing bug #7587.
Eli Zaretskii <eliz@gnu.org>
parents: 112057
diff changeset
2123 faces, keymaps, etc., that the mode line would have. Any character for
9546b9e764b9 More fallout from fixing bug #7587.
Eli Zaretskii <eliz@gnu.org>
parents: 112057
diff changeset
2124 which no @code{face} property is specified by @var{format} gets a
9546b9e764b9 More fallout from fixing bug #7587.
Eli Zaretskii <eliz@gnu.org>
parents: 112057
diff changeset
2125 default value determined by @var{face}. If @var{face} is @code{t}, that
9546b9e764b9 More fallout from fixing bug #7587.
Eli Zaretskii <eliz@gnu.org>
parents: 112057
diff changeset
2126 stands for either @code{mode-line} if @var{window} is selected,
9546b9e764b9 More fallout from fixing bug #7587.
Eli Zaretskii <eliz@gnu.org>
parents: 112057
diff changeset
2127 otherwise @code{mode-line-inactive}. If @var{face} is @code{nil} or
9546b9e764b9 More fallout from fixing bug #7587.
Eli Zaretskii <eliz@gnu.org>
parents: 112057
diff changeset
2128 omitted, that stands for the default face. If @var{face} is an integer,
9546b9e764b9 More fallout from fixing bug #7587.
Eli Zaretskii <eliz@gnu.org>
parents: 112057
diff changeset
2129 the value returned by this function will have no text properties.
84089
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2130
112057
60e7c5827df3 Fallout from fixing bug #7587.
Eli Zaretskii <eliz@gnu.org>
parents: 111918
diff changeset
2131 You can also specify other valid faces as the value of @var{face}.
112075
9546b9e764b9 More fallout from fixing bug #7587.
Eli Zaretskii <eliz@gnu.org>
parents: 112057
diff changeset
2132 If specified, that face provides the @code{face} property for characters
9546b9e764b9 More fallout from fixing bug #7587.
Eli Zaretskii <eliz@gnu.org>
parents: 112057
diff changeset
2133 whose face is not specified by @var{format}.
112057
60e7c5827df3 Fallout from fixing bug #7587.
Eli Zaretskii <eliz@gnu.org>
parents: 111918
diff changeset
2134
60e7c5827df3 Fallout from fixing bug #7587.
Eli Zaretskii <eliz@gnu.org>
parents: 111918
diff changeset
2135 Note that using @code{mode-line}, @code{mode-line-inactive}, or
60e7c5827df3 Fallout from fixing bug #7587.
Eli Zaretskii <eliz@gnu.org>
parents: 111918
diff changeset
2136 @code{header-line} as @var{face} will actually redisplay the mode line
60e7c5827df3 Fallout from fixing bug #7587.
Eli Zaretskii <eliz@gnu.org>
parents: 111918
diff changeset
2137 or the header line, respectively, using the current definitions of the
60e7c5827df3 Fallout from fixing bug #7587.
Eli Zaretskii <eliz@gnu.org>
parents: 111918
diff changeset
2138 corresponding face, in addition to returning the formatted string.
60e7c5827df3 Fallout from fixing bug #7587.
Eli Zaretskii <eliz@gnu.org>
parents: 111918
diff changeset
2139 (Other faces do not cause redisplay.)
60e7c5827df3 Fallout from fixing bug #7587.
Eli Zaretskii <eliz@gnu.org>
parents: 111918
diff changeset
2140
84089
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2141 For example, @code{(format-mode-line header-line-format)} returns the
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2142 text that would appear in the selected window's header line (@code{""}
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2143 if it has no header line). @code{(format-mode-line header-line-format
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2144 'header-line)} returns the same text, with each character
112057
60e7c5827df3 Fallout from fixing bug #7587.
Eli Zaretskii <eliz@gnu.org>
parents: 111918
diff changeset
2145 carrying the face that it will have in the header line itself, and also
60e7c5827df3 Fallout from fixing bug #7587.
Eli Zaretskii <eliz@gnu.org>
parents: 111918
diff changeset
2146 redraws the header line.
84089
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2147 @end defun
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2148
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2149 @node Imenu
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2150 @section Imenu
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2151
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2152 @cindex Imenu
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2153 @dfn{Imenu} is a feature that lets users select a definition or
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2154 section in the buffer, from a menu which lists all of them, to go
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2155 directly to that location in the buffer. Imenu works by constructing
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2156 a buffer index which lists the names and buffer positions of the
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2157 definitions, or other named portions of the buffer; then the user can
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2158 choose one of them and move point to it. Major modes can add a menu
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2159 bar item to use Imenu using @code{imenu-add-to-menubar}.
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2160
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2161 @defun imenu-add-to-menubar name
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2162 This function defines a local menu bar item named @var{name}
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2163 to run Imenu.
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2164 @end defun
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2165
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2166 The user-level commands for using Imenu are described in the Emacs
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2167 Manual (@pxref{Imenu,, Imenu, emacs, the Emacs Manual}). This section
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2168 explains how to customize Imenu's method of finding definitions or
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2169 buffer portions for a particular major mode.
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2170
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2171 The usual and simplest way is to set the variable
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2172 @code{imenu-generic-expression}:
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2173
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2174 @defvar imenu-generic-expression
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2175 This variable, if non-@code{nil}, is a list that specifies regular
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2176 expressions for finding definitions for Imenu. Simple elements of
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2177 @code{imenu-generic-expression} look like this:
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2178
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2179 @example
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2180 (@var{menu-title} @var{regexp} @var{index})
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2181 @end example
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2182
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2183 Here, if @var{menu-title} is non-@code{nil}, it says that the matches
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2184 for this element should go in a submenu of the buffer index;
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2185 @var{menu-title} itself specifies the name for the submenu. If
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2186 @var{menu-title} is @code{nil}, the matches for this element go directly
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2187 in the top level of the buffer index.
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2188
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2189 The second item in the list, @var{regexp}, is a regular expression
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2190 (@pxref{Regular Expressions}); anything in the buffer that it matches
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2191 is considered a definition, something to mention in the buffer index.
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2192 The third item, @var{index}, is a non-negative integer that indicates
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2193 which subexpression in @var{regexp} matches the definition's name.
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2194
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2195 An element can also look like this:
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2196
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2197 @example
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2198 (@var{menu-title} @var{regexp} @var{index} @var{function} @var{arguments}@dots{})
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2199 @end example
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2200
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2201 Each match for this element creates an index item, and when the index
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2202 item is selected by the user, it calls @var{function} with arguments
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2203 consisting of the item name, the buffer position, and @var{arguments}.
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2204
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2205 For Emacs Lisp mode, @code{imenu-generic-expression} could look like
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2206 this:
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2207
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2208 @c should probably use imenu-syntax-alist and \\sw rather than [-A-Za-z0-9+]
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2209 @example
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2210 @group
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2211 ((nil "^\\s-*(def\\(un\\|subst\\|macro\\|advice\\)\
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2212 \\s-+\\([-A-Za-z0-9+]+\\)" 2)
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2213 @end group
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2214 @group
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2215 ("*Vars*" "^\\s-*(def\\(var\\|const\\)\
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2216 \\s-+\\([-A-Za-z0-9+]+\\)" 2)
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2217 @end group
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2218 @group
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2219 ("*Types*"
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2220 "^\\s-*\
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2221 (def\\(type\\|struct\\|class\\|ine-condition\\)\
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2222 \\s-+\\([-A-Za-z0-9+]+\\)" 2))
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2223 @end group
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2224 @end example
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2225
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2226 Setting this variable makes it buffer-local in the current buffer.
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2227 @end defvar
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2228
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2229 @defvar imenu-case-fold-search
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2230 This variable controls whether matching against the regular
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2231 expressions in the value of @code{imenu-generic-expression} is
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2232 case-sensitive: @code{t}, the default, means matching should ignore
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2233 case.
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2234
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2235 Setting this variable makes it buffer-local in the current buffer.
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2236 @end defvar
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2237
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2238 @defvar imenu-syntax-alist
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2239 This variable is an alist of syntax table modifiers to use while
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2240 processing @code{imenu-generic-expression}, to override the syntax table
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2241 of the current buffer. Each element should have this form:
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2242
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2243 @example
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2244 (@var{characters} . @var{syntax-description})
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2245 @end example
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2246
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2247 The @sc{car}, @var{characters}, can be either a character or a string.
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2248 The element says to give that character or characters the syntax
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2249 specified by @var{syntax-description}, which is passed to
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2250 @code{modify-syntax-entry} (@pxref{Syntax Table Functions}).
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2251
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2252 This feature is typically used to give word syntax to characters which
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2253 normally have symbol syntax, and thus to simplify
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2254 @code{imenu-generic-expression} and speed up matching.
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2255 For example, Fortran mode uses it this way:
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2256
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2257 @example
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2258 (setq imenu-syntax-alist '(("_$" . "w")))
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2259 @end example
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2260
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2261 The @code{imenu-generic-expression} regular expressions can then use
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2262 @samp{\\sw+} instead of @samp{\\(\\sw\\|\\s_\\)+}. Note that this
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2263 technique may be inconvenient when the mode needs to limit the initial
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2264 character of a name to a smaller set of characters than are allowed in
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2265 the rest of a name.
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2266
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2267 Setting this variable makes it buffer-local in the current buffer.
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2268 @end defvar
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2269
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2270 Another way to customize Imenu for a major mode is to set the
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2271 variables @code{imenu-prev-index-position-function} and
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2272 @code{imenu-extract-index-name-function}:
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2273
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2274 @defvar imenu-prev-index-position-function
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2275 If this variable is non-@code{nil}, its value should be a function that
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2276 finds the next ``definition'' to put in the buffer index, scanning
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2277 backward in the buffer from point. It should return @code{nil} if it
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2278 doesn't find another ``definition'' before point. Otherwise it should
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2279 leave point at the place it finds a ``definition'' and return any
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2280 non-@code{nil} value.
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2281
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2282 Setting this variable makes it buffer-local in the current buffer.
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2283 @end defvar
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2284
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2285 @defvar imenu-extract-index-name-function
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2286 If this variable is non-@code{nil}, its value should be a function to
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2287 return the name for a definition, assuming point is in that definition
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2288 as the @code{imenu-prev-index-position-function} function would leave
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2289 it.
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2290
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2291 Setting this variable makes it buffer-local in the current buffer.
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2292 @end defvar
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2293
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2294 The last way to customize Imenu for a major mode is to set the
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2295 variable @code{imenu-create-index-function}:
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2296
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2297 @defvar imenu-create-index-function
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2298 This variable specifies the function to use for creating a buffer
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2299 index. The function should take no arguments, and return an index
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2300 alist for the current buffer. It is called within
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2301 @code{save-excursion}, so where it leaves point makes no difference.
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2302
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2303 The index alist can have three types of elements. Simple elements
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2304 look like this:
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2305
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2306 @example
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2307 (@var{index-name} . @var{index-position})
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2308 @end example
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2309
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2310 Selecting a simple element has the effect of moving to position
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2311 @var{index-position} in the buffer. Special elements look like this:
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2312
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2313 @example
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2314 (@var{index-name} @var{index-position} @var{function} @var{arguments}@dots{})
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2315 @end example
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2316
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2317 Selecting a special element performs:
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2318
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2319 @example
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2320 (funcall @var{function}
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2321 @var{index-name} @var{index-position} @var{arguments}@dots{})
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2322 @end example
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2323
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2324 A nested sub-alist element looks like this:
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2325
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2326 @example
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2327 (@var{menu-title} @var{sub-alist})
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2328 @end example
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2329
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2330 It creates the submenu @var{menu-title} specified by @var{sub-alist}.
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2331
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2332 The default value of @code{imenu-create-index-function} is
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2333 @code{imenu-default-create-index-function}. This function calls the
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2334 value of @code{imenu-prev-index-position-function} and the value of
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2335 @code{imenu-extract-index-name-function} to produce the index alist.
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2336 However, if either of these two variables is @code{nil}, the default
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2337 function uses @code{imenu-generic-expression} instead.
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2338
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2339 Setting this variable makes it buffer-local in the current buffer.
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2340 @end defvar
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2341
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2342 @node Font Lock Mode
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2343 @section Font Lock Mode
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2344 @cindex Font Lock mode
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2345
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2346 @dfn{Font Lock mode} is a feature that automatically attaches
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2347 @code{face} properties to certain parts of the buffer based on their
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2348 syntactic role. How it parses the buffer depends on the major mode;
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2349 most major modes define syntactic criteria for which faces to use in
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2350 which contexts. This section explains how to customize Font Lock for a
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2351 particular major mode.
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2352
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2353 Font Lock mode finds text to highlight in two ways: through
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2354 syntactic parsing based on the syntax table, and through searching
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2355 (usually for regular expressions). Syntactic fontification happens
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2356 first; it finds comments and string constants and highlights them.
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2357 Search-based fontification happens second.
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2358
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2359 @menu
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2360 * Font Lock Basics:: Overview of customizing Font Lock.
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2361 * Search-based Fontification:: Fontification based on regexps.
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2362 * Customizing Keywords:: Customizing search-based fontification.
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2363 * Other Font Lock Variables:: Additional customization facilities.
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2364 * Levels of Font Lock:: Each mode can define alternative levels
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2365 so that the user can select more or less.
111887
0eb10986b8f2 * doc/lispref/backups.texi (Making Backups):
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 109948
diff changeset
2366 * Precalculated Fontification:: How Lisp programs that produce the buffer
84089
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2367 contents can also specify how to fontify it.
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2368 * Faces for Font Lock:: Special faces specifically for Font Lock.
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2369 * Syntactic Font Lock:: Fontification based on syntax tables.
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2370 * Setting Syntax Properties:: Defining character syntax based on context
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2371 using the Font Lock mechanism.
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2372 * Multiline Font Lock:: How to coerce Font Lock into properly
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2373 highlighting multiline constructs.
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2374 @end menu
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2375
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2376 @node Font Lock Basics
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2377 @subsection Font Lock Basics
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2378
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2379 There are several variables that control how Font Lock mode highlights
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2380 text. But major modes should not set any of these variables directly.
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2381 Instead, they should set @code{font-lock-defaults} as a buffer-local
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2382 variable. The value assigned to this variable is used, if and when Font
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2383 Lock mode is enabled, to set all the other variables.
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2384
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2385 @defvar font-lock-defaults
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2386 This variable is set by major modes, as a buffer-local variable, to
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2387 specify how to fontify text in that mode. It automatically becomes
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2388 buffer-local when you set it. If its value is @code{nil}, Font-Lock
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2389 mode does no highlighting, and you can use the @samp{Faces} menu
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2390 (under @samp{Edit} and then @samp{Text Properties} in the menu bar) to
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2391 assign faces explicitly to text in the buffer.
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2392
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2393 If non-@code{nil}, the value should look like this:
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2394
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2395 @example
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2396 (@var{keywords} [@var{keywords-only} [@var{case-fold}
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2397 [@var{syntax-alist} [@var{syntax-begin} @var{other-vars}@dots{}]]]])
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2398 @end example
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2399
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2400 The first element, @var{keywords}, indirectly specifies the value of
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2401 @code{font-lock-keywords} which directs search-based fontification.
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2402 It can be a symbol, a variable or a function whose value is the list
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2403 to use for @code{font-lock-keywords}. It can also be a list of
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2404 several such symbols, one for each possible level of fontification.
100386
fae812e295b4 (Font Lock Basics): Fix level description. (Bug#1534)
Glenn Morris <rgm@gnu.org>
parents: 99965
diff changeset
2405 The first symbol specifies the @samp{mode default} level of
fae812e295b4 (Font Lock Basics): Fix level description. (Bug#1534)
Glenn Morris <rgm@gnu.org>
parents: 99965
diff changeset
2406 fontification, the next symbol level 1 fontification, the next level 2,
fae812e295b4 (Font Lock Basics): Fix level description. (Bug#1534)
Glenn Morris <rgm@gnu.org>
parents: 99965
diff changeset
2407 and so on. The @samp{mode default} level is normally the same as level
fae812e295b4 (Font Lock Basics): Fix level description. (Bug#1534)
Glenn Morris <rgm@gnu.org>
parents: 99965
diff changeset
2408 1. It is used when @code{font-lock-maximum-decoration} has a @code{nil}
fae812e295b4 (Font Lock Basics): Fix level description. (Bug#1534)
Glenn Morris <rgm@gnu.org>
parents: 99965
diff changeset
2409 value. @xref{Levels of Font Lock}.
84089
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2410
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2411 The second element, @var{keywords-only}, specifies the value of the
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2412 variable @code{font-lock-keywords-only}. If this is omitted or
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2413 @code{nil}, syntactic fontification (of strings and comments) is also
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2414 performed. If this is non-@code{nil}, such fontification is not
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2415 performed. @xref{Syntactic Font Lock}.
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2416
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2417 The third element, @var{case-fold}, specifies the value of
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2418 @code{font-lock-keywords-case-fold-search}. If it is non-@code{nil},
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2419 Font Lock mode ignores case when searching as directed by
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2420 @code{font-lock-keywords}.
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2421
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2422 If the fourth element, @var{syntax-alist}, is non-@code{nil}, it
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2423 should be a list of cons cells of the form @code{(@var{char-or-string}
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2424 . @var{string})}. These are used to set up a syntax table for
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2425 syntactic fontification (@pxref{Syntax Table Functions}). The
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2426 resulting syntax table is stored in @code{font-lock-syntax-table}.
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2427
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2428 The fifth element, @var{syntax-begin}, specifies the value of
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2429 @code{font-lock-beginning-of-syntax-function}. We recommend setting
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2430 this variable to @code{nil} and using @code{syntax-begin-function}
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2431 instead.
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2432
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2433 All the remaining elements (if any) are collectively called
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2434 @var{other-vars}. Each of these elements should have the form
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2435 @code{(@var{variable} . @var{value})}---which means, make
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2436 @var{variable} buffer-local and then set it to @var{value}. You can
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2437 use these @var{other-vars} to set other variables that affect
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2438 fontification, aside from those you can control with the first five
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2439 elements. @xref{Other Font Lock Variables}.
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2440 @end defvar
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2441
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2442 If your mode fontifies text explicitly by adding
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2443 @code{font-lock-face} properties, it can specify @code{(nil t)} for
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2444 @code{font-lock-defaults} to turn off all automatic fontification.
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2445 However, this is not required; it is possible to fontify some things
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2446 using @code{font-lock-face} properties and set up automatic
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2447 fontification for other parts of the text.
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2448
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2449 @node Search-based Fontification
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2450 @subsection Search-based Fontification
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2451
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2452 The most important variable for customizing Font Lock mode is
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2453 @code{font-lock-keywords}. It specifies the search criteria for
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2454 search-based fontification. You should specify the value of this
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2455 variable with @var{keywords} in @code{font-lock-defaults}.
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2456
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2457 @defvar font-lock-keywords
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2458 This variable's value is a list of the keywords to highlight. Be
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2459 careful when composing regular expressions for this list; a poorly
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2460 written pattern can dramatically slow things down!
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2461 @end defvar
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2462
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2463 Each element of @code{font-lock-keywords} specifies how to find
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2464 certain cases of text, and how to highlight those cases. Font Lock mode
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2465 processes the elements of @code{font-lock-keywords} one by one, and for
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2466 each element, it finds and handles all matches. Ordinarily, once
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2467 part of the text has been fontified already, this cannot be overridden
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2468 by a subsequent match in the same text; but you can specify different
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2469 behavior using the @var{override} element of a @var{subexp-highlighter}.
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2470
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2471 Each element of @code{font-lock-keywords} should have one of these
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2472 forms:
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2473
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2474 @table @code
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2475 @item @var{regexp}
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2476 Highlight all matches for @var{regexp} using
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2477 @code{font-lock-keyword-face}. For example,
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2478
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2479 @example
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2480 ;; @r{Highlight occurrences of the word @samp{foo}}
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2481 ;; @r{using @code{font-lock-keyword-face}.}
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2482 "\\<foo\\>"
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2483 @end example
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2484
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2485 The function @code{regexp-opt} (@pxref{Regexp Functions}) is useful
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2486 for calculating optimal regular expressions to match a number of
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2487 different keywords.
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2488
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2489 @item @var{function}
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2490 Find text by calling @var{function}, and highlight the matches
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2491 it finds using @code{font-lock-keyword-face}.
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2492
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2493 When @var{function} is called, it receives one argument, the limit of
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2494 the search; it should begin searching at point, and not search beyond the
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2495 limit. It should return non-@code{nil} if it succeeds, and set the
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2496 match data to describe the match that was found. Returning @code{nil}
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2497 indicates failure of the search.
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2498
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2499 Fontification will call @var{function} repeatedly with the same limit,
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2500 and with point where the previous invocation left it, until
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2501 @var{function} fails. On failure, @var{function} need not reset point
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2502 in any particular way.
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2503
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2504 @item (@var{matcher} . @var{subexp})
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2505 In this kind of element, @var{matcher} is either a regular
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2506 expression or a function, as described above. The @sc{cdr},
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2507 @var{subexp}, specifies which subexpression of @var{matcher} should be
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2508 highlighted (instead of the entire text that @var{matcher} matched).
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2509
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2510 @example
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2511 ;; @r{Highlight the @samp{bar} in each occurrence of @samp{fubar},}
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2512 ;; @r{using @code{font-lock-keyword-face}.}
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2513 ("fu\\(bar\\)" . 1)
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2514 @end example
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2515
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2516 If you use @code{regexp-opt} to produce the regular expression
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2517 @var{matcher}, you can use @code{regexp-opt-depth} (@pxref{Regexp
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2518 Functions}) to calculate the value for @var{subexp}.
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2519
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2520 @item (@var{matcher} . @var{facespec})
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2521 In this kind of element, @var{facespec} is an expression whose value
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2522 specifies the face to use for highlighting. In the simplest case,
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2523 @var{facespec} is a Lisp variable (a symbol) whose value is a face
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2524 name.
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2525
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2526 @example
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2527 ;; @r{Highlight occurrences of @samp{fubar},}
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2528 ;; @r{using the face which is the value of @code{fubar-face}.}
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2529 ("fubar" . fubar-face)
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2530 @end example
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2531
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2532 However, @var{facespec} can also evaluate to a list of this form:
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2533
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2534 @example
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2535 (face @var{face} @var{prop1} @var{val1} @var{prop2} @var{val2}@dots{})
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2536 @end example
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2537
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2538 @noindent
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2539 to specify the face @var{face} and various additional text properties
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2540 to put on the text that matches. If you do this, be sure to add the
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2541 other text property names that you set in this way to the value of
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2542 @code{font-lock-extra-managed-props} so that the properties will also
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2543 be cleared out when they are no longer appropriate. Alternatively,
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2544 you can set the variable @code{font-lock-unfontify-region-function} to
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2545 a function that clears these properties. @xref{Other Font Lock
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2546 Variables}.
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2547
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2548 @item (@var{matcher} . @var{subexp-highlighter})
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2549 In this kind of element, @var{subexp-highlighter} is a list
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2550 which specifies how to highlight matches found by @var{matcher}.
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2551 It has the form:
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2552
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2553 @example
101567
1a1c4c8eb2c8 (Search-based Fontification): Correct a typo.
Alan Mackenzie <acm@muc.de>
parents: 100974
diff changeset
2554 (@var{subexp} @var{facespec} [@var{override} [@var{laxmatch}]])
84089
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2555 @end example
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2556
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2557 The @sc{car}, @var{subexp}, is an integer specifying which subexpression
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2558 of the match to fontify (0 means the entire matching text). The second
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2559 subelement, @var{facespec}, is an expression whose value specifies the
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2560 face, as described above.
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2561
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2562 The last two values in @var{subexp-highlighter}, @var{override} and
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2563 @var{laxmatch}, are optional flags. If @var{override} is @code{t},
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2564 this element can override existing fontification made by previous
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2565 elements of @code{font-lock-keywords}. If it is @code{keep}, then
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2566 each character is fontified if it has not been fontified already by
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2567 some other element. If it is @code{prepend}, the face specified by
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2568 @var{facespec} is added to the beginning of the @code{font-lock-face}
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2569 property. If it is @code{append}, the face is added to the end of the
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2570 @code{font-lock-face} property.
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2571
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2572 If @var{laxmatch} is non-@code{nil}, it means there should be no error
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2573 if there is no subexpression numbered @var{subexp} in @var{matcher}.
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2574 Obviously, fontification of the subexpression numbered @var{subexp} will
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2575 not occur. However, fontification of other subexpressions (and other
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2576 regexps) will continue. If @var{laxmatch} is @code{nil}, and the
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2577 specified subexpression is missing, then an error is signaled which
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2578 terminates search-based fontification.
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2579
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2580 Here are some examples of elements of this kind, and what they do:
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2581
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2582 @smallexample
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2583 ;; @r{Highlight occurrences of either @samp{foo} or @samp{bar}, using}
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2584 ;; @r{@code{foo-bar-face}, even if they have already been highlighted.}
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2585 ;; @r{@code{foo-bar-face} should be a variable whose value is a face.}
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2586 ("foo\\|bar" 0 foo-bar-face t)
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2587
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2588 ;; @r{Highlight the first subexpression within each occurrence}
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2589 ;; @r{that the function @code{fubar-match} finds,}
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2590 ;; @r{using the face which is the value of @code{fubar-face}.}
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2591 (fubar-match 1 fubar-face)
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2592 @end smallexample
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2593
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2594 @item (@var{matcher} . @var{anchored-highlighter})
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2595 In this kind of element, @var{anchored-highlighter} specifies how to
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2596 highlight text that follows a match found by @var{matcher}. So a
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2597 match found by @var{matcher} acts as the anchor for further searches
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2598 specified by @var{anchored-highlighter}. @var{anchored-highlighter}
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2599 is a list of the following form:
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2600
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2601 @example
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2602 (@var{anchored-matcher} @var{pre-form} @var{post-form}
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2603 @var{subexp-highlighters}@dots{})
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2604 @end example
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2605
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2606 Here, @var{anchored-matcher}, like @var{matcher}, is either a regular
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2607 expression or a function. After a match of @var{matcher} is found,
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2608 point is at the end of the match. Now, Font Lock evaluates the form
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2609 @var{pre-form}. Then it searches for matches of
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2610 @var{anchored-matcher} and uses @var{subexp-highlighters} to highlight
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2611 these. A @var{subexp-highlighter} is as described above. Finally,
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2612 Font Lock evaluates @var{post-form}.
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2613
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2614 The forms @var{pre-form} and @var{post-form} can be used to initialize
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2615 before, and cleanup after, @var{anchored-matcher} is used. Typically,
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2616 @var{pre-form} is used to move point to some position relative to the
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2617 match of @var{matcher}, before starting with @var{anchored-matcher}.
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2618 @var{post-form} might be used to move back, before resuming with
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2619 @var{matcher}.
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2620
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2621 After Font Lock evaluates @var{pre-form}, it does not search for
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2622 @var{anchored-matcher} beyond the end of the line. However, if
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2623 @var{pre-form} returns a buffer position that is greater than the
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2624 position of point after @var{pre-form} is evaluated, then the position
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2625 returned by @var{pre-form} is used as the limit of the search instead.
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2626 It is generally a bad idea to return a position greater than the end
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2627 of the line; in other words, the @var{anchored-matcher} search should
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2628 not span lines.
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2629
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2630 For example,
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2631
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2632 @smallexample
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2633 ;; @r{Highlight occurrences of the word @samp{item} following}
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2634 ;; @r{an occurrence of the word @samp{anchor} (on the same line)}
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2635 ;; @r{in the value of @code{item-face}.}
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2636 ("\\<anchor\\>" "\\<item\\>" nil nil (0 item-face))
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2637 @end smallexample
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2638
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2639 Here, @var{pre-form} and @var{post-form} are @code{nil}. Therefore
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2640 searching for @samp{item} starts at the end of the match of
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2641 @samp{anchor}, and searching for subsequent instances of @samp{anchor}
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2642 resumes from where searching for @samp{item} concluded.
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2643
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2644 @item (@var{matcher} @var{highlighters}@dots{})
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2645 This sort of element specifies several @var{highlighter} lists for a
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2646 single @var{matcher}. A @var{highlighter} list can be of the type
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2647 @var{subexp-highlighter} or @var{anchored-highlighter} as described
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2648 above.
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2649
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2650 For example,
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2651
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2652 @smallexample
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2653 ;; @r{Highlight occurrences of the word @samp{anchor} in the value}
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2654 ;; @r{of @code{anchor-face}, and subsequent occurrences of the word}
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2655 ;; @r{@samp{item} (on the same line) in the value of @code{item-face}.}
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2656 ("\\<anchor\\>" (0 anchor-face)
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2657 ("\\<item\\>" nil nil (0 item-face)))
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2658 @end smallexample
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2659
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2660 @item (eval . @var{form})
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2661 Here @var{form} is an expression to be evaluated the first time
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2662 this value of @code{font-lock-keywords} is used in a buffer.
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2663 Its value should have one of the forms described in this table.
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2664 @end table
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2665
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2666 @strong{Warning:} Do not design an element of @code{font-lock-keywords}
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2667 to match text which spans lines; this does not work reliably.
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2668 For details, see @xref{Multiline Font Lock}.
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2669
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2670 You can use @var{case-fold} in @code{font-lock-defaults} to specify
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2671 the value of @code{font-lock-keywords-case-fold-search} which says
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2672 whether search-based fontification should be case-insensitive.
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2673
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2674 @defvar font-lock-keywords-case-fold-search
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2675 Non-@code{nil} means that regular expression matching for the sake of
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2676 @code{font-lock-keywords} should be case-insensitive.
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2677 @end defvar
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2678
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2679 @node Customizing Keywords
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2680 @subsection Customizing Search-Based Fontification
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2681
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2682 You can use @code{font-lock-add-keywords} to add additional
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2683 search-based fontification rules to a major mode, and
102151
328f4b370b74 Remove duplicate words.
Juanma Barranquero <lekktu@gmail.com>
parents: 101567
diff changeset
2684 @code{font-lock-remove-keywords} to remove rules.
84089
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2685
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2686 @defun font-lock-add-keywords mode keywords &optional how
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2687 This function adds highlighting @var{keywords}, for the current buffer
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2688 or for major mode @var{mode}. The argument @var{keywords} should be a
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2689 list with the same format as the variable @code{font-lock-keywords}.
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2690
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2691 If @var{mode} is a symbol which is a major mode command name, such as
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2692 @code{c-mode}, the effect is that enabling Font Lock mode in
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2693 @var{mode} will add @var{keywords} to @code{font-lock-keywords}.
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2694 Calling with a non-@code{nil} value of @var{mode} is correct only in
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2695 your @file{~/.emacs} file.
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2696
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2697 If @var{mode} is @code{nil}, this function adds @var{keywords} to
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2698 @code{font-lock-keywords} in the current buffer. This way of calling
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2699 @code{font-lock-add-keywords} is usually used in mode hook functions.
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2700
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2701 By default, @var{keywords} are added at the beginning of
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2702 @code{font-lock-keywords}. If the optional argument @var{how} is
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2703 @code{set}, they are used to replace the value of
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2704 @code{font-lock-keywords}. If @var{how} is any other non-@code{nil}
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2705 value, they are added at the end of @code{font-lock-keywords}.
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2706
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2707 Some modes provide specialized support you can use in additional
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2708 highlighting patterns. See the variables
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2709 @code{c-font-lock-extra-types}, @code{c++-font-lock-extra-types},
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2710 and @code{java-font-lock-extra-types}, for example.
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2711
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2712 @strong{Warning:} major mode functions must not call
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2713 @code{font-lock-add-keywords} under any circumstances, either directly
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2714 or indirectly, except through their mode hooks. (Doing so would lead
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2715 to incorrect behavior for some minor modes.) They should set up their
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2716 rules for search-based fontification by setting
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2717 @code{font-lock-keywords}.
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2718 @end defun
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2719
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2720 @defun font-lock-remove-keywords mode keywords
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2721 This function removes @var{keywords} from @code{font-lock-keywords}
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2722 for the current buffer or for major mode @var{mode}. As in
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2723 @code{font-lock-add-keywords}, @var{mode} should be a major mode
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2724 command name or @code{nil}. All the caveats and requirements for
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2725 @code{font-lock-add-keywords} apply here too.
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2726 @end defun
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2727
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2728 For example, this code
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2729
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2730 @smallexample
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2731 (font-lock-add-keywords 'c-mode
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2732 '(("\\<\\(FIXME\\):" 1 font-lock-warning-face prepend)
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2733 ("\\<\\(and\\|or\\|not\\)\\>" . font-lock-keyword-face)))
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2734 @end smallexample
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2735
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2736 @noindent
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2737 adds two fontification patterns for C mode: one to fontify the word
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2738 @samp{FIXME}, even in comments, and another to fontify the words
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2739 @samp{and}, @samp{or} and @samp{not} as keywords.
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2740
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2741 @noindent
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2742 That example affects only C mode proper. To add the same patterns to
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2743 C mode @emph{and} all modes derived from it, do this instead:
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2744
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2745 @smallexample
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2746 (add-hook 'c-mode-hook
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2747 (lambda ()
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2748 (font-lock-add-keywords nil
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2749 '(("\\<\\(FIXME\\):" 1 font-lock-warning-face prepend)
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2750 ("\\<\\(and\\|or\\|not\\)\\>" .
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2751 font-lock-keyword-face)))))
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2752 @end smallexample
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2753
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2754 @node Other Font Lock Variables
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2755 @subsection Other Font Lock Variables
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2756
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2757 This section describes additional variables that a major mode can
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2758 set by means of @var{other-vars} in @code{font-lock-defaults}
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2759 (@pxref{Font Lock Basics}).
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2760
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2761 @defvar font-lock-mark-block-function
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2762 If this variable is non-@code{nil}, it should be a function that is
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2763 called with no arguments, to choose an enclosing range of text for
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2764 refontification for the command @kbd{M-o M-o}
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2765 (@code{font-lock-fontify-block}).
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2766
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2767 The function should report its choice by placing the region around it.
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2768 A good choice is a range of text large enough to give proper results,
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2769 but not too large so that refontification becomes slow. Typical values
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2770 are @code{mark-defun} for programming modes or @code{mark-paragraph} for
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2771 textual modes.
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2772 @end defvar
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2773
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2774 @defvar font-lock-extra-managed-props
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2775 This variable specifies additional properties (other than
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2776 @code{font-lock-face}) that are being managed by Font Lock mode. It
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2777 is used by @code{font-lock-default-unfontify-region}, which normally
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2778 only manages the @code{font-lock-face} property. If you want Font
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2779 Lock to manage other properties as well, you must specify them in a
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2780 @var{facespec} in @code{font-lock-keywords} as well as add them to
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2781 this list. @xref{Search-based Fontification}.
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2782 @end defvar
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2783
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2784 @defvar font-lock-fontify-buffer-function
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2785 Function to use for fontifying the buffer. The default value is
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2786 @code{font-lock-default-fontify-buffer}.
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2787 @end defvar
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2788
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2789 @defvar font-lock-unfontify-buffer-function
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2790 Function to use for unfontifying the buffer. This is used when
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2791 turning off Font Lock mode. The default value is
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2792 @code{font-lock-default-unfontify-buffer}.
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2793 @end defvar
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2794
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2795 @defvar font-lock-fontify-region-function
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2796 Function to use for fontifying a region. It should take two
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2797 arguments, the beginning and end of the region, and an optional third
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2798 argument @var{verbose}. If @var{verbose} is non-@code{nil}, the
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2799 function should print status messages. The default value is
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2800 @code{font-lock-default-fontify-region}.
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2801 @end defvar
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2802
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2803 @defvar font-lock-unfontify-region-function
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2804 Function to use for unfontifying a region. It should take two
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2805 arguments, the beginning and end of the region. The default value is
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2806 @code{font-lock-default-unfontify-region}.
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2807 @end defvar
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2808
99694
7d1d2a142ab5 (Other Font Lock Variables): Document jit-lock-register and
Chong Yidong <cyd@stupidchicken.com>
parents: 98729
diff changeset
2809 @defun jit-lock-register function &optional contextual
7d1d2a142ab5 (Other Font Lock Variables): Document jit-lock-register and
Chong Yidong <cyd@stupidchicken.com>
parents: 98729
diff changeset
2810 This function tells Font Lock mode to run the Lisp function
7d1d2a142ab5 (Other Font Lock Variables): Document jit-lock-register and
Chong Yidong <cyd@stupidchicken.com>
parents: 98729
diff changeset
2811 @var{function} any time it has to fontify or refontify part of the
7d1d2a142ab5 (Other Font Lock Variables): Document jit-lock-register and
Chong Yidong <cyd@stupidchicken.com>
parents: 98729
diff changeset
2812 current buffer. It calls @var{function} before calling the default
7d1d2a142ab5 (Other Font Lock Variables): Document jit-lock-register and
Chong Yidong <cyd@stupidchicken.com>
parents: 98729
diff changeset
2813 fontification functions, and gives it two arguments, @var{start} and
7d1d2a142ab5 (Other Font Lock Variables): Document jit-lock-register and
Chong Yidong <cyd@stupidchicken.com>
parents: 98729
diff changeset
2814 @var{end}, which specify the region to be fontified or refontified.
7d1d2a142ab5 (Other Font Lock Variables): Document jit-lock-register and
Chong Yidong <cyd@stupidchicken.com>
parents: 98729
diff changeset
2815
7d1d2a142ab5 (Other Font Lock Variables): Document jit-lock-register and
Chong Yidong <cyd@stupidchicken.com>
parents: 98729
diff changeset
2816 The optional argument @var{contextual}, if non-@code{nil}, forces Font
7d1d2a142ab5 (Other Font Lock Variables): Document jit-lock-register and
Chong Yidong <cyd@stupidchicken.com>
parents: 98729
diff changeset
2817 Lock mode to always refontify a syntactically relevant part of the
7d1d2a142ab5 (Other Font Lock Variables): Document jit-lock-register and
Chong Yidong <cyd@stupidchicken.com>
parents: 98729
diff changeset
2818 buffer, and not just the modified lines. This argument can usually be
7d1d2a142ab5 (Other Font Lock Variables): Document jit-lock-register and
Chong Yidong <cyd@stupidchicken.com>
parents: 98729
diff changeset
2819 omitted.
7d1d2a142ab5 (Other Font Lock Variables): Document jit-lock-register and
Chong Yidong <cyd@stupidchicken.com>
parents: 98729
diff changeset
2820 @end defun
7d1d2a142ab5 (Other Font Lock Variables): Document jit-lock-register and
Chong Yidong <cyd@stupidchicken.com>
parents: 98729
diff changeset
2821
7d1d2a142ab5 (Other Font Lock Variables): Document jit-lock-register and
Chong Yidong <cyd@stupidchicken.com>
parents: 98729
diff changeset
2822 @defun jit-lock-unregister function
7d1d2a142ab5 (Other Font Lock Variables): Document jit-lock-register and
Chong Yidong <cyd@stupidchicken.com>
parents: 98729
diff changeset
2823 If @var{function} was previously registered as a fontification
7d1d2a142ab5 (Other Font Lock Variables): Document jit-lock-register and
Chong Yidong <cyd@stupidchicken.com>
parents: 98729
diff changeset
2824 function using @code{jit-lock-register}, this function unregisters it.
7d1d2a142ab5 (Other Font Lock Variables): Document jit-lock-register and
Chong Yidong <cyd@stupidchicken.com>
parents: 98729
diff changeset
2825 @end defun
84089
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2826
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2827 @node Levels of Font Lock
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2828 @subsection Levels of Font Lock
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2829
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2830 Many major modes offer three different levels of fontification. You
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2831 can define multiple levels by using a list of symbols for @var{keywords}
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2832 in @code{font-lock-defaults}. Each symbol specifies one level of
100386
fae812e295b4 (Font Lock Basics): Fix level description. (Bug#1534)
Glenn Morris <rgm@gnu.org>
parents: 99965
diff changeset
2833 fontification; it is up to the user to choose one of these levels,
fae812e295b4 (Font Lock Basics): Fix level description. (Bug#1534)
Glenn Morris <rgm@gnu.org>
parents: 99965
diff changeset
2834 normally by setting @code{font-lock-maximum-decoration} (@pxref{Font
fae812e295b4 (Font Lock Basics): Fix level description. (Bug#1534)
Glenn Morris <rgm@gnu.org>
parents: 99965
diff changeset
2835 Lock,,, emacs, the GNU Emacs Manual}). The chosen level's symbol
fae812e295b4 (Font Lock Basics): Fix level description. (Bug#1534)
Glenn Morris <rgm@gnu.org>
parents: 99965
diff changeset
2836 value is used to initialize @code{font-lock-keywords}.
84089
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2837
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2838 Here are the conventions for how to define the levels of
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2839 fontification:
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2840
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2841 @itemize @bullet
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2842 @item
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2843 Level 1: highlight function declarations, file directives (such as include or
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2844 import directives), strings and comments. The idea is speed, so only
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2845 the most important and top-level components are fontified.
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2846
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2847 @item
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2848 Level 2: in addition to level 1, highlight all language keywords,
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2849 including type names that act like keywords, as well as named constant
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2850 values. The idea is that all keywords (either syntactic or semantic)
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2851 should be fontified appropriately.
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2852
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2853 @item
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2854 Level 3: in addition to level 2, highlight the symbols being defined in
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2855 function and variable declarations, and all builtin function names,
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2856 wherever they appear.
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2857 @end itemize
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2858
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2859 @node Precalculated Fontification
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2860 @subsection Precalculated Fontification
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2861
103238
074577abd4d1 * modes.texi (Precalculated Fontification): Clarify text.
Richard M. Stallman <rms@gnu.org>
parents: 102775
diff changeset
2862 Some major modes such as @code{list-buffers} and @code{occur}
074577abd4d1 * modes.texi (Precalculated Fontification): Clarify text.
Richard M. Stallman <rms@gnu.org>
parents: 102775
diff changeset
2863 construct the buffer text programmatically. The easiest way for them
074577abd4d1 * modes.texi (Precalculated Fontification): Clarify text.
Richard M. Stallman <rms@gnu.org>
parents: 102775
diff changeset
2864 to support Font Lock mode is to specify the faces of text when they
074577abd4d1 * modes.texi (Precalculated Fontification): Clarify text.
Richard M. Stallman <rms@gnu.org>
parents: 102775
diff changeset
2865 insert the text in the buffer.
074577abd4d1 * modes.texi (Precalculated Fontification): Clarify text.
Richard M. Stallman <rms@gnu.org>
parents: 102775
diff changeset
2866
074577abd4d1 * modes.texi (Precalculated Fontification): Clarify text.
Richard M. Stallman <rms@gnu.org>
parents: 102775
diff changeset
2867 The way to do this is to specify the faces in the text with the
074577abd4d1 * modes.texi (Precalculated Fontification): Clarify text.
Richard M. Stallman <rms@gnu.org>
parents: 102775
diff changeset
2868 special text property @code{font-lock-face} (@pxref{Special
074577abd4d1 * modes.texi (Precalculated Fontification): Clarify text.
Richard M. Stallman <rms@gnu.org>
parents: 102775
diff changeset
2869 Properties}). When Font Lock mode is enabled, this property controls
074577abd4d1 * modes.texi (Precalculated Fontification): Clarify text.
Richard M. Stallman <rms@gnu.org>
parents: 102775
diff changeset
2870 the display, just like the @code{face} property. When Font Lock mode
074577abd4d1 * modes.texi (Precalculated Fontification): Clarify text.
Richard M. Stallman <rms@gnu.org>
parents: 102775
diff changeset
2871 is disabled, @code{font-lock-face} has no effect on the display.
074577abd4d1 * modes.texi (Precalculated Fontification): Clarify text.
Richard M. Stallman <rms@gnu.org>
parents: 102775
diff changeset
2872
074577abd4d1 * modes.texi (Precalculated Fontification): Clarify text.
Richard M. Stallman <rms@gnu.org>
parents: 102775
diff changeset
2873 It is ok for a mode to use @code{font-lock-face} for some text and
074577abd4d1 * modes.texi (Precalculated Fontification): Clarify text.
Richard M. Stallman <rms@gnu.org>
parents: 102775
diff changeset
2874 also use the normal Font Lock machinery. But if the mode does not use
074577abd4d1 * modes.texi (Precalculated Fontification): Clarify text.
Richard M. Stallman <rms@gnu.org>
parents: 102775
diff changeset
2875 the normal Font Lock machinery, it should not set the variable
074577abd4d1 * modes.texi (Precalculated Fontification): Clarify text.
Richard M. Stallman <rms@gnu.org>
parents: 102775
diff changeset
2876 @code{font-lock-defaults}.
84089
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2877
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2878 @node Faces for Font Lock
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2879 @subsection Faces for Font Lock
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2880 @cindex faces for font lock
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2881 @cindex font lock faces
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2882
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2883 You can make Font Lock mode use any face, but several faces are
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2884 defined specifically for Font Lock mode. Each of these symbols is both
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2885 a face name, and a variable whose default value is the symbol itself.
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2886 Thus, the default value of @code{font-lock-comment-face} is
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2887 @code{font-lock-comment-face}. This means you can write
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2888 @code{font-lock-comment-face} in a context such as
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2889 @code{font-lock-keywords} where a face-name-valued expression is used.
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2890
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2891 @table @code
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2892 @item font-lock-comment-face
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2893 @vindex font-lock-comment-face
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2894 Used (typically) for comments.
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2895
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2896 @item font-lock-comment-delimiter-face
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2897 @vindex font-lock-comment-delimiter-face
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2898 Used (typically) for comments delimiters.
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2899
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2900 @item font-lock-doc-face
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2901 @vindex font-lock-doc-face
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2902 Used (typically) for documentation strings in the code.
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2903
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2904 @item font-lock-string-face
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2905 @vindex font-lock-string-face
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2906 Used (typically) for string constants.
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2907
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2908 @item font-lock-keyword-face
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2909 @vindex font-lock-keyword-face
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2910 Used (typically) for keywords---names that have special syntactic
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2911 significance, like @code{for} and @code{if} in C.
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2912
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2913 @item font-lock-builtin-face
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2914 @vindex font-lock-builtin-face
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2915 Used (typically) for built-in function names.
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2916
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2917 @item font-lock-function-name-face
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2918 @vindex font-lock-function-name-face
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2919 Used (typically) for the name of a function being defined or declared,
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2920 in a function definition or declaration.
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2921
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2922 @item font-lock-variable-name-face
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2923 @vindex font-lock-variable-name-face
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2924 Used (typically) for the name of a variable being defined or declared,
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2925 in a variable definition or declaration.
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2926
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2927 @item font-lock-type-face
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2928 @vindex font-lock-type-face
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2929 Used (typically) for names of user-defined data types,
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2930 where they are defined and where they are used.
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2931
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2932 @item font-lock-constant-face
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2933 @vindex font-lock-constant-face
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2934 Used (typically) for constant names.
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2935
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2936 @item font-lock-preprocessor-face
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2937 @vindex font-lock-preprocessor-face
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2938 Used (typically) for preprocessor commands.
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2939
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2940 @item font-lock-negation-char-face
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2941 @vindex font-lock-negation-char-face
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2942 Used (typically) for easily-overlooked negation characters.
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2943
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2944 @item font-lock-warning-face
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2945 @vindex font-lock-warning-face
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2946 Used (typically) for constructs that are peculiar, or that greatly
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2947 change the meaning of other text. For example, this is used for
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2948 @samp{;;;###autoload} cookies in Emacs Lisp, and for @code{#error}
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2949 directives in C.
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2950 @end table
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2951
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2952 @node Syntactic Font Lock
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2953 @subsection Syntactic Font Lock
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2954 @cindex syntactic font lock
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2955
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2956 Syntactic fontification uses the syntax table to find comments and
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2957 string constants (@pxref{Syntax Tables}). It highlights them using
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2958 @code{font-lock-comment-face} and @code{font-lock-string-face}
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2959 (@pxref{Faces for Font Lock}), or whatever
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2960 @code{font-lock-syntactic-face-function} chooses. There are several
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2961 variables that affect syntactic fontification; you should set them by
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2962 means of @code{font-lock-defaults} (@pxref{Font Lock Basics}).
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2963
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2964 @defvar font-lock-keywords-only
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2965 Non-@code{nil} means Font Lock should not do syntactic fontification;
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2966 it should only fontify based on @code{font-lock-keywords}. The normal
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2967 way for a mode to set this variable to @code{t} is with
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2968 @var{keywords-only} in @code{font-lock-defaults}.
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2969 @end defvar
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2970
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2971 @defvar font-lock-syntax-table
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2972 This variable holds the syntax table to use for fontification of
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2973 comments and strings. Specify it using @var{syntax-alist} in
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2974 @code{font-lock-defaults}. If this is @code{nil}, fontification uses
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2975 the buffer's syntax table.
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2976 @end defvar
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2977
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2978 @defvar font-lock-beginning-of-syntax-function
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2979 If this variable is non-@code{nil}, it should be a function to move
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2980 point back to a position that is syntactically at ``top level'' and
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2981 outside of strings or comments. Font Lock uses this when necessary
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2982 to get the right results for syntactic fontification.
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2983
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2984 This function is called with no arguments. It should leave point at
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2985 the beginning of any enclosing syntactic block. Typical values are
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2986 @code{beginning-of-line} (used when the start of the line is known to
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2987 be outside a syntactic block), or @code{beginning-of-defun} for
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2988 programming modes, or @code{backward-paragraph} for textual modes.
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2989
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2990 If the value is @code{nil}, Font Lock uses
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2991 @code{syntax-begin-function} to move back outside of any comment,
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2992 string, or sexp. This variable is semi-obsolete; we recommend setting
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2993 @code{syntax-begin-function} instead.
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2994
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2995 Specify this variable using @var{syntax-begin} in
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2996 @code{font-lock-defaults}.
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2997 @end defvar
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2998
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2999 @defvar font-lock-syntactic-face-function
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3000 A function to determine which face to use for a given syntactic
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3001 element (a string or a comment). The function is called with one
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3002 argument, the parse state at point returned by
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3003 @code{parse-partial-sexp}, and should return a face. The default
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3004 value returns @code{font-lock-comment-face} for comments and
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3005 @code{font-lock-string-face} for strings.
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3006
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3007 This can be used to highlighting different kinds of strings or
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3008 comments differently. It is also sometimes abused together with
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3009 @code{font-lock-syntactic-keywords} to highlight constructs that span
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3010 multiple lines, but this is too esoteric to document here.
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3011
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3012 Specify this variable using @var{other-vars} in
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3013 @code{font-lock-defaults}.
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3014 @end defvar
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3015
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3016 @node Setting Syntax Properties
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3017 @subsection Setting Syntax Properties
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3018
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3019 Font Lock mode can be used to update @code{syntax-table} properties
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3020 automatically (@pxref{Syntax Properties}). This is useful in
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3021 languages for which a single syntax table by itself is not sufficient.
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3022
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3023 @defvar font-lock-syntactic-keywords
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3024 This variable enables and controls updating @code{syntax-table}
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3025 properties by Font Lock. Its value should be a list of elements of
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3026 this form:
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3027
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3028 @example
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3029 (@var{matcher} @var{subexp} @var{syntax} @var{override} @var{laxmatch})
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3030 @end example
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3031
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3032 The parts of this element have the same meanings as in the corresponding
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3033 sort of element of @code{font-lock-keywords},
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3034
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3035 @example
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3036 (@var{matcher} @var{subexp} @var{facespec} @var{override} @var{laxmatch})
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3037 @end example
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3038
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3039 However, instead of specifying the value @var{facespec} to use for the
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3040 @code{face} property, it specifies the value @var{syntax} to use for
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3041 the @code{syntax-table} property. Here, @var{syntax} can be a string
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3042 (as taken by @code{modify-syntax-entry}), a syntax table, a cons cell
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3043 (as returned by @code{string-to-syntax}), or an expression whose value
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3044 is one of those two types. @var{override} cannot be @code{prepend} or
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3045 @code{append}.
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3046
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3047 For example, an element of the form:
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3048
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3049 @example
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3050 ("\\$\\(#\\)" 1 ".")
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3051 @end example
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3052
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3053 highlights syntactically a hash character when following a dollar
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3054 character, with a SYNTAX of @code{"."} (meaning punctuation syntax).
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3055 Assuming that the buffer syntax table specifies hash characters to
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3056 have comment start syntax, the element will only highlight hash
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3057 characters that do not follow dollar characters as comments
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3058 syntactically.
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3059
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3060 An element of the form:
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3061
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3062 @example
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3063 ("\\('\\).\\('\\)"
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3064 (1 "\"")
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3065 (2 "\""))
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3066 @end example
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3067
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3068 highlights syntactically both single quotes which surround a single
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3069 character, with a SYNTAX of @code{"\""} (meaning string quote syntax).
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3070 Assuming that the buffer syntax table does not specify single quotes
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3071 to have quote syntax, the element will only highlight single quotes of
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3072 the form @samp{'@var{c}'} as strings syntactically. Other forms, such
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3073 as @samp{foo'bar} or @samp{'fubar'}, will not be highlighted as
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3074 strings.
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3075
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3076 Major modes normally set this variable with @var{other-vars} in
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3077 @code{font-lock-defaults}.
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3078 @end defvar
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3079
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3080 @node Multiline Font Lock
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3081 @subsection Multiline Font Lock Constructs
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3082 @cindex multiline font lock
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3083
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3084 Normally, elements of @code{font-lock-keywords} should not match
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3085 across multiple lines; that doesn't work reliably, because Font Lock
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3086 usually scans just part of the buffer, and it can miss a multi-line
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3087 construct that crosses the line boundary where the scan starts. (The
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3088 scan normally starts at the beginning of a line.)
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3089
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3090 Making elements that match multiline constructs work properly has
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3091 two aspects: correct @emph{identification} and correct
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3092 @emph{rehighlighting}. The first means that Font Lock finds all
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3093 multiline constructs. The second means that Font Lock will correctly
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3094 rehighlight all the relevant text when a multiline construct is
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3095 changed---for example, if some of the text that was previously part of
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3096 a multiline construct ceases to be part of it. The two aspects are
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3097 closely related, and often getting one of them to work will appear to
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3098 make the other also work. However, for reliable results you must
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3099 attend explicitly to both aspects.
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3100
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3101 There are three ways to ensure correct identification of multiline
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3102 constructs:
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3103
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3104 @itemize
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3105 @item
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3106 Add a function to @code{font-lock-extend-region-functions} that does
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3107 the @emph{identification} and extends the scan so that the scanned
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3108 text never starts or ends in the middle of a multiline construct.
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3109 @item
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3110 Use the @code{font-lock-fontify-region-function} hook similarly to
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3111 extend the scan so that the scanned text never starts or ends in the
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3112 middle of a multiline construct.
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3113 @item
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3114 Somehow identify the multiline construct right when it gets inserted
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3115 into the buffer (or at any point after that but before font-lock
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3116 tries to highlight it), and mark it with a @code{font-lock-multiline}
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3117 which will instruct font-lock not to start or end the scan in the
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3118 middle of the construct.
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3119 @end itemize
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3120
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3121 There are three ways to do rehighlighting of multiline constructs:
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3122
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3123 @itemize
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3124 @item
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3125 Place a @code{font-lock-multiline} property on the construct. This
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3126 will rehighlight the whole construct if any part of it is changed. In
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3127 some cases you can do this automatically by setting the
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3128 @code{font-lock-multiline} variable, which see.
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3129 @item
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3130 Make sure @code{jit-lock-contextually} is set and rely on it doing its
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3131 job. This will only rehighlight the part of the construct that
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3132 follows the actual change, and will do it after a short delay.
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3133 This only works if the highlighting of the various parts of your
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3134 multiline construct never depends on text in subsequent lines.
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3135 Since @code{jit-lock-contextually} is activated by default, this can
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3136 be an attractive solution.
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3137 @item
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3138 Place a @code{jit-lock-defer-multiline} property on the construct.
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3139 This works only if @code{jit-lock-contextually} is used, and with the
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3140 same delay before rehighlighting, but like @code{font-lock-multiline},
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3141 it also handles the case where highlighting depends on
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3142 subsequent lines.
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3143 @end itemize
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3144
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3145 @menu
103821
6595a0b7f418 (Multiline Font Lock): End menu description with period.
Glenn Morris <rgm@gnu.org>
parents: 103273
diff changeset
3146 * Font Lock Multiline:: Marking multiline chunks with a text property.
84089
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3147 * Region to Fontify:: Controlling which region gets refontified
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3148 after a buffer change.
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3149 @end menu
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3150
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3151 @node Font Lock Multiline
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3152 @subsubsection Font Lock Multiline
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3153
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3154 One way to ensure reliable rehighlighting of multiline Font Lock
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3155 constructs is to put on them the text property @code{font-lock-multiline}.
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3156 It should be present and non-@code{nil} for text that is part of a
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3157 multiline construct.
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3158
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3159 When Font Lock is about to highlight a range of text, it first
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3160 extends the boundaries of the range as necessary so that they do not
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3161 fall within text marked with the @code{font-lock-multiline} property.
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3162 Then it removes any @code{font-lock-multiline} properties from the
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3163 range, and highlights it. The highlighting specification (mostly
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3164 @code{font-lock-keywords}) must reinstall this property each time,
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3165 whenever it is appropriate.
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3166
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3167 @strong{Warning:} don't use the @code{font-lock-multiline} property
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3168 on large ranges of text, because that will make rehighlighting slow.
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3169
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3170 @defvar font-lock-multiline
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3171 If the @code{font-lock-multiline} variable is set to @code{t}, Font
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3172 Lock will try to add the @code{font-lock-multiline} property
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3173 automatically on multiline constructs. This is not a universal
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3174 solution, however, since it slows down Font Lock somewhat. It can
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3175 miss some multiline constructs, or make the property larger or smaller
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3176 than necessary.
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3177
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3178 For elements whose @var{matcher} is a function, the function should
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3179 ensure that submatch 0 covers the whole relevant multiline construct,
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3180 even if only a small subpart will be highlighted. It is often just as
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3181 easy to add the @code{font-lock-multiline} property by hand.
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3182 @end defvar
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3183
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3184 The @code{font-lock-multiline} property is meant to ensure proper
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3185 refontification; it does not automatically identify new multiline
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3186 constructs. Identifying the requires that Font-Lock operate on large
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3187 enough chunks at a time. This will happen by accident on many cases,
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3188 which may give the impression that multiline constructs magically work.
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3189 If you set the @code{font-lock-multiline} variable non-@code{nil},
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3190 this impression will be even stronger, since the highlighting of those
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3191 constructs which are found will be properly updated from then on.
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3192 But that does not work reliably.
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3193
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3194 To find multiline constructs reliably, you must either manually
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3195 place the @code{font-lock-multiline} property on the text before
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3196 Font-Lock looks at it, or use
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3197 @code{font-lock-fontify-region-function}.
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3198
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3199 @node Region to Fontify
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3200 @subsubsection Region to Fontify after a Buffer Change
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3201
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3202 When a buffer is changed, the region that Font Lock refontifies is
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3203 by default the smallest sequence of whole lines that spans the change.
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3204 While this works well most of the time, sometimes it doesn't---for
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3205 example, when a change alters the syntactic meaning of text on an
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3206 earlier line.
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3207
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3208 You can enlarge (or even reduce) the region to fontify by setting
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3209 one the following variables:
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3210
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3211 @defvar font-lock-extend-after-change-region-function
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3212 This buffer-local variable is either @code{nil} or a function for
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3213 Font-Lock to call to determine the region to scan and fontify.
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3214
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3215 The function is given three parameters, the standard @var{beg},
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3216 @var{end}, and @var{old-len} from after-change-functions
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3217 (@pxref{Change Hooks}). It should return either a cons of the
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3218 beginning and end buffer positions (in that order) of the region to
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3219 fontify, or @code{nil} (which means choose the region in the standard
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3220 way). This function needs to preserve point, the match-data, and the
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3221 current restriction. The region it returns may start or end in the
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3222 middle of a line.
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3223
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3224 Since this function is called after every buffer change, it should be
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3225 reasonably fast.
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3226 @end defvar
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3227
111918
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3228 @node Auto-Indentation
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3229 @section Auto-indention of code
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3230
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3231 For programming languages, an important feature of a major mode is to
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3232 provide automatic indentation. This is controlled in Emacs by
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3233 @code{indent-line-function} (@pxref{Mode-Specific Indent}).
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3234 Writing a good indentation function can be difficult and to a large
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3235 extent it is still a black art.
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3236
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3237 Many major mode authors will start by writing a simple indentation
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3238 function that works for simple cases, for example by comparing with the
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3239 indentation of the previous text line. For most programming languages
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3240 that are not really line-based, this tends to scale very poorly:
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3241 improving such a function to let it handle more diverse situations tends
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3242 to become more and more difficult, resulting in the end with a large,
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3243 complex, unmaintainable indentation function which nobody dares to touch.
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3244
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3245 A good indentation function will usually need to actually parse the
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3246 text, according to the syntax of the language. Luckily, it is not
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3247 necessary to parse the text in as much detail as would be needed
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3248 for a compiler, but on the other hand, the parser embedded in the
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3249 indentation code will want to be somewhat friendly to syntactically
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3250 incorrect code.
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3251
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3252 Good maintainable indentation functions usually fall into 2 categories:
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3253 either parsing forward from some ``safe'' starting point until the
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3254 position of interest, or parsing backward from the position of interest.
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3255 Neither of the two is a clearly better choice than the other: parsing
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3256 backward is often more difficult than parsing forward because
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3257 programming languages are designed to be parsed forward, but for the
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3258 purpose of indentation it has the advantage of not needing to
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3259 guess a ``safe'' starting point, and it generally enjoys the property
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3260 that only a minimum of text will be analyzed to decide the indentation
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3261 of a line, so indentation will tend to be unaffected by syntax errors in
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3262 some earlier unrelated piece of code. Parsing forward on the other hand
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3263 is usually easier and has the advantage of making it possible to
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3264 reindent efficiently a whole region at a time, with a single parse.
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3265
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3266 Rather than write your own indentation function from scratch, it is
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3267 often preferable to try and reuse some existing ones or to rely
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3268 on a generic indentation engine. There are sadly few such
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3269 engines. The CC-mode indentation code (used with C, C++, Java, Awk
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3270 and a few other such modes) has been made more generic over the years,
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3271 so if your language seems somewhat similar to one of those languages,
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3272 you might try to use that engine. @c FIXME: documentation?
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3273 Another one is SMIE which takes an approach in the spirit
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3274 of Lisp sexps and adapts it to non-Lisp languages.
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3275
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3276 @menu
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3277 * SMIE:: A simple minded indentation engine
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3278 @end menu
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3279
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3280 @node SMIE
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3281 @subsection Simple Minded Indentation Engine
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3282
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3283 SMIE is a package that provides a generic navigation and indentation
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3284 engine. Based on a very simple parser using an ``operator precedence
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3285 grammar'', it lets major modes extend the sexp-based navigation of Lisp
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3286 to non-Lisp languages as well as provide a simple to use but reliable
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3287 auto-indentation.
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3288
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3289 Operator precedence grammar is a very primitive technology for parsing
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3290 compared to some of the more common techniques used in compilers.
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3291 It has the following characteristics: its parsing power is very limited,
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3292 and it is largely unable to detect syntax errors, but it has the
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3293 advantage of being algorithmically efficient and able to parse forward
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3294 just as well as backward. In practice that means that SMIE can use it
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3295 for indentation based on backward parsing, that it can provide both
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3296 @code{forward-sexp} and @code{backward-sexp} functionality, and that it
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3297 will naturally work on syntactically incorrect code without any extra
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3298 effort. The downside is that it also means that most programming
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3299 languages cannot be parsed correctly using SMIE, at least not without
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3300 resorting to some special tricks (@pxref{SMIE Tricks}).
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3301
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3302 @menu
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3303 * SMIE setup:: SMIE setup and features
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3304 * Operator Precedence Grammars:: A very simple parsing technique
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3305 * SMIE Grammar:: Defining the grammar of a language
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3306 * SMIE Lexer:: Defining tokens
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3307 * SMIE Tricks:: Working around the parser's limitations
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3308 * SMIE Indentation:: Specifying indentation rules
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3309 * SMIE Indentation Helpers:: Helper functions for indentation rules
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3310 * SMIE Indentation Example:: Sample indentation rules
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3311 @end menu
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3312
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3313 @node SMIE setup
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3314 @subsubsection SMIE Setup and Features
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3315
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3316 SMIE is meant to be a one-stop shop for structural navigation and
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3317 various other features which rely on the syntactic structure of code, in
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3318 particular automatic indentation. The main entry point is
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3319 @code{smie-setup} which is a function typically called while setting
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3320 up a major mode.
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3321
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3322 @defun smie-setup grammar rules-function &rest keywords
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3323 Setup SMIE navigation and indentation.
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3324 @var{grammar} is a grammar table generated by @code{smie-prec2->grammar}.
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3325 @var{rules-function} is a set of indentation rules for use on
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3326 @code{smie-rules-function}.
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3327 @var{keywords} are additional arguments, which can include the following
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3328 keywords:
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3329 @itemize
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3330 @item
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3331 @code{:forward-token} @var{fun}: Specify the forward lexer to use.
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3332 @item
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3333 @code{:backward-token} @var{fun}: Specify the backward lexer to use.
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3334 @end itemize
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3335 @end defun
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3336
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3337 Calling this function is sufficient to make commands such as
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3338 @code{forward-sexp}, @code{backward-sexp}, and @code{transpose-sexps} be
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3339 able to properly handle structural elements other than just the paired
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3340 parentheses already handled by syntax tables. For example, if the
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3341 provided grammar is precise enough, @code{transpose-sexps} can correctly
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3342 transpose the two arguments of a @code{+} operator, taking into account
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3343 the precedence rules of the language.
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3344
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3345 Calling `smie-setup' is also sufficient to make TAB indentation work in
111945
c00190a8c8ef Merge from emacs-23
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111918
diff changeset
3346 the expected way, extends @code{blink-matching-paren} to apply to
c00190a8c8ef Merge from emacs-23
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111918
diff changeset
3347 elements like @code{begin...end}, and provides some commands that you
c00190a8c8ef Merge from emacs-23
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111918
diff changeset
3348 can bind in the major mode keymap.
111918
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3349
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3350 @deffn Command smie-close-block
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3351 This command closes the most recently opened (and not yet closed) block.
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3352 @end deffn
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3353
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3354 @deffn Command smie-down-list &optional arg
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3355 This command is like @code{down-list} but it also pays attention to
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3356 nesting of tokens other than parentheses, such as @code{begin...end}.
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3357 @end deffn
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3358
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3359 @node Operator Precedence Grammars
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3360 @subsubsection Operator Precedence Grammars
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3361
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3362 SMIE's precedence grammars simply give to each token a pair of
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3363 precedences: the left-precedence and the right-precedence. We say
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3364 @code{T1 < T2} if the right-precedence of token @code{T1} is less than
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3365 the left-precedence of token @code{T2}. A good way to read this
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3366 @code{<} is as a kind of parenthesis: if we find @code{... T1 something
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3367 T2 ...} then that should be parsed as @code{... T1 (something T2 ...}
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3368 rather than as @code{... T1 something) T2 ...}. The latter
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3369 interpretation would be the case if we had @code{T1 > T2}. If we have
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3370 @code{T1 = T2}, it means that token T2 follows token T1 in the same
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3371 syntactic construction, so typically we have @code{"begin" = "end"}.
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3372 Such pairs of precedences are sufficient to express left-associativity
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3373 or right-associativity of infix operators, nesting of tokens like
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3374 parentheses and many other cases.
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3375
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3376 @c ¡Let's leave this undocumented to leave it more open for change!
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3377 @c @defvar smie-grammar
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3378 @c The value of this variable is an alist specifying the left and right
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3379 @c precedence of each token. It is meant to be initialized by using one of
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3380 @c the functions below.
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3381 @c @end defvar
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3382
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3383 @defun smie-prec2->grammar table
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3384 This function takes a @emph{prec2} grammar @var{table} and returns an
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3385 alist suitable for use in @code{smie-setup}. The @emph{prec2}
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3386 @var{table} is itself meant to be built by one of the functions below.
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3387 @end defun
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3388
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3389 @defun smie-merge-prec2s &rest tables
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3390 This function takes several @emph{prec2} @var{tables} and merges them
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3391 into a new @emph{prec2} table.
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3392 @end defun
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3393
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3394 @defun smie-precs->prec2 precs
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3395 This function builds a @emph{prec2} table from a table of precedences
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3396 @var{precs}. @var{precs} should be a list, sorted by precedence (for
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3397 example @code{"+"} will come before @code{"*"}), of elements of the form
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3398 @code{(@var{assoc} @var{op} ...)}, where each @var{op} is a token that
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3399 acts as an operator; @var{assoc} is their associativity, which can be
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3400 either @code{left}, @code{right}, @code{assoc}, or @code{nonassoc}.
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3401 All operators in a given element share the same precedence level
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3402 and associativity.
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3403 @end defun
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3404
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3405 @defun smie-bnf->prec2 bnf &rest resolvers
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3406 This function lets you specify the grammar using a BNF notation.
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3407 It accepts a @var{bnf} description of the grammar along with a set of
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3408 conflict resolution rules @var{resolvers}, and
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3409 returns a @emph{prec2} table.
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3410
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3411 @var{bnf} is a list of nonterminal definitions of the form
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3412 @code{(@var{nonterm} @var{rhs1} @var{rhs2} ...)} where each @var{rhs}
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3413 is a (non-empty) list of terminals (aka tokens) or non-terminals.
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3414
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3415 Not all grammars are accepted:
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3416 @itemize
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3417 @item
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3418 An @var{rhs} cannot be an empty list (an empty list is never needed,
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3419 since SMIE allows all non-terminals to match the empty string anyway).
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3420 @item
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3421 An @var{rhs} cannot have 2 consecutive non-terminals: each pair of
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3422 non-terminals needs to be separated by a terminal (aka token).
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3423 This is a fundamental limitation of operator precedence grammars.
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3424 @end itemize
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3425
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3426 Additionally, conflicts can occur:
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3427 @itemize
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3428 @item
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3429 The returned @emph{prec2} table holds constraints between pairs of tokens, and
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3430 for any given pair only one constraint can be present: T1 < T2,
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3431 T1 = T2, or T1 > T2.
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3432 @item
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3433 A token can be an @code{opener} (something similar to an open-paren),
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3434 a @code{closer} (like a close-paren), or @code{neither} of the two
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3435 (e.g. an infix operator, or an inner token like @code{"else"}).
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3436 @end itemize
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3437
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3438 Precedence conflicts can be resolved via @var{resolvers}, which
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3439 is a list of @emph{precs} tables (see @code{smie-precs->prec2}): for
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3440 each precedence conflict, if those @code{precs} tables
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3441 specify a particular constraint, then the conflict is resolved by using
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3442 this constraint instead, else a conflict is reported and one of the
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3443 conflicting constraints is picked arbitrarily and the others are
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3444 simply ignored.
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3445 @end defun
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3446
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3447 @node SMIE Grammar
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3448 @subsubsection Defining the Grammar of a Language
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3449
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3450 The usual way to define the SMIE grammar of a language is by
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3451 defining a new global variable that holds the precedence table by
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3452 giving a set of BNF rules.
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3453 For example, the grammar definition for a small Pascal-like language
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3454 could look like:
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3455 @example
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3456 @group
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3457 (require 'smie)
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3458 (defvar sample-smie-grammar
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3459 (smie-prec2->grammar
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3460 (smie-bnf->prec2
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3461 @end group
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3462 @group
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3463 '((id)
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3464 (inst ("begin" insts "end")
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3465 ("if" exp "then" inst "else" inst)
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3466 (id ":=" exp)
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3467 (exp))
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3468 (insts (insts ";" insts) (inst))
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3469 (exp (exp "+" exp)
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3470 (exp "*" exp)
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3471 ("(" exps ")"))
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3472 (exps (exps "," exps) (exp)))
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3473 @end group
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3474 @group
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3475 '((assoc ";"))
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3476 '((assoc ","))
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3477 '((assoc "+") (assoc "*")))))
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3478 @end group
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3479 @end example
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3480
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3481 @noindent
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3482 A few things to note:
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3483
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3484 @itemize
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3485 @item
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3486 The above grammar does not explicitly mention the syntax of function
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3487 calls: SMIE will automatically allow any sequence of sexps, such as
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3488 identifiers, balanced parentheses, or @code{begin ... end} blocks
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3489 to appear anywhere anyway.
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3490 @item
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3491 The grammar category @code{id} has no right hand side: this does not
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3492 mean that it can match only the empty string, since as mentioned any
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3493 sequence of sexps can appear anywhere anyway.
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3494 @item
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3495 Because non terminals cannot appear consecutively in the BNF grammar, it
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3496 is difficult to correctly handle tokens that act as terminators, so the
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3497 above grammar treats @code{";"} as a statement @emph{separator} instead,
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3498 which SMIE can handle very well.
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3499 @item
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3500 Separators used in sequences (such as @code{","} and @code{";"} above)
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3501 are best defined with BNF rules such as @code{(foo (foo "separator" foo) ...)}
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3502 which generate precedence conflicts which are then resolved by giving
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3503 them an explicit @code{(assoc "separator")}.
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3504 @item
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3505 The @code{("(" exps ")")} rule was not needed to pair up parens, since
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3506 SMIE will pair up any characters that are marked as having paren syntax
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3507 in the syntax table. What this rule does instead (together with the
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3508 definition of @code{exps}) is to make it clear that @code{","} should
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3509 not appear outside of parentheses.
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3510 @item
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3511 Rather than have a single @emph{precs} table to resolve conflicts, it is
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3512 preferable to have several tables, so as to let the BNF part of the
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3513 grammar specify relative precedences where possible.
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3514 @item
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3515 Unless there is a very good reason to prefer @code{left} or
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3516 @code{right}, it is usually preferable to mark operators as associative,
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3517 using @code{assoc}. For that reason @code{"+"} and @code{"*"} are
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3518 defined above as @code{assoc}, although the language defines them
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3519 formally as left associative.
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3520 @end itemize
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3521
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3522 @node SMIE Lexer
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3523 @subsubsection Defining Tokens
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3524
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3525 SMIE comes with a predefined lexical analyzer which uses syntax tables
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3526 in the following way: any sequence of characters that have word or
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3527 symbol syntax is considered a token, and so is any sequence of
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3528 characters that have punctuation syntax. This default lexer is
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3529 often a good starting point but is rarely actually correct for any given
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3530 language. For example, it will consider @code{"2,+3"} to be composed
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3531 of 3 tokens: @code{"2"}, @code{",+"}, and @code{"3"}.
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3532
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3533 To describe the lexing rules of your language to SMIE, you need
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3534 2 functions, one to fetch the next token, and another to fetch the
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3535 previous token. Those functions will usually first skip whitespace and
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3536 comments and then look at the next chunk of text to see if it
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3537 is a special token. If so it should skip the token and
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3538 return a description of this token. Usually this is simply the string
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3539 extracted from the buffer, but it can be anything you want.
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3540 For example:
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3541 @example
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3542 @group
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3543 (defvar sample-keywords-regexp
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3544 (regexp-opt '("+" "*" "," ";" ">" ">=" "<" "<=" ":=" "=")))
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3545 @end group
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3546 @group
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3547 (defun sample-smie-forward-token ()
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3548 (forward-comment (point-max))
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3549 (cond
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3550 ((looking-at sample-keywords-regexp)
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3551 (goto-char (match-end 0))
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3552 (match-string-no-properties 0))
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3553 (t (buffer-substring-no-properties
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3554 (point)
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3555 (progn (skip-syntax-forward "w_")
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3556 (point))))))
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3557 @end group
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3558 @group
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3559 (defun sample-smie-backward-token ()
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3560 (forward-comment (- (point)))
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3561 (cond
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3562 ((looking-back sample-keywords-regexp (- (point) 2) t)
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3563 (goto-char (match-beginning 0))
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3564 (match-string-no-properties 0))
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3565 (t (buffer-substring-no-properties
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3566 (point)
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3567 (progn (skip-syntax-backward "w_")
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3568 (point))))))
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3569 @end group
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3570 @end example
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3571
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3572 Notice how those lexers return the empty string when in front of
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3573 parentheses. This is because SMIE automatically takes care of the
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3574 parentheses defined in the syntax table. More specifically if the lexer
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3575 returns nil or an empty string, SMIE tries to handle the corresponding
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3576 text as a sexp according to syntax tables.
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3577
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3578 @node SMIE Tricks
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3579 @subsubsection Living With a Weak Parser
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3580
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3581 The parsing technique used by SMIE does not allow tokens to behave
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3582 differently in different contexts. For most programming languages, this
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3583 manifests itself by precedence conflicts when converting the
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3584 BNF grammar.
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3585
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3586 Sometimes, those conflicts can be worked around by expressing the
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3587 grammar slightly differently. For example, for Modula-2 it might seem
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3588 natural to have a BNF grammar that looks like this:
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3589
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3590 @example
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3591 ...
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3592 (inst ("IF" exp "THEN" insts "ELSE" insts "END")
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3593 ("CASE" exp "OF" cases "END")
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3594 ...)
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3595 (cases (cases "|" cases) (caselabel ":" insts) ("ELSE" insts))
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3596 ...
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3597 @end example
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3598
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3599 But this will create conflicts for @code{"ELSE"}: on the one hand, the
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3600 IF rule implies (among many other things) that @code{"ELSE" = "END"};
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3601 but on the other hand, since @code{"ELSE"} appears within @code{cases},
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3602 which appears left of @code{"END"}, we also have @code{"ELSE" > "END"}.
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3603 We can solve the conflict either by using:
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3604 @example
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3605 ...
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3606 (inst ("IF" exp "THEN" insts "ELSE" insts "END")
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3607 ("CASE" exp "OF" cases "END")
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3608 ("CASE" exp "OF" cases "ELSE" insts "END")
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3609 ...)
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3610 (cases (cases "|" cases) (caselabel ":" insts))
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3611 ...
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3612 @end example
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3613 or
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3614 @example
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3615 ...
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3616 (inst ("IF" exp "THEN" else "END")
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3617 ("CASE" exp "OF" cases "END")
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3618 ...)
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3619 (else (insts "ELSE" insts))
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3620 (cases (cases "|" cases) (caselabel ":" insts) (else))
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3621 ...
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3622 @end example
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3623
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3624 Reworking the grammar to try and solve conflicts has its downsides, tho,
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3625 because SMIE assumes that the grammar reflects the logical structure of
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3626 the code, so it is preferable to keep the BNF closer to the intended
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3627 abstract syntax tree.
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3628
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3629 Other times, after careful consideration you may conclude that those
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3630 conflicts are not serious and simply resolve them via the
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3631 @var{resolvers} argument of @code{smie-bnf->prec2}. Usually this is
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3632 because the grammar is simply ambiguous: the conflict does not affect
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3633 the set of programs described by the grammar, but only the way those
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3634 programs are parsed. This is typically the case for separators and
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3635 associative infix operators, where you want to add a resolver like
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3636 @code{'((assoc "|"))}. Another case where this can happen is for the
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3637 classic @emph{dangling else} problem, where you will use @code{'((assoc
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3638 "else" "then"))}. It can also happen for cases where the conflict is
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3639 real and cannot really be resolved, but it is unlikely to pose a problem
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3640 in practice.
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3641
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3642 Finally, in many cases some conflicts will remain despite all efforts to
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3643 restructure the grammar. Do not despair: while the parser cannot be
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3644 made more clever, you can make the lexer as smart as you want. So, the
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3645 solution is then to look at the tokens involved in the conflict and to
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3646 split one of those tokens into 2 (or more) different tokens. E.g. if
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3647 the grammar needs to distinguish between two incompatible uses of the
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3648 token @code{"begin"}, make the lexer return different tokens (say
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3649 @code{"begin-fun"} and @code{"begin-plain"}) depending on which kind of
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3650 @code{"begin"} it finds. This pushes the work of distinguishing the
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3651 different cases to the lexer, which will thus have to look at the
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3652 surrounding text to find ad-hoc clues.
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3653
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3654 @node SMIE Indentation
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3655 @subsubsection Specifying Indentation Rules
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3656
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3657 Based on the provided grammar, SMIE will be able to provide automatic
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3658 indentation without any extra effort. But in practice, this default
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3659 indentation style will probably not be good enough. You will want to
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3660 tweak it in many different cases.
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3661
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3662 SMIE indentation is based on the idea that indentation rules should be
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3663 as local as possible. To this end, it relies on the idea of
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3664 @emph{virtual} indentation, which is the indentation that a particular
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3665 program point would have if it were at the beginning of a line.
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3666 Of course, if that program point is indeed at the beginning of a line,
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3667 its virtual indentation is its current indentation. But if not, then
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3668 SMIE uses the indentation algorithm to compute the virtual indentation
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3669 of that point. Now in practice, the virtual indentation of a program
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3670 point does not have to be identical to the indentation it would have if
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3671 we inserted a newline before it. To see how this works, the SMIE rule
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3672 for indentation after a @code{@{} in C does not care whether the
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3673 @code{@{} is standing on a line of its own or is at the end of the
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3674 preceding line. Instead, these different cases are handled in the
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3675 indentation rule that decides how to indent before a @code{@{}.
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3676
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3677 Another important concept is the notion of @emph{parent}: The
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3678 @emph{parent} of a token, is the head token of the nearest enclosing
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3679 syntactic construct. For example, the parent of an @code{else} is the
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3680 @code{if} to which it belongs, and the parent of an @code{if}, in turn,
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3681 is the lead token of the surrounding construct. The command
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3682 @code{backward-sexp} jumps from a token to its parent, but there are
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3683 some caveats: for @emph{openers} (tokens which start a construct, like
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3684 @code{if}), you need to start with point before the token, while for
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3685 others you need to start with point after the token.
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3686 @code{backward-sexp} stops with point before the parent token if that is
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3687 the @emph{opener} of the token of interest, and otherwise it stops with
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3688 point after the parent token.
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3689
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3690 SMIE indentation rules are specified using a function that takes two
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3691 arguments @var{method} and @var{arg} where the meaning of @var{arg} and the
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3692 expected return value depend on @var{method}.
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3693
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3694 @var{method} can be:
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3695 @itemize
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3696 @item
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3697 @code{:after}, in which case @var{arg} is a token and the function
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3698 should return the @var{offset} to use for indentation after @var{arg}.
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3699 @item
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3700 @code{:before}, in which case @var{arg} is a token and the function
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3701 should return the @var{offset} to use to indent @var{arg} itself.
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3702 @item
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3703 @code{:elem}, in which case the function should return either the offset
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3704 to use to indent function arguments (if @var{arg} is the symbol
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3705 @code{arg}) or the basic indentation step (if @var{arg} is the symbol
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3706 @code{basic}).
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3707 @item
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3708 @code{:list-intro}, in which case @var{arg} is a token and the function
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3709 should return non-@code{nil} if the token is followed by a list of
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3710 expressions (not separated by any token) rather than an expression.
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3711 @end itemize
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3712
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3713 When @var{arg} is a token, the function is called with point just before
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3714 that token. A return value of nil always means to fallback on the
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3715 default behavior, so the function should return nil for arguments it
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3716 does not expect.
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3717
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3718 @var{offset} can be:
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3719 @itemize
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3720 @item
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3721 @code{nil}: use the default indentation rule.
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3722 @item
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3723 @code{(column . @var{column})}: indent to column @var{column}.
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3724 @item
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3725 @var{number}: offset by @var{number}, relative to a base token which is
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3726 the current token for @code{:after} and its parent for @code{:before}.
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3727 @end itemize
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3728
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3729 @node SMIE Indentation Helpers
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3730 @subsubsection Helper Functions for Indentation Rules
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3731
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3732 SMIE provides various functions designed specifically for use in the
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3733 indentation rules function (several of those functions break if used in
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3734 another context). These functions all start with the prefix
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3735 @code{smie-rule-}.
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3736
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3737 @defun smie-rule-bolp
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3738 Return non-@code{nil} if the current token is the first on the line.
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3739 @end defun
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3740
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3741 @defun smie-rule-hanging-p
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3742 Return non-@code{nil} if the current token is @emph{hanging}.
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3743 A token is @emph{hanging} if it is the last token on the line
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3744 and if it is preceded by other tokens: a lone token on a line is not
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3745 hanging.
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3746 @end defun
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3747
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3748 @defun smie-rule-next-p &rest tokens
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3749 Return non-@code{nil} if the next token is among @var{tokens}.
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3750 @end defun
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3751
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3752 @defun smie-rule-prev-p &rest tokens
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3753 Return non-@code{nil} if the previous token is among @var{tokens}.
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3754 @end defun
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3755
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3756 @defun smie-rule-parent-p &rest parents
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3757 Return non-@code{nil} if the current token's parent is among @var{parents}.
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3758 @end defun
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3759
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3760 @defun smie-rule-sibling-p
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3761 Return non-nil if the current token's parent is actually a sibling.
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3762 This is the case for example when the parent of a @code{","} is just the
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3763 previous @code{","}.
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3764 @end defun
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3765
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3766 @defun smie-rule-parent &optional offset
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3767 Return the proper offset to align the current token with the parent.
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3768 If non-@code{nil}, @var{offset} should be an integer giving an
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3769 additional offset to apply.
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3770 @end defun
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3771
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3772 @defun smie-rule-separator method
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3773 Indent current token as a @emph{separator}.
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3774
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3775 By @emph{separator}, we mean here a token whose sole purpose is to
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3776 separate various elements within some enclosing syntactic construct, and
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3777 which does not have any semantic significance in itself (i.e. it would
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3778 typically not exist as a node in an abstract syntax tree).
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3779
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3780 Such a token is expected to have an associative syntax and be closely
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3781 tied to its syntactic parent. Typical examples are @code{","} in lists
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3782 of arguments (enclosed inside parentheses), or @code{";"} in sequences
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3783 of instructions (enclosed in a @code{@{...@}} or @code{begin...end}
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3784 block).
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3785
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3786 @var{method} should be the method name that was passed to
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3787 `smie-rules-function'.
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3788 @end defun
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3789
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3790 @node SMIE Indentation Example
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3791 @subsubsection Sample Indentation Rules
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3792
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3793 Here is an example of an indentation function:
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3794
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3795 @example
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3796 (defun sample-smie-rules (kind token)
111945
c00190a8c8ef Merge from emacs-23
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111918
diff changeset
3797 (pcase (cons kind token)
c00190a8c8ef Merge from emacs-23
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111918
diff changeset
3798 (`(:elem . basic) sample-indent-basic)
c00190a8c8ef Merge from emacs-23
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111918
diff changeset
3799 (`(,_ . ",") (smie-rule-separator kind))
c00190a8c8ef Merge from emacs-23
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111918
diff changeset
3800 (`(:after . ":=") sample-indent-basic)
c00190a8c8ef Merge from emacs-23
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111918
diff changeset
3801 (`(:before . ,(or `"begin" `"(" `"@{")))
c00190a8c8ef Merge from emacs-23
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111918
diff changeset
3802 (if (smie-rule-hanging-p) (smie-rule-parent)))
c00190a8c8ef Merge from emacs-23
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111918
diff changeset
3803 (`(:before . "if")
c00190a8c8ef Merge from emacs-23
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111918
diff changeset
3804 (and (not (smie-rule-bolp)) (smie-rule-prev-p "else")
c00190a8c8ef Merge from emacs-23
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111918
diff changeset
3805 (smie-rule-parent)))))
111918
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3806 @end example
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3807
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3808 @noindent
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3809 A few things to note:
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3810
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3811 @itemize
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3812 @item
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3813 The first case indicates the basic indentation increment to use.
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3814 If @code{sample-indent-basic} is nil, then SMIE uses the global
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3815 setting @code{smie-indent-basic}. The major mode could have set
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3816 @code{smie-indent-basic} buffer-locally instead, but that
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3817 is discouraged.
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3818
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3819 @item
111945
c00190a8c8ef Merge from emacs-23
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111918
diff changeset
3820 The rule for the token @code{","} make SMIE try to be more clever when
c00190a8c8ef Merge from emacs-23
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111918
diff changeset
3821 the comma separator is placed at the beginning of lines. It tries to
c00190a8c8ef Merge from emacs-23
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111918
diff changeset
3822 outdent the separator so as to align the code after the comma; for
c00190a8c8ef Merge from emacs-23
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111918
diff changeset
3823 example:
111918
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3824
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3825 @example
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3826 x = longfunctionname (
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3827 arg1
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3828 , arg2
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3829 );
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3830 @end example
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3831
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3832 @item
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3833 The rule for indentation after @code{":="} exists because otherwise
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3834 SMIE would treat @code{":="} as an infix operator and would align the
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3835 right argument with the left one.
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3836
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3837 @item
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3838 The rule for indentation before @code{"begin"} is an example of the use
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3839 of virtual indentation: This rule is used only when @code{"begin"} is
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3840 hanging, which can happen only when @code{"begin"} is not at the
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3841 beginning of a line. So this is not used when indenting
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3842 @code{"begin"} itself but only when indenting something relative to this
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3843 @code{"begin"}. Concretely, this rule changes the indentation from:
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3844
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3845 @example
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3846 if x > 0 then begin
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3847 dosomething(x);
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3848 end
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3849 @end example
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3850 to
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3851 @example
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3852 if x > 0 then begin
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3853 dosomething(x);
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3854 end
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3855 @end example
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3856
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3857 @item
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3858 The rule for indentation before @code{"if"} is similar to the one for
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3859 @code{"begin"}, but where the purpose is to treat @code{"else if"}
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3860 as a single unit, so as to align a sequence of tests rather than indent
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3861 each test further to the right. This function does this only in the
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3862 case where the @code{"if"} is not placed on a separate line, hence the
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3863 @code{smie-rule-bolp} test.
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3864
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3865 If we know that the @code{"else"} is always aligned with its @code{"if"}
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3866 and is always at the beginning of a line, we can use a more efficient
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3867 rule:
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3868 @example
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3869 ((equal token "if")
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3870 (and (not (smie-rule-bolp)) (smie-rule-prev-p "else")
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3871 (save-excursion
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3872 (sample-smie-backward-token) ;Jump before the "else".
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3873 (cons 'column (current-column)))))
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3874 @end example
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3875
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3876 The advantage of this formulation is that it reuses the indentation of
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3877 the previous @code{"else"}, rather than going all the way back to the
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3878 first @code{"if"} of the sequence.
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3879 @end itemize
e71e87e08d5f * doc/lispref/modes.texi (Auto-Indentation): New section to document SMIE.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 111887
diff changeset
3880
84089
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3881 @node Desktop Save Mode
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3882 @section Desktop Save Mode
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3883 @cindex desktop save mode
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3884
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3885 @dfn{Desktop Save Mode} is a feature to save the state of Emacs from
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3886 one session to another. The user-level commands for using Desktop
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3887 Save Mode are described in the GNU Emacs Manual (@pxref{Saving Emacs
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3888 Sessions,,, emacs, the GNU Emacs Manual}). Modes whose buffers visit
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3889 a file, don't have to do anything to use this feature.
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3890
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3891 For buffers not visiting a file to have their state saved, the major
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3892 mode must bind the buffer local variable @code{desktop-save-buffer} to
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3893 a non-@code{nil} value.
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3894
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3895 @defvar desktop-save-buffer
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3896 If this buffer-local variable is non-@code{nil}, the buffer will have
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3897 its state saved in the desktop file at desktop save. If the value is
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3898 a function, it is called at desktop save with argument
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3899 @var{desktop-dirname}, and its value is saved in the desktop file along
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3900 with the state of the buffer for which it was called. When file names
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3901 are returned as part of the auxiliary information, they should be
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3902 formatted using the call
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3903
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3904 @example
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3905 (desktop-file-name @var{file-name} @var{desktop-dirname})
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3906 @end example
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3907
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3908 @end defvar
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3909
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3910 For buffers not visiting a file to be restored, the major mode must
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3911 define a function to do the job, and that function must be listed in
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3912 the alist @code{desktop-buffer-mode-handlers}.
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3913
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3914 @defvar desktop-buffer-mode-handlers
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3915 Alist with elements
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3916
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3917 @example
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3918 (@var{major-mode} . @var{restore-buffer-function})
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3919 @end example
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3920
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3921 The function @var{restore-buffer-function} will be called with
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3922 argument list
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3923
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3924 @example
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3925 (@var{buffer-file-name} @var{buffer-name} @var{desktop-buffer-misc})
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3926 @end example
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3927
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3928 and it should return the restored buffer.
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3929 Here @var{desktop-buffer-misc} is the value returned by the function
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3930 optionally bound to @code{desktop-save-buffer}.
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3931 @end defvar
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3932
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3933 @ignore
111887
0eb10986b8f2 * doc/lispref/backups.texi (Making Backups):
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 109948
diff changeset
3934 Local Variables:
0eb10986b8f2 * doc/lispref/backups.texi (Making Backups):
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 109948
diff changeset
3935 fill-column: 72
0eb10986b8f2 * doc/lispref/backups.texi (Making Backups):
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 109948
diff changeset
3936 End:
84089
b9cb597718e5 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3937 @end ignore