@c -*-texinfo-*-
@c This is part of the GNU Emacs Lisp Reference Manual.
-@c Copyright (C) 1990-1995, 1998-1999, 2001-2015 Free Software
+@c Copyright (C) 1990-1995, 1998-1999, 2001-2016 Free Software
@c Foundation, Inc.
@c See the file elisp.texi for copying conditions.
@node Modes
Each major mode should have a normal @dfn{mode hook} named
@code{@var{modename}-mode-hook}. The very last thing the major mode command
should do is to call @code{run-mode-hooks}. This runs the normal
-hook @code{change-major-mode-after-body-hook}, the mode hook,
+hook @code{change-major-mode-after-body-hook}, the mode hook, the
+function @code{hack-local-variables} (when the buffer is visiting a file),
and then the normal hook @code{after-change-major-mode-hook}.
@xref{Mode Hooks}.
It also processes local variables specified in the file text.
@deffn Command normal-mode &optional find-file
-This function establishes the proper major mode and buffer-local variable
-bindings for the current buffer. First it calls @code{set-auto-mode}
-(see below), then it runs @code{hack-local-variables} to parse, and
-bind or evaluate as appropriate, the file's local variables
-(@pxref{File Local Variables}).
+This function establishes the proper major mode and buffer-local
+variable bindings for the current buffer. It calls
+@code{set-auto-mode} (see below). As from Emacs 25.2, it no longer
+runs @code{hack-local-variables}, this now being done in
+@code{run-mode-hooks} at the initialization of major modes
+(@pxref{Mode Hooks}).
If the @var{find-file} argument to @code{normal-mode} is non-@code{nil},
@code{normal-mode} assumes that the @code{find-file} function is calling
@var{find-file} is normally @code{nil}. In this case,
@code{normal-mode} unconditionally processes any file local variables.
-The function calls @code{set-auto-mode} to choose a major mode. If this
-does not specify a mode, the buffer stays in the major mode determined
-by the default value of @code{major-mode} (see below).
+The function calls @code{set-auto-mode} to choose and set a major
+mode. If this does not specify a mode, the buffer stays in the major
+mode determined by the default value of @code{major-mode} (see below).
@cindex file mode specification error
@code{normal-mode} uses @code{condition-case} around the call to the
@defun set-auto-mode &optional keep-mode-if-same
@cindex visited file mode
- This function selects the major mode that is appropriate for the
-current buffer. It bases its decision (in order of precedence) on the
-@w{@samp{-*-}} line, on any @samp{mode:} local variable near the end of
-a file, on the @w{@samp{#!}} line (using @code{interpreter-mode-alist}),
-on the text at the beginning of the buffer (using
-@code{magic-mode-alist}), and finally on the visited file name (using
-@code{auto-mode-alist}). @xref{Choosing Modes, , How Major Modes are
-Chosen, emacs, The GNU Emacs Manual}. If @code{enable-local-variables}
-is @code{nil}, @code{set-auto-mode} does not check the @w{@samp{-*-}}
-line, or near the end of the file, for any mode tag.
+ This function selects and sets the major mode that is appropriate
+for the current buffer. It bases its decision (in order of
+precedence) on the @w{@samp{-*-}} line, on any @samp{mode:} local
+variable near the end of a file, on the @w{@samp{#!}} line (using
+@code{interpreter-mode-alist}), on the text at the beginning of the
+buffer (using @code{magic-mode-alist}), and finally on the visited
+file name (using @code{auto-mode-alist}). @xref{Choosing Modes, , How
+Major Modes are Chosen, emacs, The GNU Emacs Manual}. If
+@code{enable-local-variables} is @code{nil}, @code{set-auto-mode} does
+not check the @w{@samp{-*-}} line, or near the end of the file, for
+any mode tag.
@vindex inhibit-local-variables-regexps
There are some file types where it is not appropriate to scan the file
@item
The new mode has its own mode hook, @code{@var{variant}-hook}. It
runs this hook, after running the hooks of its ancestor modes, with
-@code{run-mode-hooks}, as the last thing it does. @xref{Mode Hooks}.
+@code{run-mode-hooks}, as the last thing it does, apart from running
+any @code{:after-hook} form it may have. @xref{Mode Hooks}.
@end itemize
In addition, you can specify how to override other aspects of
documentation string. If you omit @var{docstring},
@code{define-derived-mode} generates a documentation string.
-The @var{keyword-args} are pairs of keywords and values. The values
-are evaluated. The following keywords are currently supported:
+The @var{keyword-args} are pairs of keywords and values. The values,
+except for @code{:after-hook}'s, are evaluated. The following
+keywords are currently supported:
@table @code
@item :syntax-table
@item :group
If this is specified, the value should be the customization group for
-this mode. (Not all major modes have one.) Only the (still
-experimental and unadvertised) command @code{customize-mode} currently
-uses this. @code{define-derived-mode} does @emph{not} automatically
-define the specified customization group.
+this mode. (Not all major modes have one.) The command
+@code{customize-mode} uses this. @code{define-derived-mode} does
+@emph{not} automatically define the specified customization group.
+
+@item :after-hook
+This optional keyword specifies a single Lisp form to evaluate as the
+final act of the mode function, after the mode hooks have been run.
+It should not be quoted. Since the form might be evaluated after the
+mode function has terminated, it should not access any element of the
+mode function's local state. An @code{:after-hook} form is useful for
+setting up aspects of the mode which depend on the user's settings,
+which in turn may have been changed in a mode hook.
@end table
Here is a hypothetical example:
or fail to run @code{after-change-major-mode-hook}. If you encounter
such a major mode, please correct it to follow these conventions.
- When you defined a major mode using @code{define-derived-mode}, it
+ When you define 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},
use the following functions to handle these conventions automatically.
@defun run-mode-hooks &rest hookvars
Major modes should run their mode hook using this function. It is
similar to @code{run-hooks} (@pxref{Hooks}), but it also runs
-@code{change-major-mode-after-body-hook} and
-@code{after-change-major-mode-hook}.
+@code{change-major-mode-after-body-hook}, @code{hack-local-variables}
+(when the buffer is visiting a file) (@pxref{File Local Variables}),
+and @code{after-change-major-mode-hook}. The last thing it does is to
+evaluate any @code{:after-hook} forms declared by parent modes
+(@pxref{Derived Modes}).
When this function is called during the execution of a
-@code{delay-mode-hooks} form, it does not run the hooks immediately.
+@code{delay-mode-hooks} form, it does not run the hooks or
+@code{hack-local-variables} or evaluate the forms immediately.
Instead, it arranges for the next call to @code{run-mode-hooks} to run
them.
@end defun
@defun tabulated-list-init-header
This function computes and sets @code{header-line-format} for the
Tabulated List buffer (@pxref{Header Lines}), and assigns a keymap to
-the header line to allow sort entries by clicking on column headers.
+the header line to allow sorting entries by clicking on column headers.
Modes derived from Tabulated List mode should call this after setting
the above variables (in particular, only after setting
@code{mode-line-format} is changed to use them. However, various parts
of Emacs set these variables on the understanding that they will control
parts of the mode line; therefore, practically speaking, it is essential
-for the mode line to use them.
+for the mode line to use them. Also see
+@ref{Optional Mode Line,,, emacs, The GNU Emacs Manual}.
@defvar mode-line-mule-info
This variable holds the value of the mode line construct that displays
least 12 columns.
@end defvar
-@defopt mode-line-position
+@defvar mode-line-position
This variable indicates the position in the buffer. Its default value
displays the buffer percentage and, optionally, the buffer size, the
line number and the column number.
-@end defopt
+@end defvar
@defvar vc-mode
The variable @code{vc-mode}, buffer-local in each buffer, records
line, or @code{nil} for no version control.
@end defvar
-@defopt mode-line-modes
+@defvar mode-line-modes
This variable displays the buffer's major and minor modes. Its
default value also displays the recursive editing level, information
on the process status, and whether narrowing is in effect.
-@end defopt
+@end defvar
@defvar mode-line-remote
This variable is used to show whether @code{default-directory} for the
is @code{nil}.
@end defvar
+@defvar mode-line-front-space
+This variable is displayed at the front of the mode line. By default,
+this construct is displayed right at the beginning of the mode line,
+except that if there is a memory-full message, it is displayed first.
+@end defvar
+
+@defvar mode-line-end-spaces
+This variable is displayed at the end of the mode line.
+@end defvar
+
+@defvar mode-line-misc-info
+Mode line construct for miscellaneous information. By default, this
+shows the information specified by @code{global-mode-string}.
+@end defvar
+
@defvar minor-mode-alist
@anchor{Definition of minor-mode-alist}
This variable holds an association list whose elements specify how the
The Font Lock functionality is based on several basic functions.
Each of these calls the function specified by the corresponding
-variable. This indirection allows major modes to modify the way
-fontification works in the buffers of that mode, and even use the Font
-Lock mechanisms for features that have nothing to do with
+variable. This indirection allows major and minor modes to modify the
+way fontification works in the buffers of that mode, and even use the
+Font Lock mechanisms for features that have nothing to do with
fontification. (This is why the description below says ``should''
-when it describes what the functions do: the major mode can customize
-the values of the corresponding variables to do something entirely
+when it describes what the functions do: the mode can customize the
+values of the corresponding variables to do something entirely
different.) The variables mentioned below are described in @ref{Other
Font Lock Variables}.
Lock mode is enabled, to set all the other variables.
@defvar font-lock-defaults
-This variable is set by major modes to specify how to fontify text in
-that mode. It automatically becomes buffer-local when set. If its
-value is @code{nil}, Font Lock mode does no highlighting, and you can
-use the @samp{Faces} menu (under @samp{Edit} and then @samp{Text
+This variable is set by modes to specify how to fontify text in that
+mode. It automatically becomes buffer-local when set. If its value
+is @code{nil}, Font Lock mode does no highlighting, and you can use
+the @samp{Faces} menu (under @samp{Edit} and then @samp{Text
Properties} in the menu bar) to assign faces explicitly to text in the
buffer.