Commit | Line | Data |
---|---|---|
8875da1e | 1 | @c This is part of the Emacs manual. |
acaf905b | 2 | @c Copyright (C) 1985-1987, 1993-1995, 1997, 2000-2012 |
8875da1e CY |
3 | @c Free Software Foundation, Inc. |
4 | @c See file emacs.texi for copying conditions. | |
5 | @node Modes, Indentation, International, Top | |
dc95a8b0 | 6 | @chapter Major and Minor Modes |
8875da1e | 7 | |
dc95a8b0 CY |
8 | Emacs contains many @dfn{editing modes} that alter its basic |
9 | behavior in useful ways. These are divided into @dfn{major modes} and | |
10 | @dfn{minor modes}. | |
8875da1e CY |
11 | |
12 | Major modes provide specialized facilities for working on a | |
13 | particular file type, such as a C source file (@pxref{Programs}), or a | |
14 | particular type of non-file buffer, such as a shell buffer | |
15 | (@pxref{Shell}). Major modes are mutually exclusive; each buffer has | |
16 | one and only one major mode at any time. | |
17 | ||
18 | Minor modes are optional features which you can turn on or off, not | |
19 | necessarily specific to a type of file or buffer. For example, Auto | |
20 | Fill mode is a minor mode in which @key{SPC} breaks lines between | |
21 | words as you type (@pxref{Auto Fill}). Minor modes are independent of | |
22 | one another, and of the selected major mode. | |
23 | ||
24 | @menu | |
25 | * Major Modes:: Text mode vs. Lisp mode vs. C mode... | |
26 | * Minor Modes:: Each minor mode is a feature you can turn on | |
27 | independently of any others. | |
28 | * Choosing Modes:: How modes are chosen when visiting files. | |
29 | @end menu | |
30 | ||
31 | @node Major Modes | |
32 | @section Major Modes | |
33 | @cindex major modes | |
34 | @cindex mode, major | |
35 | @kindex TAB @r{(and major modes)} | |
36 | @kindex DEL @r{(and major modes)} | |
37 | @kindex C-j @r{(and major modes)} | |
38 | ||
39 | Every buffer possesses a major mode, which determines the editing | |
40 | behavior of Emacs while that buffer is current. The mode line | |
dc95a8b0 CY |
41 | normally shows the name of the current major mode, in parentheses |
42 | (@pxref{Mode Line}). | |
8875da1e CY |
43 | |
44 | The least specialized major mode is called @dfn{Fundamental mode}. | |
45 | This mode has no mode-specific redefinitions or variable settings, so | |
46 | that each Emacs command behaves in its most general manner, and each | |
47 | user option variable is in its default state. | |
48 | ||
49 | For editing text of a specific type that Emacs knows about, such as | |
50 | Lisp code or English text, you typically use a more specialized major | |
dc95a8b0 CY |
51 | mode, such as Lisp mode or Text mode. Most major modes fall into |
52 | three major groups. The first group contains modes for normal text, | |
53 | either plain or with mark-up. It includes Text mode, HTML mode, SGML | |
54 | mode, @TeX{} mode and Outline mode. The second group contains modes | |
55 | for specific programming languages. These include Lisp mode (which | |
56 | has several variants), C mode, Fortran mode, and others. The third | |
57 | group consists of major modes that are not associated directly with | |
58 | files; they are used in buffers created for specific purposes by | |
59 | Emacs, such as Dired mode for buffers made by Dired (@pxref{Dired}), | |
60 | Message mode for buffers made by @kbd{C-x m} (@pxref{Sending Mail}), | |
61 | and Shell mode for buffers used to communicate with an inferior shell | |
62 | process (@pxref{Interactive Shell}). | |
63 | ||
64 | Usually, the major mode is automatically set by Emacs, when you | |
65 | first visit a file or create a buffer (@pxref{Choosing Modes}). You | |
66 | can explicitly select a new major mode by using an @kbd{M-x} command. | |
67 | Take the name of the mode and add @code{-mode} to get the name of the | |
68 | command to select that mode. Thus, you can enter Lisp mode with | |
69 | @kbd{M-x lisp-mode}. | |
70 | ||
71 | @vindex major-mode | |
72 | The value of the buffer-local variable @code{major-mode} is a symbol | |
73 | with the same name as the major mode command (e.g. @code{lisp-mode}). | |
74 | This variable is set automatically; you should not change it yourself. | |
75 | ||
76 | The default value of @code{major-mode} determines the major mode to | |
77 | use for files that do not specify a major mode, and for new buffers | |
78 | created with @kbd{C-x b}. Normally, this default value is the symbol | |
79 | @code{fundamental-mode}, which specifies Fundamental mode. You can | |
80 | change this default value via the Customization interface (@pxref{Easy | |
81 | Customization}), or by adding a line like this to your init file | |
82 | (@pxref{Init File}): | |
83 | ||
84 | @smallexample | |
85 | (setq-default major-mode 'text-mode) | |
86 | @end smallexample | |
87 | ||
88 | @noindent | |
89 | If the default value of @code{major-mode} is @code{nil}, the major | |
90 | mode is taken from the previously current buffer. | |
91 | ||
92 | Specialized major modes often change the meanings of certain keys to | |
93 | do something more suitable for the mode. For instance, programming | |
94 | language modes bind @key{TAB} to indent the current line according to | |
95 | the rules of the language (@pxref{Indentation}). The keys that are | |
96 | commonly changed are @key{TAB}, @key{DEL}, and @kbd{C-j}. Many modes | |
97 | also define special commands of their own, usually bound in the prefix | |
98 | key @kbd{C-c}. Major modes can also alter user options and variables; | |
22bcf204 | 99 | for instance, programming language modes typically set a buffer-local |
dc95a8b0 CY |
100 | value for the variable @code{comment-start}, which determines how |
101 | source code comments are delimited (@pxref{Comments}). | |
102 | ||
103 | @findex describe-mode | |
104 | @kindex C-h m | |
105 | To view the documentation for the current major mode, including a | |
106 | list of its key bindings, type @code{C-h m} (@code{describe-mode}). | |
107 | ||
108 | @cindex mode hook | |
109 | @vindex text-mode-hook | |
110 | @vindex prog-mode-hook | |
111 | Every major mode, apart from Fundamental mode, defines a @dfn{mode | |
112 | hook}, a customizable list of Lisp functions to run each time the mode | |
113 | is enabled in a buffer. @xref{Hooks}, for more information about | |
114 | hooks. Each mode hook is named after its major mode, e.g. Fortran | |
115 | mode has @code{fortran-mode-hook}. Furthermore, all text-based major | |
116 | modes run @code{text-mode-hook}, and all programming language modes | |
117 | run @code{prog-mode-hook}, prior to running their own mode hooks. | |
95ca9bc7 CY |
118 | Hook functions can look at the value of the variable @code{major-mode} |
119 | to see which mode is actually being entered. | |
dc95a8b0 CY |
120 | |
121 | Mode hooks are commonly used to enable minor modes (@pxref{Minor | |
122 | Modes}). For example, you can put the following lines in your init | |
123 | file to enable Flyspell minor mode in all text-based major modes | |
124 | (@pxref{Spelling}), and Eldoc minor mode in Emacs Lisp mode | |
125 | (@pxref{Lisp Doc}): | |
126 | ||
127 | @example | |
128 | (add-hook 'text-mode-hook 'flyspell-mode) | |
129 | (add-hook 'emacs-lisp-mode-hook 'eldoc-mode) | |
130 | @end example | |
8875da1e CY |
131 | |
132 | @node Minor Modes | |
133 | @section Minor Modes | |
134 | @cindex minor modes | |
135 | @cindex mode, minor | |
136 | ||
dc95a8b0 CY |
137 | A minor mode is an optional editing mode that alters the behavior of |
138 | Emacs in some well-defined way. Unlike major modes, any number of | |
8875da1e | 139 | minor modes can be in effect at any time. Some minor modes are |
dc95a8b0 CY |
140 | @dfn{buffer-local}, and can be turned on (enabled) in certain buffers |
141 | and off (disabled) in others. Other minor modes are @dfn{global}: | |
142 | while enabled, they affect everything you do in the Emacs session, in | |
143 | all buffers. Most minor modes are disabled by default, but a few are | |
144 | enabled by default. | |
145 | ||
146 | Most buffer-local minor modes say in the mode line when they are | |
147 | enabled, just after the major mode indicator. For example, | |
148 | @samp{Fill} in the mode line means that Auto Fill mode is enabled. | |
149 | @xref{Mode Line}. | |
150 | ||
151 | @cindex mode commands for minor modes | |
152 | Like major modes, each minor mode is associated with a @dfn{mode | |
153 | command}, whose name consists of the mode name followed by | |
154 | @samp{-mode}. For instance, the mode command for Auto Fill mode is | |
155 | @code{auto-fill-mode}. But unlike a major mode command, which simply | |
156 | enables the mode, the mode command for a minor mode can either enable | |
157 | or disable it: | |
158 | ||
159 | @itemize | |
160 | @item | |
161 | If you invoke the mode command directly with no prefix argument | |
162 | (either via @kbd{M-x}, or by binding it to a key and typing that key; | |
163 | @pxref{Key Bindings}), that @dfn{toggles} the minor mode. The minor | |
164 | mode is turned on if it was off, and turned off if it was on. | |
165 | ||
166 | @item | |
167 | If you invoke the mode command with a prefix argument, the minor mode | |
168 | is unconditionally turned off if that argument is zero or negative; | |
169 | otherwise, it is unconditionally turned on. | |
170 | ||
171 | @item | |
172 | If the mode command is called via Lisp, the minor mode is | |
173 | unconditionally turned on if the argument is omitted or @code{nil}. | |
174 | This makes it easy to turn on a minor mode from a major mode's mode | |
175 | hook (@pxref{Major Modes}). A non-@code{nil} argument is handled like | |
176 | an interactive prefix argument, as described above. | |
177 | @end itemize | |
8875da1e CY |
178 | |
179 | Most minor modes also have a @dfn{mode variable}, with the same name | |
180 | as the mode command. Its value is non-@code{nil} if the mode is | |
dc95a8b0 CY |
181 | enabled, and @code{nil} if it is disabled. In general, you should not |
182 | try to enable or disable the mode by changing the value of the mode | |
183 | variable directly in Lisp; you should run the mode command instead. | |
184 | However, setting the mode variable through the Customize interface | |
185 | (@pxref{Easy Customization}) will always properly enable or disable | |
186 | the mode, since Customize automatically runs the mode command for you. | |
8875da1e CY |
187 | |
188 | The following is a list of some buffer-local minor modes: | |
189 | ||
190 | @itemize @bullet | |
191 | @item | |
192 | Abbrev mode automatically expands text based on pre-defined | |
193 | abbreviation definitions. @xref{Abbrevs}. | |
194 | ||
195 | @item | |
196 | Auto Fill mode inserts newlines as you type to prevent lines from | |
197 | becoming too long. @xref{Filling}. | |
198 | ||
199 | @item | |
200 | Auto Save mode saves the buffer contents periodically to reduce the | |
201 | amount of work you can lose in case of a crash. @xref{Auto Save}. | |
202 | ||
203 | @item | |
204 | Enriched mode enables editing and saving of formatted text. | |
8863a584 | 205 | @xref{Enriched Text}. |
8875da1e CY |
206 | |
207 | @item | |
208 | Flyspell mode automatically highlights misspelled words. | |
209 | @xref{Spelling}. | |
210 | ||
211 | @item | |
212 | Font-Lock mode automatically highlights certain textual units found in | |
213 | programs. It is enabled globally by default, but you can disable it | |
214 | in individual buffers. @xref{Faces}. | |
215 | ||
216 | @findex linum-mode | |
217 | @cindex Linum mode | |
218 | @item | |
219 | Linum mode displays each line's line number in the window's left | |
220 | margin. Its mode command is @code{linum-mode}. | |
221 | ||
222 | @item | |
223 | Outline minor mode provides similar facilities to the major mode | |
224 | called Outline mode. @xref{Outline Mode}. | |
225 | ||
226 | @cindex Overwrite mode | |
227 | @cindex mode, Overwrite | |
228 | @findex overwrite-mode | |
229 | @kindex INSERT | |
230 | @item | |
231 | Overwrite mode causes ordinary printing characters to replace existing | |
232 | text instead of shoving it to the right. For example, if point is in | |
233 | front of the @samp{B} in @samp{FOOBAR}, then in Overwrite mode typing | |
234 | a @kbd{G} changes it to @samp{FOOGAR}, instead of producing | |
235 | @samp{FOOGBAR} as usual. In Overwrite mode, the command @kbd{C-q} | |
236 | inserts the next character whatever it may be, even if it is a | |
237 | digit---this gives you a way to insert a character instead of | |
238 | replacing an existing character. The mode command, | |
239 | @code{overwrite-mode}, is bound to the @key{Insert} key. | |
240 | ||
241 | @findex binary-overwrite-mode | |
242 | @item | |
243 | Binary Overwrite mode is a variant of Overwrite mode for editing | |
244 | binary files; it treats newlines and tabs like other characters, so | |
245 | that they overwrite other characters and can be overwritten by them. | |
246 | In Binary Overwrite mode, digits after @kbd{C-q} specify an octal | |
247 | character code, as usual. | |
248 | ||
249 | @item | |
250 | Visual Line mode performs ``word wrapping'', causing long lines to be | |
251 | wrapped at word boundaries. @xref{Visual Line Mode}. | |
252 | @end itemize | |
253 | ||
dc95a8b0 CY |
254 | @noindent |
255 | And here are some useful global minor modes: | |
8875da1e CY |
256 | |
257 | @itemize @bullet | |
258 | @item | |
259 | Column Number mode enables display of the current column number in the | |
260 | mode line. @xref{Mode Line}. | |
261 | ||
262 | @item | |
263 | Delete Selection mode causes text insertion to first delete the text | |
264 | in the region, if the region is active. @xref{Using Region}. | |
265 | ||
266 | @item | |
267 | Icomplete mode displays an indication of available completions when | |
268 | you are in the minibuffer and completion is active. @xref{Completion | |
269 | Options}. | |
270 | ||
271 | @item | |
272 | Line Number mode enables display of the current line number in the | |
273 | mode line. It is enabled by default. @xref{Mode Line}. | |
274 | ||
275 | @item | |
276 | Menu Bar mode gives each frame a menu bar. It is enabled by default. | |
277 | @xref{Menu Bars}. | |
278 | ||
279 | @item | |
280 | Scroll Bar mode gives each window a scroll bar. It is enabled by | |
281 | default, but the scroll bar is only displayed on graphical terminals. | |
282 | @xref{Scroll Bars}. | |
283 | ||
284 | @item | |
285 | Tool Bar mode gives each frame a tool bar. It is enabled by default, | |
286 | but the tool bar is only displayed on graphical terminals. @xref{Tool | |
287 | Bars}. | |
288 | ||
289 | @item | |
290 | Transient Mark mode highlights the region, and makes many Emacs | |
291 | commands operate on the region when the mark is active. It is enabled | |
292 | by default. @xref{Mark}. | |
293 | @end itemize | |
294 | ||
295 | @node Choosing Modes | |
296 | @section Choosing File Modes | |
297 | ||
298 | @cindex choosing a major mode | |
299 | @cindex choosing a minor mode | |
300 | @vindex auto-mode-alist | |
301 | When you visit a file, Emacs chooses a major mode automatically. | |
302 | Normally, it makes the choice based on the file name---for example, | |
303 | files whose names end in @samp{.c} are normally edited in C mode---but | |
304 | sometimes it chooses the major mode based on special text in the file. | |
305 | This special text can also be used to enable buffer-local minor modes. | |
306 | ||
307 | Here is the exact procedure: | |
308 | ||
309 | First, Emacs checks whether the file contains file-local mode | |
310 | variables. @xref{File Variables}. If there is a file-local variable | |
311 | that specifies a major mode, then Emacs uses that major mode, ignoring | |
312 | all other criteria. There are several methods to specify a major mode | |
313 | using a file-local variable; the simplest is to put the mode name in | |
314 | the first nonblank line, preceded and followed by @samp{-*-}. Other | |
315 | text may appear on the line as well. For example, | |
316 | ||
317 | @example | |
318 | ; -*-Lisp-*- | |
319 | @end example | |
320 | ||
321 | @noindent | |
322 | tells Emacs to use Lisp mode. Note how the semicolon is used to make | |
dc95a8b0 | 323 | Lisp treat this line as a comment. You could equivalently write |
8875da1e CY |
324 | |
325 | @example | |
326 | ; -*- mode: Lisp;-*- | |
327 | @end example | |
328 | ||
329 | @noindent | |
dc95a8b0 CY |
330 | You can also use file-local variables to specify buffer-local minor |
331 | modes, by using @code{eval} specifications. For example, this first | |
332 | nonblank line puts the buffer in Lisp mode and enables Auto-Fill mode: | |
8875da1e CY |
333 | |
334 | @example | |
dc95a8b0 | 335 | ; -*- mode: Lisp; eval: (auto-fill-mode 1); -*- |
8875da1e CY |
336 | @end example |
337 | ||
dc95a8b0 CY |
338 | @noindent |
339 | Note, however, that it is usually inappropriate to enable minor modes | |
340 | this way, since most minor modes represent individual user | |
341 | preferences. If you personally want to use a minor mode for a | |
342 | particular file type, it is better to enable the minor mode via a | |
343 | major mode hook (@pxref{Major Modes}). | |
8875da1e CY |
344 | |
345 | @vindex interpreter-mode-alist | |
346 | Second, if there is no file variable specifying a major mode, Emacs | |
347 | checks whether the file's contents begin with @samp{#!}. If so, that | |
348 | indicates that the file can serve as an executable shell command, | |
349 | which works by running an interpreter named on the file's first line | |
350 | (the rest of the file is used as input to the interpreter). | |
351 | Therefore, Emacs tries to use the interpreter name to choose a mode. | |
352 | For instance, a file that begins with @samp{#!/usr/bin/perl} is opened | |
353 | in Perl mode. The variable @code{interpreter-mode-alist} specifies | |
354 | the correspondence between interpreter program names and major modes. | |
355 | ||
356 | When the first line starts with @samp{#!}, you usually cannot use | |
357 | the @samp{-*-} feature on the first line, because the system would get | |
358 | confused when running the interpreter. So Emacs looks for @samp{-*-} | |
359 | on the second line in such files as well as on the first line. The | |
360 | same is true for man pages which start with the magic string | |
361 | @samp{'\"} to specify a list of troff preprocessors. | |
362 | ||
363 | @vindex magic-mode-alist | |
364 | Third, Emacs tries to determine the major mode by looking at the | |
365 | text at the start of the buffer, based on the variable | |
366 | @code{magic-mode-alist}. By default, this variable is @code{nil} (an | |
367 | empty list), so Emacs skips this step; however, you can customize it | |
368 | in your init file (@pxref{Init File}). The value should be a list of | |
369 | elements of the form | |
370 | ||
371 | @example | |
372 | (@var{regexp} . @var{mode-function}) | |
373 | @end example | |
374 | ||
375 | @noindent | |
376 | where @var{regexp} is a regular expression (@pxref{Regexps}), and | |
dc95a8b0 CY |
377 | @var{mode-function} is a major mode command. If the text at the |
378 | beginning of the file matches @var{regexp}, Emacs chooses the major | |
379 | mode specified by @var{mode-function}. | |
8875da1e CY |
380 | |
381 | Alternatively, an element of @code{magic-mode-alist} may have the form | |
382 | ||
383 | @example | |
384 | (@var{match-function} . @var{mode-function}) | |
385 | @end example | |
386 | ||
387 | @noindent | |
388 | where @var{match-function} is a Lisp function that is called at the | |
389 | beginning of the buffer; if the function returns non-@code{nil}, Emacs | |
dc95a8b0 | 390 | set the major mode with @var{mode-function}. |
8875da1e CY |
391 | |
392 | Fourth---if Emacs still hasn't found a suitable major mode---it | |
393 | looks at the file's name. The correspondence between file names and | |
394 | major modes is controlled by the variable @code{auto-mode-alist}. Its | |
395 | value is a list in which each element has this form, | |
396 | ||
397 | @example | |
398 | (@var{regexp} . @var{mode-function}) | |
399 | @end example | |
400 | ||
401 | @noindent | |
402 | or this form, | |
403 | ||
404 | @example | |
405 | (@var{regexp} @var{mode-function} @var{flag}) | |
406 | @end example | |
407 | ||
408 | @noindent | |
409 | For example, one element normally found in the list has the form | |
410 | @code{(@t{"\\.c\\'"} . c-mode)}, and it is responsible for selecting C | |
411 | mode for files whose names end in @file{.c}. (Note that @samp{\\} is | |
412 | needed in Lisp syntax to include a @samp{\} in the string, which must | |
413 | be used to suppress the special meaning of @samp{.} in regexps.) If | |
414 | the element has the form @code{(@var{regexp} @var{mode-function} | |
415 | @var{flag})} and @var{flag} is non-@code{nil}, then after calling | |
416 | @var{mode-function}, Emacs discards the suffix that matched | |
417 | @var{regexp} and searches the list again for another match. | |
418 | ||
419 | @vindex auto-mode-case-fold | |
3fd50d5c CY |
420 | On GNU/Linux and other systems with case-sensitive file names, Emacs |
421 | performs a case-sensitive search through @code{auto-mode-alist}; if | |
422 | this search fails, it performs a second case-insensitive search | |
423 | through the alist. To suppress the second search, change the variable | |
424 | @code{auto-mode-case-fold} to @code{nil}. On systems with | |
425 | case-insensitive file names, such as Microsoft Windows, Emacs performs | |
426 | a single case-insensitive search through @code{auto-mode-alist}. | |
8875da1e CY |
427 | |
428 | @vindex magic-fallback-mode-alist | |
429 | Finally, if Emacs @emph{still} hasn't found a major mode to use, it | |
430 | compares the text at the start of the buffer to the variable | |
431 | @code{magic-fallback-mode-alist}. This variable works like | |
432 | @code{magic-mode-alist}, described above, except that is consulted | |
433 | only after @code{auto-mode-alist}. By default, | |
434 | @code{magic-fallback-mode-alist} contains forms that check for image | |
7877f373 | 435 | files, HTML/XML/SGML files, and PostScript files. |
8875da1e | 436 | |
8875da1e CY |
437 | @findex normal-mode |
438 | If you have changed the major mode of a buffer, you can return to | |
439 | the major mode Emacs would have chosen automatically, by typing | |
440 | @kbd{M-x normal-mode}. This is the same function that | |
441 | @code{find-file} calls to choose the major mode. It also processes | |
442 | the file's @samp{-*-} line or local variables list (if any). | |
443 | @xref{File Variables}. | |
444 | ||
445 | @vindex change-major-mode-with-file-name | |
446 | The commands @kbd{C-x C-w} and @code{set-visited-file-name} change to | |
447 | a new major mode if the new file name implies a mode (@pxref{Saving}). | |
448 | (@kbd{C-x C-s} does this too, if the buffer wasn't visiting a file.) | |
449 | However, this does not happen if the buffer contents specify a major | |
450 | mode, and certain ``special'' major modes do not allow the mode to | |
451 | change. You can turn off this mode-changing feature by setting | |
452 | @code{change-major-mode-with-file-name} to @code{nil}. |