1 @c -*- coding: utf-8 -*-
2 @c This is part of the Emacs manual.
3 @c Copyright (C) 1985-1987, 1993-1995, 1997, 2000-2017 Free Software
5 @c See file emacs.texi for copying conditions.
7 @chapter Major and Minor Modes
9 Emacs contains many @dfn{editing modes} that alter its basic
10 behavior in useful ways. These are divided into @dfn{major modes} and
13 Major modes provide specialized facilities for working on a
14 particular file type, such as a C source file (@pxref{Programs}), or a
15 particular type of non-file buffer, such as a shell buffer
16 (@pxref{Shell}). Major modes are mutually exclusive; each buffer has
17 one and only one major mode at any time.
19 Minor modes are optional features which you can turn on or off, not
20 necessarily specific to a type of file or buffer. For example, Auto
21 Fill mode is a minor mode in which @key{SPC} breaks lines between
22 words as you type (@pxref{Auto Fill}). Minor modes are independent of
23 one another, and of the selected major mode.
26 * Major Modes:: Text mode vs. Lisp mode vs. C mode...
27 * Minor Modes:: Each minor mode is a feature you can turn on
28 independently of any others.
29 * Choosing Modes:: How modes are chosen when visiting files.
36 @kindex TAB @r{(and major modes)}
37 @kindex DEL @r{(and major modes)}
38 @kindex C-j @r{(and major modes)}
40 Every buffer possesses a major mode, which determines the editing
41 behavior of Emacs while that buffer is current. The mode line
42 normally shows the name of the current major mode, in parentheses
45 The least specialized major mode is called @dfn{Fundamental mode}.
46 This mode has no mode-specific redefinitions or variable settings, so
47 that each Emacs command behaves in its most general manner, and each
48 user option variable is in its default state.
50 For editing text of a specific type that Emacs knows about, such as
51 Lisp code or English text, you typically use a more specialized major
52 mode, such as Lisp mode or Text mode. Most major modes fall into
53 three major groups. The first group contains modes for normal text,
54 either plain or with mark-up. It includes Text mode, HTML mode, SGML
55 mode, @TeX{} mode and Outline mode. The second group contains modes
56 for specific programming languages. These include Lisp mode (which
57 has several variants), C mode, Fortran mode, and others. The third
58 group consists of major modes that are not associated directly with
59 files; they are used in buffers created for specific purposes by
60 Emacs, such as Dired mode for buffers made by Dired (@pxref{Dired}),
61 Message mode for buffers made by @kbd{C-x m} (@pxref{Sending Mail}),
62 and Shell mode for buffers used to communicate with an inferior shell
63 process (@pxref{Interactive Shell}).
65 Usually, the major mode is automatically set by Emacs, when you
66 first visit a file or create a buffer (@pxref{Choosing Modes}). You
67 can explicitly select a new major mode by using an @kbd{M-x} command.
68 Take the name of the mode and add @code{-mode} to get the name of the
69 command to select that mode (e.g., @kbd{M-x lisp-mode} enters Lisp
70 mode). Since every buffer has exactly one major mode, there is no way
71 to ``turn off'' a major mode; instead you must switch to a different
75 The value of the buffer-local variable @code{major-mode} is a symbol
76 with the same name as the major mode command (e.g., @code{lisp-mode}).
77 This variable is set automatically; you should not change it yourself.
79 The default value of @code{major-mode} determines the major mode to
80 use for files that do not specify a major mode, and for new buffers
81 created with @kbd{C-x b}. Normally, this default value is the symbol
82 @code{fundamental-mode}, which specifies Fundamental mode. You can
83 change this default value via the Customization interface (@pxref{Easy
84 Customization}), or by adding a line like this to your init file
88 (setq-default major-mode 'text-mode)
92 If the default value of @code{major-mode} is @code{nil}, the major
93 mode is taken from the previously current buffer.
95 Specialized major modes often change the meanings of certain keys to
96 do something more suitable for the mode. For instance, programming
97 language modes bind @key{TAB} to indent the current line according to
98 the rules of the language (@pxref{Indentation}). The keys that are
99 commonly changed are @key{TAB}, @key{DEL}, and @kbd{C-j}. Many modes
100 also define special commands of their own, usually bound in the prefix
101 key @kbd{C-c}. Major modes can also alter user options and variables;
102 for instance, programming language modes typically set a buffer-local
103 value for the variable @code{comment-start}, which determines how
104 source code comments are delimited (@pxref{Comments}).
106 @findex describe-mode
108 To view the documentation for the current major mode, including a
109 list of its key bindings, type @code{C-h m} (@code{describe-mode}).
112 @vindex text-mode-hook
113 @vindex prog-mode-hook
114 Every major mode, apart from Fundamental mode, defines a @dfn{mode
115 hook}, a customizable list of Lisp functions to run each time the mode
116 is enabled in a buffer. @xref{Hooks}, for more information about
117 hooks. Each mode hook is named after its major mode, e.g., Fortran
118 mode has @code{fortran-mode-hook}. Furthermore, all text-based major
119 modes run @code{text-mode-hook}, and many programming language modes
120 @footnote{More specifically, the modes which are ''derived'' from
121 @code{prog-mode} (@pxref{Derived Modes,,, elisp, The Emacs Lisp
122 Reference Manual}).} (including all those distributed with Emacs) run
123 @code{prog-mode-hook}, prior to running their own mode hooks. Hook
124 functions can look at the value of the variable @code{major-mode} to
125 see which mode is actually being entered.
127 Mode hooks are commonly used to enable minor modes (@pxref{Minor
128 Modes}). For example, you can put the following lines in your init
129 file to enable Flyspell minor mode in all text-based major modes
130 (@pxref{Spelling}), and Eldoc minor mode in Emacs Lisp mode
134 (add-hook 'text-mode-hook 'flyspell-mode)
135 (add-hook 'emacs-lisp-mode-hook 'eldoc-mode)
143 A minor mode is an optional editing mode that alters the behavior of
144 Emacs in some well-defined way. Unlike major modes, any number of
145 minor modes can be in effect at any time. Some minor modes are
146 @dfn{buffer-local}, and can be turned on (enabled) in certain buffers
147 and off (disabled) in others. Other minor modes are @dfn{global}:
148 while enabled, they affect everything you do in the Emacs session, in
149 all buffers. Most minor modes are disabled by default, but a few are
152 Most buffer-local minor modes say in the mode line when they are
153 enabled, just after the major mode indicator. For example,
154 @samp{Fill} in the mode line means that Auto Fill mode is enabled.
157 @cindex mode commands for minor modes
158 Like major modes, each minor mode is associated with a @dfn{mode
159 command}, whose name consists of the mode name followed by
160 @samp{-mode}. For instance, the mode command for Auto Fill mode is
161 @code{auto-fill-mode}. But unlike a major mode command, which simply
162 enables the mode, the mode command for a minor mode can either enable
167 If you invoke the mode command directly with no prefix argument
168 (either via @kbd{M-x}, or by binding it to a key and typing that key;
169 @pxref{Key Bindings}), that @dfn{toggles} the minor mode. The minor
170 mode is turned on if it was off, and turned off if it was on.
173 If you invoke the mode command with a prefix argument, the minor mode
174 is unconditionally turned off if that argument is zero or negative;
175 otherwise, it is unconditionally turned on.
178 If the mode command is called via Lisp, the minor mode is
179 unconditionally turned on if the argument is omitted or @code{nil}.
180 This makes it easy to turn on a minor mode from a major mode's mode
181 hook (@pxref{Major Modes}). A non-@code{nil} argument is handled like
182 an interactive prefix argument, as described above.
185 Most minor modes also have a @dfn{mode variable}, with the same name
186 as the mode command. Its value is non-@code{nil} if the mode is
187 enabled, and @code{nil} if it is disabled. In general, you should not
188 try to enable or disable the mode by changing the value of the mode
189 variable directly in Lisp; you should run the mode command instead.
190 However, setting the mode variable through the Customize interface
191 (@pxref{Easy Customization}) will always properly enable or disable
192 the mode, since Customize automatically runs the mode command for you.
194 The following is a list of some buffer-local minor modes:
198 Abbrev mode automatically expands text based on pre-defined
199 abbreviation definitions. @xref{Abbrevs}.
202 Auto Fill mode inserts newlines as you type to prevent lines from
203 becoming too long. @xref{Filling}.
206 Auto Save mode saves the buffer contents periodically to reduce the
207 amount of work you can lose in case of a crash. @xref{Auto Save}.
210 Electric Quote mode automatically converts quotation marks. For
211 example, it requotes text typed @t{`like this'} to text @t{‘like
212 this’}. You can control what kind of text it operates in, and you can
213 disable it entirely in individual buffers. @xref{Quotation Marks}.
216 Enriched mode enables editing and saving of formatted text.
217 @xref{Enriched Text}.
220 Flyspell mode automatically highlights misspelled words.
224 Font-Lock mode automatically highlights certain textual units found in
225 programs. It is enabled globally by default, but you can disable it
226 in individual buffers. @xref{Faces}.
228 @findex display-line-numbers-mode
229 @cindex display-line-numbers-mode
231 Display Line Numbers mode is a convenience wrapper around
232 @code{display-line-numbers}, setting it using the value of
233 @code{display-line-numbers-type}. @xref{Display Custom}.
236 Outline minor mode provides similar facilities to the major mode
237 called Outline mode. @xref{Outline Mode}.
239 @cindex Overwrite mode
240 @cindex mode, Overwrite
241 @findex overwrite-mode
244 Overwrite mode causes ordinary printing characters to replace existing
245 text instead of shoving it to the right. For example, if point is in
246 front of the @samp{B} in @samp{FOOBAR}, then in Overwrite mode typing
247 a @kbd{G} changes it to @samp{FOOGAR}, instead of producing
248 @samp{FOOGBAR} as usual. In Overwrite mode, the command @kbd{C-q}
249 inserts the next character whatever it may be, even if it is a
250 digit---this gives you a way to insert a character instead of
251 replacing an existing character. The mode command,
252 @code{overwrite-mode}, is bound to the @key{Insert} key.
254 @findex binary-overwrite-mode
256 Binary Overwrite mode is a variant of Overwrite mode for editing
257 binary files; it treats newlines and tabs like other characters, so
258 that they overwrite other characters and can be overwritten by them.
259 In Binary Overwrite mode, digits after @kbd{C-q} specify an octal
260 character code, as usual.
263 Visual Line mode performs word wrapping, causing long lines to be
264 wrapped at word boundaries. @xref{Visual Line Mode}.
268 And here are some useful global minor modes:
272 Column Number mode enables display of the current column number in the
273 mode line. @xref{Mode Line}.
276 Delete Selection mode causes text insertion to first delete the text
277 in the region, if the region is active. @xref{Using Region}.
280 Icomplete mode displays an indication of available completions when
281 you are in the minibuffer and completion is active. @xref{Icomplete}.
284 Line Number mode enables display of the current line number in the
285 mode line. It is enabled by default. @xref{Mode Line}.
288 Menu Bar mode gives each frame a menu bar. It is enabled by default.
292 Scroll Bar mode gives each window a scroll bar. It is enabled by
293 default, but the scroll bar is only displayed on graphical terminals.
297 Tool Bar mode gives each frame a tool bar. It is enabled by default,
298 but the tool bar is only displayed on graphical terminals. @xref{Tool
302 Transient Mark mode highlights the region, and makes many Emacs
303 commands operate on the region when the mark is active. It is enabled
304 by default. @xref{Mark}.
308 @section Choosing File Modes
310 @cindex choosing a major mode
311 @cindex choosing a minor mode
312 @vindex auto-mode-alist
313 When you visit a file, Emacs chooses a major mode automatically.
314 Normally, it makes the choice based on the file name---for example,
315 files whose names end in @samp{.c} are normally edited in C mode---but
316 sometimes it chooses the major mode based on special text in the file.
317 This special text can also be used to enable buffer-local minor modes.
319 Here is the exact procedure:
321 First, Emacs checks whether the file contains file-local mode
322 variables. @xref{File Variables}. If there is a file-local variable
323 that specifies a major mode, then Emacs uses that major mode, ignoring
324 all other criteria. There are several methods to specify a major mode
325 using a file-local variable; the simplest is to put the mode name in
326 the first nonblank line, preceded and followed by @samp{-*-}. Other
327 text may appear on the line as well. For example,
334 tells Emacs to use Lisp mode. Note how the semicolon is used to make
335 Lisp treat this line as a comment. You could equivalently write
342 You can also use file-local variables to specify buffer-local minor
343 modes, by using @code{eval} specifications. For example, this first
344 nonblank line puts the buffer in Lisp mode and enables Auto-Fill mode:
347 ; -*- mode: Lisp; eval: (auto-fill-mode 1); -*-
351 Note, however, that it is usually inappropriate to enable minor modes
352 this way, since most minor modes represent individual user
353 preferences. If you personally want to use a minor mode for a
354 particular file type, it is better to enable the minor mode via a
355 major mode hook (@pxref{Major Modes}).
357 @vindex interpreter-mode-alist
358 Second, if there is no file variable specifying a major mode, Emacs
359 checks whether the file's contents begin with @samp{#!}. If so, that
360 indicates that the file can serve as an executable shell command,
361 which works by running an interpreter named on the file's first line
362 (the rest of the file is used as input to the interpreter).
363 Therefore, Emacs tries to use the interpreter name to choose a mode.
364 For instance, a file that begins with @samp{#!/usr/bin/perl} is opened
365 in Perl mode. The variable @code{interpreter-mode-alist} specifies
366 the correspondence between interpreter program names and major modes.
368 When the first line starts with @samp{#!}, you usually cannot use
369 the @samp{-*-} feature on the first line, because the system would get
370 confused when running the interpreter. So Emacs looks for @samp{-*-}
371 on the second line in such files as well as on the first line. The
372 same is true for man pages which start with the magic string
373 @samp{'\"} to specify a list of troff preprocessors.
375 @vindex magic-mode-alist
376 Third, Emacs tries to determine the major mode by looking at the
377 text at the start of the buffer, based on the variable
378 @code{magic-mode-alist}. By default, this variable is @code{nil} (an
379 empty list), so Emacs skips this step; however, you can customize it
380 in your init file (@pxref{Init File}). The value should be a list of
384 (@var{regexp} . @var{mode-function})
388 where @var{regexp} is a regular expression (@pxref{Regexps}), and
389 @var{mode-function} is a major mode command. If the text at the
390 beginning of the file matches @var{regexp}, Emacs chooses the major
391 mode specified by @var{mode-function}.
393 Alternatively, an element of @code{magic-mode-alist} may have the form
396 (@var{match-function} . @var{mode-function})
400 where @var{match-function} is a Lisp function that is called at the
401 beginning of the buffer; if the function returns non-@code{nil}, Emacs
402 set the major mode with @var{mode-function}.
404 Fourth---if Emacs still hasn't found a suitable major mode---it
405 looks at the file's name. The correspondence between file names and
406 major modes is controlled by the variable @code{auto-mode-alist}. Its
407 value is a list in which each element has this form,
410 (@var{regexp} . @var{mode-function})
417 (@var{regexp} @var{mode-function} @var{flag})
421 For example, one element normally found in the list has the form
422 @code{(@t{"\\.c\\'"} . c-mode)}, and it is responsible for selecting C
423 mode for files whose names end in @file{.c}. (Note that @samp{\\} is
424 needed in Lisp syntax to include a @samp{\} in the string, which must
425 be used to suppress the special meaning of @samp{.} in regexps.) If
426 the element has the form @code{(@var{regexp} @var{mode-function}
427 @var{flag})} and @var{flag} is non-@code{nil}, then after calling
428 @var{mode-function}, Emacs discards the suffix that matched
429 @var{regexp} and searches the list again for another match.
431 @vindex auto-mode-case-fold
432 On GNU/Linux and other systems with case-sensitive file names, Emacs
433 performs a case-sensitive search through @code{auto-mode-alist}; if
434 this search fails, it performs a second case-insensitive search
435 through the alist. To suppress the second search, change the variable
436 @code{auto-mode-case-fold} to @code{nil}. On systems with
437 case-insensitive file names, such as Microsoft Windows, Emacs performs
438 a single case-insensitive search through @code{auto-mode-alist}.
440 @vindex magic-fallback-mode-alist
441 Finally, if Emacs @emph{still} hasn't found a major mode to use, it
442 compares the text at the start of the buffer to the variable
443 @code{magic-fallback-mode-alist}. This variable works like
444 @code{magic-mode-alist}, described above, except that is consulted
445 only after @code{auto-mode-alist}. By default,
446 @code{magic-fallback-mode-alist} contains forms that check for image
447 files, HTML/XML/SGML files, PostScript files, and Unix style Conf
451 If you have changed the major mode of a buffer, you can return to
452 the major mode Emacs would have chosen automatically, by typing
453 @kbd{M-x normal-mode}. This is the same function that
454 @code{find-file} calls to choose the major mode. It also processes
455 the file's @samp{-*-} line or local variables list (if any).
456 @xref{File Variables}.
458 @vindex change-major-mode-with-file-name
459 The commands @kbd{C-x C-w} and @code{set-visited-file-name} change to
460 a new major mode if the new file name implies a mode (@pxref{Saving}).
461 (@kbd{C-x C-s} does this too, if the buffer wasn't visiting a file.)
462 However, this does not happen if the buffer contents specify a major
463 mode, and certain special major modes do not allow the mode to
464 change. You can turn off this mode-changing feature by setting
465 @code{change-major-mode-with-file-name} to @code{nil}.