@c -*-texinfo-*-
@c This is part of the GNU Emacs Lisp Reference Manual.
-@c Copyright (C) 1990-1995, 1998-1999, 2001-2012 Free Software Foundation, Inc.
+@c Copyright (C) 1990-1995, 1998-1999, 2001-2013 Free Software
+@c Foundation, Inc.
@c See the file elisp.texi for copying conditions.
-@setfilename ../../info/modes
-@node Modes, Documentation, Keymaps, Top
+@node Modes
@chapter Major and Minor Modes
@cindex mode
hook, but you must write the function to follow the hook's calling
convention.
- By convention, abnormal hook names end in @samp{-functions} or
-@samp{-hooks}. If the variable's name ends in @samp{-function}, then
-its value is just a single function, not a list of functions.
+ By convention, abnormal hook names end in @samp{-functions}. If the
+variable's name ends in @samp{-function}, then its value is just a single
+function, not a list of functions.
@menu
* Running Hooks:: How to run a hook.
* Derived Modes:: Defining a new major mode based on another major
mode.
* Basic Major Modes:: Modes that other modes are often derived from.
-* Mode Hooks:: Hooks run at the end of major mode commands.
+* Mode Hooks:: Hooks run at the end of major mode functions.
* Tabulated List Mode:: Parent mode for buffers containing tabulated data.
* Generic Modes:: Defining a simple major mode that supports
comment syntax and Font Lock mode.
A major mode can also rebind the keys @kbd{M-n}, @kbd{M-p} and
@kbd{M-s}. The bindings for @kbd{M-n} and @kbd{M-p} should normally
-be some kind of ``moving forward and backward,'' but this does not
+be some kind of ``moving forward and backward'', but this does not
necessarily mean cursor motion.
It is legitimate for a major mode to rebind a standard key sequence if
should not be applied to the containing tar file. Similarly, a tiff
image file might just happen to contain a first line that seems to
match the @w{@samp{-*-}} pattern. For these reasons, both these file
-extensions are members of the list @var{inhibit-local-variables-regexps}.
+extensions are members of the list @code{inhibit-local-variables-regexps}.
Add patterns to this list to prevent Emacs searching them for local
variables of any kind (not just mode specifiers).
This function sets the major mode of @var{buffer} to the default value of
@code{major-mode}; if that is @code{nil}, it uses the
current buffer's major mode (if that is suitable). As an exception,
-if @var{buffer}'s name is @samp{*scratch*}, it sets the mode to
+if @var{buffer}'s name is @file{*scratch*}, it sets the mode to
@code{initial-major-mode}.
The low-level primitives for creating buffers do not use this function,
@end defun
@defopt initial-major-mode
-@cindex @samp{*scratch*}
+@cindex @file{*scratch*}
The value of this variable determines the major mode of the initial
-@samp{*scratch*} buffer. The value should be a symbol that is a major
+@file{*scratch*} buffer. The value should be a symbol that is a major
mode command. The default value is @code{lisp-interaction-mode}.
@end defopt
variable @code{major-mode} (@pxref{Major Modes}), which is why every
major mode command needs to set that variable.
-@deffn Command describe-mode
-This function displays the documentation of the current major mode.
+@deffn Command describe-mode &optional buffer
+This command displays the documentation of the current buffer's major
+mode and minor modes. It uses the @code{documentation} function to
+retrieve the documentation strings of the major and minor mode
+commands (@pxref{Accessing Documentation}).
-The @code{describe-mode} function calls the @code{documentation}
-function using the value of @code{major-mode} as an argument. Thus, it
-displays the documentation string of the major mode command.
-(@xref{Accessing Documentation}.)
+If called from Lisp with a non-nil @var{buffer} argument, this
+function displays the documentation for that buffer's major and minor
+modes, rather than those of the current buffer.
@end deffn
@node Derived Modes
Apart from Fundamental mode, there are three major modes that other
major modes commonly derive from: Text mode, Prog mode, and Special
-mode. While Text mode is useful in its own right (e.g. for editing
+mode. While Text mode is useful in its own right (e.g., for editing
files ending in @file{.txt}), Prog mode and Special mode exist mainly to
let other modes derive from them.
As far as possible, new major modes should be derived, either directly
or indirectly, from one of these three modes. One reason is that this
allows users to customize a single mode hook
-(e.g. @code{prog-mode-hook}) for an entire family of relevant modes
-(e.g. all programming language modes).
+(e.g., @code{prog-mode-hook}) for an entire family of relevant modes
+(e.g., all programming language modes).
@deffn Command text-mode
Text mode is a major mode for editing human languages. It defines the
of @code{special} (@pxref{Major Mode Conventions}).
Special mode sets the buffer to read-only. Its keymap defines several
-common bindings, including @kbd{q} for @code{quit-window}, @kbd{z} for
-@code{kill-this-buffer}, and @kbd{g} for @code{revert-buffer}
-(@pxref{Reverting}).
+common bindings, including @kbd{q} for @code{quit-window} and @kbd{g}
+for @code{revert-buffer} (@pxref{Reverting}).
An example of a major mode derived from Special mode is Buffer Menu
-mode, which is used by the @samp{*Buffer List*} buffer. @xref{List
+mode, which is used by the @file{*Buffer List*} buffer. @xref{List
Buffers,,Listing Existing Buffers, emacs, The GNU Emacs Manual}.
@end deffn
When you defined a major mode using @code{define-derived-mode}, it
automatically makes sure these conventions are followed. If you
-define a major mode ``by hand,'' not using @code{define-derived-mode},
+define a major mode ``by hand'', not using @code{define-derived-mode},
use the following functions to handle these conventions automatically.
@defun run-mode-hooks &rest hookvars
@cindex Tabulated List mode
Tabulated List mode is a major mode for displaying tabulated data,
-i.e.@: data consisting of @dfn{entries}, each entry occupying one row of
+i.e., data consisting of @dfn{entries}, each entry occupying one row of
text with its contents divided into columns. Tabulated List mode
provides facilities for pretty-printing rows and columns, and sorting
the rows according to the values in each column. It is derived from
line.
The derived mode should also define a @dfn{listing command}. This,
-not the mode command, is what the user calls (e.g.@: @kbd{M-x
+not the mode command, is what the user calls (e.g., @kbd{M-x
list-processes}). The listing command should create or switch to a
buffer, turn on the derived mode, specify the tabulated data, and
finally call @code{tabulated-list-print} to populate the buffer.
The argument @var{comment-list} is a list in which each element is
either a character, a string of one or two characters, or a cons cell.
A character or a string is set up in the mode's syntax table as a
-``comment starter.'' If the entry is a cons cell, the @sc{car} is set
-up as a ``comment starter'' and the @sc{cdr} as a ``comment ender.''
+``comment starter''. If the entry is a cons cell, the @sc{car} is set
+up as a ``comment starter'' and the @sc{cdr} as a ``comment ender''.
(Use @code{nil} for the latter if you want comments to end at the end
of the line.) Note that the syntax table mechanism has limitations
about what comment starters and enders are actually possible.
@smallexample
@group
-(defun lisp-mode-variables (&optional lisp-syntax keywords-case-insensitive)
- (when lisp-syntax
+(defun lisp-mode-variables (&optional syntax keywords-case-insensitive)
+ (when syntax
(set-syntax-table lisp-mode-syntax-table))
(setq local-abbrev-table lisp-mode-abbrev-table)
@dots{}
Entry to this mode calls the value of `lisp-mode-hook'
if that value is non-nil."
(lisp-mode-variables nil t)
- (set (make-local-variable 'find-tag-default-function) 'lisp-find-tag-default)
- (make-local-variable 'comment-start-skip)
- (setq comment-start-skip
+ (set (make-local-variable 'find-tag-default-function)
+ 'lisp-find-tag-default)
+ (set (make-local-variable 'comment-start-skip)
"\\(\\(^\\|[^\\\\\n]\\)\\(\\\\\\\\\\)*\\)\\(;+\\|#|\\) *")
(setq imenu-case-fold-search t))
@end group
@cindex mode variable
Define a variable whose name ends in @samp{-mode}. We call this the
@dfn{mode variable}. The minor mode command should set this variable.
-The value will be @code{nil} is the mode is disabled, and non-@code{nil}
+The value will be @code{nil} if the mode is disabled, and non-@code{nil}
if the mode is enabled. The variable should be buffer-local if the
minor mode is buffer-local.
The mode command should accept one optional argument. If called
interactively with no prefix argument, it should toggle the mode
-(i.e.@: enable if it is disabled, and disable if it is enabled). If
+(i.e., enable if it is disabled, and disable if it is enabled). If
called interactively with a prefix argument, it should enable the mode
if the argument is positive and disable it otherwise.
-If the mode command is called from Lisp (i.e.@: non-interactively), it
+If the mode command is called from Lisp (i.e., non-interactively), it
should enable the mode if the argument is omitted or @code{nil}; it
should toggle the mode if the argument is the symbol @code{toggle};
otherwise it should treat the argument in the same way as for an
One of the effects of making a minor mode global is that the
@var{mode} variable becomes a customization variable. Toggling it
-through the Custom interface turns the mode on and off, and its value
-can be saved for future Emacs sessions (@pxref{Saving
+through the Customize interface turns the mode on and off, and its
+value can be saved for future Emacs sessions (@pxref{Saving
Customizations,,, emacs, The GNU Emacs Manual}. For the saved
variable to work, you should ensure that the @code{define-minor-mode}
form is evaluated each time Emacs starts; for packages that are not
defined, and any @var{init-value} argument is unused. @var{place}
can be a different named variable (which you must define yourself), or
anything that can be used with the @code{setf} function
-(@pxref{Generalized Variables,,, cl, Common Lisp Extensions}).
+(@pxref{Generalized Variables}).
@var{place} can also be a cons @code{(@var{get} . @var{set})},
where @var{get} is an expression that returns the current state,
and @var{set} is a function of one argument (a state) that sets it.
@end smallexample
@noindent
-This defines a minor mode named ``Hungry mode,'' a command named
+This defines a minor mode named ``Hungry mode'', a command named
@code{hungry-mode} to toggle it, a variable named @code{hungry-mode}
which indicates whether the mode is enabled, and a variable named
@code{hungry-mode-map} which holds the keymap that is active when the
in Fundamental mode.
This defines the customization option @var{global-mode} (@pxref{Customization}),
-which can be toggled in the Custom interface to turn the minor mode on
+which can be toggled in the Customize interface to turn the minor mode on
and off. As with @code{define-minor-mode}, you should ensure that the
@code{define-globalized-minor-mode} form is evaluated each time Emacs
starts, for example by providing a @code{:require} keyword.
A list whose first element is a symbol that is not a keyword specifies
a conditional. Its meaning depends on the value of @var{symbol}. If
@var{symbol} has a non-@code{nil} value, the second element,
-@var{then}, is processed recursively as a mode line element.
+@var{then}, is processed recursively as a mode line construct.
Otherwise, the third element, @var{else}, is processed recursively.
-You may omit @var{else}; then the mode line element displays nothing
+You may omit @var{else}; then the mode line construct displays nothing
if the value of @var{symbol} is @code{nil} or void.
@item (@var{width} @var{rest}@dots{})
on the process status, and whether narrowing is in effect.
@end defopt
-@defopt mode-line-remote
+@defvar mode-line-remote
This variable is used to show whether @code{default-directory} for the
current buffer is remote.
-@end defopt
+@end defvar
-@defopt mode-line-client
+@defvar mode-line-client
This variable is used to identify @code{emacsclient} frames.
-@end defopt
+@end defvar
The following three variables are used in @code{mode-line-modes}:
This buffer-local variable contains the mode line information on process
status in modes used for communicating with subprocesses. It is
displayed immediately following the major mode name, with no intervening
-space. For example, its value in the @samp{*shell*} buffer is
+space. For example, its value in the @file{*shell*} buffer is
@code{(":%s")}, which allows the shell to display its status along
with the major mode as: @samp{(Shell:run)}. Normally this variable
is @code{nil}.
@subsection @code{%}-Constructs in the Mode Line
Strings used as mode line constructs can use certain
-@code{%}-constructs to substitute various kinds of data. Here is a
-list of the defined @code{%}-constructs, and what they mean. In any
-construct except @samp{%%}, you can add a decimal integer after the
-@samp{%} to specify a minimum field width. If the width is less, the
-field is padded with spaces to the right.
+@code{%}-constructs to substitute various kinds of data. The
+following is a list of the defined @code{%}-constructs, and what they
+mean.
+
+ In any construct except @samp{%%}, you can add a decimal integer
+after the @samp{%} to specify a minimum field width. If the width is
+less, the field is padded to that width. Purely numeric constructs
+(@samp{c}, @samp{i}, @samp{I}, and @samp{l}) are padded by inserting
+spaces to the left, and others are padded by inserting spaces to the
+right.
@table @code
@item %b
choose one of them and move point to it. Major modes can add a menu
bar item to use Imenu using @code{imenu-add-to-menubar}.
-@defun imenu-add-to-menubar name
+@deffn Command imenu-add-to-menubar name
This function defines a local menu bar item named @var{name}
to run Imenu.
-@end defun
+@end deffn
The user-level commands for using Imenu are described in the Emacs
Manual (@pxref{Imenu,, Imenu, emacs, the Emacs Manual}). This section
@item font-lock-comment-delimiter-face
@vindex font-lock-comment-delimiter-face
-for comments delimiters, like @samp{/*} and @samp{*/} in C. On most
+for comments delimiters, like @samp{/*} and @samp{*/} in C@. On most
terminals, this inherits from @code{font-lock-comment-face}.
@item font-lock-type-face
This variable is semi-obsolete; we usually recommend setting
@code{syntax-begin-function} instead. One of its uses is to tune the
-behavior of syntactic fontification, e.g.@: to ensure that different
+behavior of syntactic fontification, e.g., to ensure that different
kinds of strings or comments are highlighted differently.
The specified function is called with no arguments. It should leave
of Lisp sexps and adapts it to non-Lisp languages.
@menu
-* SMIE:: A simple minded indentation engine
+* SMIE:: A simple minded indentation engine.
@end menu
@node SMIE
resorting to some special tricks (@pxref{SMIE Tricks}).
@menu
-* SMIE setup:: SMIE setup and features
-* Operator Precedence Grammars:: A very simple parsing technique
-* SMIE Grammar:: Defining the grammar of a language
-* SMIE Lexer:: Defining tokens
-* SMIE Tricks:: Working around the parser's limitations
-* SMIE Indentation:: Specifying indentation rules
-* SMIE Indentation Helpers:: Helper functions for indentation rules
-* SMIE Indentation Example:: Sample indentation rules
+* SMIE setup:: SMIE setup and features.
+* Operator Precedence Grammars:: A very simple parsing technique.
+* SMIE Grammar:: Defining the grammar of a language.
+* SMIE Lexer:: Defining tokens.
+* SMIE Tricks:: Working around the parser's limitations.
+* SMIE Indentation:: Specifying indentation rules.
+* SMIE Indentation Helpers:: Helper functions for indentation rules.
+* SMIE Indentation Example:: Sample indentation rules.
@end menu
@node SMIE setup
@item
A token can be an @code{opener} (something similar to an open-paren),
a @code{closer} (like a close-paren), or @code{neither} of the two
-(e.g. an infix operator, or an inner token like @code{"else"}).
+(e.g., an infix operator, or an inner token like @code{"else"}).
@end itemize
Precedence conflicts can be resolved via @var{resolvers}, which
restructure the grammar. Do not despair: while the parser cannot be
made more clever, you can make the lexer as smart as you want. So, the
solution is then to look at the tokens involved in the conflict and to
-split one of those tokens into 2 (or more) different tokens. E.g. if
+split one of those tokens into 2 (or more) different tokens. E.g., if
the grammar needs to distinguish between two incompatible uses of the
token @code{"begin"}, make the lexer return different tokens (say
@code{"begin-fun"} and @code{"begin-plain"}) depending on which kind of
@end defun
@defun smie-rule-sibling-p
-Return non-nil if the current token's parent is actually a sibling.
-This is the case for example when the parent of a @code{","} is just the
-previous @code{","}.
+Return non-@code{nil} if the current token's parent is actually a
+sibling. This is the case for example when the parent of a @code{","}
+is just the previous @code{","}.
@end defun
@defun smie-rule-parent &optional offset
By @emph{separator}, we mean here a token whose sole purpose is to
separate various elements within some enclosing syntactic construct, and
-which does not have any semantic significance in itself (i.e. it would
+which does not have any semantic significance in itself (i.e., it would
typically not exist as a node in an abstract syntax tree).
Such a token is expected to have an associative syntax and be closely
Here @var{desktop-buffer-misc} is the value returned by the function
optionally bound to @code{desktop-save-buffer}.
@end defvar
-