Commit dc95a8b0 authored by Chong Yidong's avatar Chong Yidong
Browse files

More updates to Modes chapter of Emacs manual.

* doc/emacs/modes.texi (Major Modes): Move major-mode variable doc here from
Choosing Modes.  Document describe-mode.  Document prog-mode-hook
and text-mode-hook.  Add example of using hooks.
(Minor Modes): Document behavior of mode command calls from Lisp.
Note that setting the mode variable using Customize will DTRT.
(Choosing Modes): Add example of setting a minor mode using a
local variable.
parent 1305621b
...@@ -170,7 +170,7 @@ entering.texi cyd ...@@ -170,7 +170,7 @@ entering.texi cyd
files.texi cyd files.texi cyd
fixit.texi fixit.texi
fortran-xtra.texi fortran-xtra.texi
frames.texi frames.texi cyd
glossary.texi glossary.texi
help.texi cyd help.texi cyd
indent.texi indent.texi
...@@ -182,6 +182,7 @@ major.texi ...@@ -182,6 +182,7 @@ major.texi
mark.texi cyd mark.texi cyd
mini.texi mini.texi
misc.texi misc.texi
modes.texi cyd
msdog.texi msdog.texi
msdog-xtra.texi msdog-xtra.texi
mule.texi mule.texi
...@@ -197,7 +198,7 @@ text.texi ...@@ -197,7 +198,7 @@ text.texi
trouble.texi trouble.texi
vc-xtra.texi vc-xtra.texi
vc1-xtra.texi vc1-xtra.texi
windows.texi windows.texi cyd
xresources.texi xresources.texi
** Check the Lisp manual. ** Check the Lisp manual.
......
2011-11-28 Chong Yidong <cyd@gnu.org>
* modes.texi (Major Modes): Move major-mode variable doc here from
Choosing Modes. Document describe-mode. Document prog-mode-hook
and text-mode-hook. Add example of using hooks.
(Minor Modes): Document behavior of mode command calls from Lisp.
Note that setting the mode variable using Customize will DTRT.
(Choosing Modes): Add example of setting a minor mode using a
local variable.
2011-11-27 Chong Yidong <cyd@gnu.org> 2011-11-27 Chong Yidong <cyd@gnu.org>
* frames.texi (Creating Frames): Move frame parameter example to * frames.texi (Creating Frames): Move frame parameter example to
......
...@@ -3,11 +3,11 @@ ...@@ -3,11 +3,11 @@
@c Free Software Foundation, Inc. @c Free Software Foundation, Inc.
@c See file emacs.texi for copying conditions. @c See file emacs.texi for copying conditions.
@node Modes, Indentation, International, Top @node Modes, Indentation, International, Top
@chapter Editing Modes @chapter Major and Minor Modes
Emacs contains many @dfn{editing modes}, each of which alters its Emacs contains many @dfn{editing modes} that alter its basic
basic behavior in useful ways. These are divided into @dfn{major behavior in useful ways. These are divided into @dfn{major modes} and
modes} and @dfn{minor modes}. @dfn{minor modes}.
Major modes provide specialized facilities for working on a Major modes provide specialized facilities for working on a
particular file type, such as a C source file (@pxref{Programs}), or a particular file type, such as a C source file (@pxref{Programs}), or a
...@@ -38,15 +38,8 @@ one another, and of the selected major mode. ...@@ -38,15 +38,8 @@ one another, and of the selected major mode.
Every buffer possesses a major mode, which determines the editing Every buffer possesses a major mode, which determines the editing
behavior of Emacs while that buffer is current. The mode line behavior of Emacs while that buffer is current. The mode line
normally shows the name of the current major mode, in parentheses. normally shows the name of the current major mode, in parentheses
@xref{Mode Line}. (@pxref{Mode Line}).
Usually, the major mode is automatically set by Emacs, when you
first visit a file or create a buffer. @xref{Choosing Modes}. You
can explicitly select a new major mode by using an @kbd{M-x} command.
Take the name of the mode and add @code{-mode} to get the name of the
command to select that mode. Thus, you can enter Lisp mode with
@kbd{M-x lisp-mode}.
The least specialized major mode is called @dfn{Fundamental mode}. The least specialized major mode is called @dfn{Fundamental mode}.
This mode has no mode-specific redefinitions or variable settings, so This mode has no mode-specific redefinitions or variable settings, so
...@@ -55,73 +48,140 @@ user option variable is in its default state. ...@@ -55,73 +48,140 @@ user option variable is in its default state.
For editing text of a specific type that Emacs knows about, such as For editing text of a specific type that Emacs knows about, such as
Lisp code or English text, you typically use a more specialized major Lisp code or English text, you typically use a more specialized major
mode, such as Lisp mode or Text mode. Such major modes change the mode, such as Lisp mode or Text mode. Most major modes fall into
meanings of some keys to become more specifically adapted to the three major groups. The first group contains modes for normal text,
language being edited. The ones that are commonly changed are either plain or with mark-up. It includes Text mode, HTML mode, SGML
@key{TAB}, @key{DEL}, and @kbd{C-j}. The prefix key @kbd{C-c} mode, @TeX{} mode and Outline mode. The second group contains modes
normally contains mode-specific commands. In addition, the commands for specific programming languages. These include Lisp mode (which
which handle comments use the mode to determine how comments are to be has several variants), C mode, Fortran mode, and others. The third
delimited. Many major modes redefine the syntactical properties of group consists of major modes that are not associated directly with
characters appearing in the buffer. files; they are used in buffers created for specific purposes by
Emacs, such as Dired mode for buffers made by Dired (@pxref{Dired}),
The major modes fall into three major groups. The first group Message mode for buffers made by @kbd{C-x m} (@pxref{Sending Mail}),
contains modes for normal text, either plain or with mark-up. It and Shell mode for buffers used to communicate with an inferior shell
includes Text mode, HTML mode, SGML mode, @TeX{} mode and Outline process (@pxref{Interactive Shell}).
mode. The second group contains modes for specific programming
languages. These include Lisp mode (which has several variants), C Usually, the major mode is automatically set by Emacs, when you
mode, Fortran mode, and others. The remaining major modes are not first visit a file or create a buffer (@pxref{Choosing Modes}). You
intended for use on users' files; they are used in buffers created for can explicitly select a new major mode by using an @kbd{M-x} command.
specific purposes by Emacs, such as Dired mode for buffers made by Take the name of the mode and add @code{-mode} to get the name of the
Dired (@pxref{Dired}), Message mode for buffers made by @kbd{C-x m} command to select that mode. Thus, you can enter Lisp mode with
(@pxref{Sending Mail}), and Shell mode for buffers used for @kbd{M-x lisp-mode}.
communicating with an inferior shell process (@pxref{Interactive
Shell}). @vindex major-mode
The value of the buffer-local variable @code{major-mode} is a symbol
Most programming-language major modes specify that only blank lines with the same name as the major mode command (e.g. @code{lisp-mode}).
separate paragraphs. This is to make the paragraph commands useful. This variable is set automatically; you should not change it yourself.
(@xref{Paragraphs}.) They also cause Auto Fill mode to use the
definition of @key{TAB} to indent the new lines it creates. This is The default value of @code{major-mode} determines the major mode to
because most lines in a program are usually indented use for files that do not specify a major mode, and for new buffers
(@pxref{Indentation}). created with @kbd{C-x b}. Normally, this default value is the symbol
@code{fundamental-mode}, which specifies Fundamental mode. You can
change this default value via the Customization interface (@pxref{Easy
Customization}), or by adding a line like this to your init file
(@pxref{Init File}):
@smallexample
(setq-default major-mode 'text-mode)
@end smallexample
@noindent
If the default value of @code{major-mode} is @code{nil}, the major
mode is taken from the previously current buffer.
Specialized major modes often change the meanings of certain keys to
do something more suitable for the mode. For instance, programming
language modes bind @key{TAB} to indent the current line according to
the rules of the language (@pxref{Indentation}). The keys that are
commonly changed are @key{TAB}, @key{DEL}, and @kbd{C-j}. Many modes
also define special commands of their own, usually bound in the prefix
key @kbd{C-c}. Major modes can also alter user options and variables;
for instance, programming language modes typicaly set a buffer-local
value for the variable @code{comment-start}, which determines how
source code comments are delimited (@pxref{Comments}).
@findex describe-mode
@kindex C-h m
To view the documentation for the current major mode, including a
list of its key bindings, type @code{C-h m} (@code{describe-mode}).
@cindex mode hook
@vindex text-mode-hook
@vindex prog-mode-hook
Every major mode, apart from Fundamental mode, defines a @dfn{mode
hook}, a customizable list of Lisp functions to run each time the mode
is enabled in a buffer. @xref{Hooks}, for more information about
hooks. Each mode hook is named after its major mode, e.g. Fortran
mode has @code{fortran-mode-hook}. Furthermore, all text-based major
modes run @code{text-mode-hook}, and all programming language modes
run @code{prog-mode-hook}, prior to running their own mode hooks.
Mode hooks are commonly used to enable minor modes (@pxref{Minor
Modes}). For example, you can put the following lines in your init
file to enable Flyspell minor mode in all text-based major modes
(@pxref{Spelling}), and Eldoc minor mode in Emacs Lisp mode
(@pxref{Lisp Doc}):
@example
(add-hook 'text-mode-hook 'flyspell-mode)
(add-hook 'emacs-lisp-mode-hook 'eldoc-mode)
@end example
@node Minor Modes @node Minor Modes
@section Minor Modes @section Minor Modes
@cindex minor modes @cindex minor modes
@cindex mode, minor @cindex mode, minor
A minor mode is an optional editing modes that alters the behavior A minor mode is an optional editing mode that alters the behavior of
of Emacs in some well-defined way. Unlike major modes, any number of Emacs in some well-defined way. Unlike major modes, any number of
minor modes can be in effect at any time. Some minor modes are minor modes can be in effect at any time. Some minor modes are
@dfn{buffer-local}: they apply only to the current buffer, so you can @dfn{buffer-local}, and can be turned on (enabled) in certain buffers
enable the mode in certain buffers and not others. Other minor modes and off (disabled) in others. Other minor modes are @dfn{global}:
are @dfn{global}: while enabled, they affect everything you do in the while enabled, they affect everything you do in the Emacs session, in
Emacs session, in all buffers. Some global minor modes are enabled by all buffers. Most minor modes are disabled by default, but a few are
default. enabled by default.
Most minor modes say in the mode line when they are enabled, just Most buffer-local minor modes say in the mode line when they are
after the major mode indicator. For example, @samp{Fill} in the mode enabled, just after the major mode indicator. For example,
line means that Auto Fill mode is enabled. @xref{Mode Line}. @samp{Fill} in the mode line means that Auto Fill mode is enabled.
@xref{Mode Line}.
Each minor mode is associated with a command, called the @dfn{mode
command}, which turns it on or off. The name of this command consists @cindex mode commands for minor modes
of the name of the minor mode, followed by @samp{-mode}; for instance, Like major modes, each minor mode is associated with a @dfn{mode
the mode command for Auto Fill mode is @code{auto-fill-mode}. Calling command}, whose name consists of the mode name followed by
the minor mode command with no prefix argument @dfn{toggles} the mode, @samp{-mode}. For instance, the mode command for Auto Fill mode is
turning it on if it was off, and off if it was on. A positive @code{auto-fill-mode}. But unlike a major mode command, which simply
argument always turns the mode on, and a zero or negative argument enables the mode, the mode command for a minor mode can either enable
always turns it off. Mode commands are usually invoked with or disable it:
@kbd{M-x}, but you can bind keys to them if you wish (@pxref{Key
Bindings}). @itemize
@item
If you invoke the mode command directly with no prefix argument
(either via @kbd{M-x}, or by binding it to a key and typing that key;
@pxref{Key Bindings}), that @dfn{toggles} the minor mode. The minor
mode is turned on if it was off, and turned off if it was on.
@item
If you invoke the mode command with a prefix argument, the minor mode
is unconditionally turned off if that argument is zero or negative;
otherwise, it is unconditionally turned on.
@item
If the mode command is called via Lisp, the minor mode is
unconditionally turned on if the argument is omitted or @code{nil}.
This makes it easy to turn on a minor mode from a major mode's mode
hook (@pxref{Major Modes}). A non-@code{nil} argument is handled like
an interactive prefix argument, as described above.
@end itemize
Most minor modes also have a @dfn{mode variable}, with the same name Most minor modes also have a @dfn{mode variable}, with the same name
as the mode command. Its value is non-@code{nil} if the mode is as the mode command. Its value is non-@code{nil} if the mode is
enabled, and @code{nil} if it is disabled. In some minor modes---but enabled, and @code{nil} if it is disabled. In general, you should not
not all---the value of the variable alone determines whether the mode try to enable or disable the mode by changing the value of the mode
is active: the mode command works simply by setting the variable, and variable directly in Lisp; you should run the mode command instead.
changing the value of the variable has the same effect as calling the However, setting the mode variable through the Customize interface
mode command. Because not all minor modes work this way, we recommend (@pxref{Easy Customization}) will always properly enable or disable
that you avoid changing the mode variables directly; use the mode the mode, since Customize automatically runs the mode command for you.
commands instead.
The following is a list of some buffer-local minor modes: The following is a list of some buffer-local minor modes:
...@@ -189,11 +249,8 @@ Visual Line mode performs ``word wrapping'', causing long lines to be ...@@ -189,11 +249,8 @@ Visual Line mode performs ``word wrapping'', causing long lines to be
wrapped at word boundaries. @xref{Visual Line Mode}. wrapped at word boundaries. @xref{Visual Line Mode}.
@end itemize @end itemize
Here are some useful global minor modes. Since Line Number mode and @noindent
Transient Mark mode can be enabled or disabled just by setting the And here are some useful global minor modes:
value of the minor mode variable, you @emph{can} set them differently
for particular buffers, by explicitly making the corresponding
variable local in those buffers. @xref{Locals}.
@itemize @bullet @itemize @bullet
@item @item
...@@ -261,22 +318,27 @@ text may appear on the line as well. For example, ...@@ -261,22 +318,27 @@ text may appear on the line as well. For example,
@noindent @noindent
tells Emacs to use Lisp mode. Note how the semicolon is used to make tells Emacs to use Lisp mode. Note how the semicolon is used to make
Lisp treat this line as a comment. Alternatively, you could write Lisp treat this line as a comment. You could equivalently write
@example @example
; -*- mode: Lisp;-*- ; -*- mode: Lisp;-*-
@end example @end example
@noindent @noindent
The latter format allows you to specify local variables as well, like You can also use file-local variables to specify buffer-local minor
this: modes, by using @code{eval} specifications. For example, this first
nonblank line puts the buffer in Lisp mode and enables Auto-Fill mode:
@example @example
; -*- mode: Lisp; tab-width: 4; -*- ; -*- mode: Lisp; eval: (auto-fill-mode 1); -*-
@end example @end example
If a file variable specifies a buffer-local minor mode, Emacs @noindent
enables that minor mode in the buffer. Note, however, that it is usually inappropriate to enable minor modes
this way, since most minor modes represent individual user
preferences. If you personally want to use a minor mode for a
particular file type, it is better to enable the minor mode via a
major mode hook (@pxref{Major Modes}).
@vindex interpreter-mode-alist @vindex interpreter-mode-alist
Second, if there is no file variable specifying a major mode, Emacs Second, if there is no file variable specifying a major mode, Emacs
...@@ -310,9 +372,9 @@ elements of the form ...@@ -310,9 +372,9 @@ elements of the form
@noindent @noindent
where @var{regexp} is a regular expression (@pxref{Regexps}), and where @var{regexp} is a regular expression (@pxref{Regexps}), and
@var{mode-function} is a Lisp function that toggles a major mode. If @var{mode-function} is a major mode command. If the text at the
the text at the beginning of the file matches @var{regexp}, Emacs beginning of the file matches @var{regexp}, Emacs chooses the major
chooses the major mode specified by @var{mode-function}. mode specified by @var{mode-function}.
Alternatively, an element of @code{magic-mode-alist} may have the form Alternatively, an element of @code{magic-mode-alist} may have the form
...@@ -323,7 +385,7 @@ Alternatively, an element of @code{magic-mode-alist} may have the form ...@@ -323,7 +385,7 @@ Alternatively, an element of @code{magic-mode-alist} may have the form
@noindent @noindent
where @var{match-function} is a Lisp function that is called at the where @var{match-function} is a Lisp function that is called at the
beginning of the buffer; if the function returns non-@code{nil}, Emacs beginning of the buffer; if the function returns non-@code{nil}, Emacs
set the major mode wit @var{mode-function}. set the major mode with @var{mode-function}.
Fourth---if Emacs still hasn't found a suitable major mode---it Fourth---if Emacs still hasn't found a suitable major mode---it
looks at the file's name. The correspondence between file names and looks at the file's name. The correspondence between file names and
...@@ -370,29 +432,6 @@ only after @code{auto-mode-alist}. By default, ...@@ -370,29 +432,6 @@ only after @code{auto-mode-alist}. By default,
@code{magic-fallback-mode-alist} contains forms that check for image @code{magic-fallback-mode-alist} contains forms that check for image
files, HTML/XML/SGML files, and PostScript files. files, HTML/XML/SGML files, and PostScript files.
@vindex major-mode
Once a major mode is chosen, Emacs sets the value of the variable
@code{major-mode} to the symbol for that major mode (e.g.,
@code{text-mode} for Text mode). This is a per-buffer variable
(@pxref{Locals}); its buffer-local value is set automatically, and you
should not change it yourself.
The default value of @code{major-mode} determines the major mode to
use for files that do not specify a major mode, and for new buffers
created with @kbd{C-x b}. Normally, this default value is the symbol
@code{fundamental-mode}, which specifies Fundamental mode. You can
change it via the Customization interface (@pxref{Easy
Customization}), or by adding a line like this to your init file
(@pxref{Init File}):
@smallexample
(setq-default major-mode 'text-mode)
@end smallexample
@noindent
If the default value of @code{major-mode} is @code{nil}, the major
mode is taken from the previously current buffer.
@findex normal-mode @findex normal-mode
If you have changed the major mode of a buffer, you can return to If you have changed the major mode of a buffer, you can return to
the major mode Emacs would have chosen automatically, by typing the major mode Emacs would have chosen automatically, by typing
......
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment