@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 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
* 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
@code{special} modes, Fundamental mode is used instead. Modes such as
Dired, Rmail, and Buffer List use this feature.
+The function @code{view-buffer} does not enable View mode in buffers
+whose mode-class is special, because such modes usually provide their
+own View-like bindings.
+
The @code{define-derived-mode} macro automatically marks the derived
mode as special if the parent mode is special. Special mode is a
convenient parent for such modes to inherit from; @xref{Basic Major
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
(@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
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
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
@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}.
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
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
@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