X-Git-Url: https://code.delx.au/gnu-emacs/blobdiff_plain/fb6d826c69939c2d016c1b824d4e9bcb53d9e643..85b3eca57a5ae5335c11b157bb481cf8f7a35684:/doc/lispref/modes.texi diff --git a/doc/lispref/modes.texi b/doc/lispref/modes.texi index 3b8550e13b..368d882a4b 100644 --- a/doc/lispref/modes.texi +++ b/doc/lispref/modes.texi @@ -1,6 +1,6 @@ @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 @@ -445,7 +445,8 @@ other packages would interfere with them. 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}. @@ -525,11 +526,12 @@ the buffer based on information in the file name or in the file itself. 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 @@ -543,9 +545,9 @@ If you run @code{normal-mode} interactively, the argument @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 @@ -555,16 +557,17 @@ mode specification error}, followed by the original error message. @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 @@ -749,7 +752,8 @@ The new mode has its own abbrev table, kept in the variable @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 @@ -773,8 +777,9 @@ about the mode's hook, followed by the mode's keymap, at the end of this 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 @@ -794,10 +799,18 @@ if @var{parent} is @code{nil}. (Again, a @code{nil} value is @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: @@ -899,7 +912,7 @@ follow these conventions: they may run the parent's mode hook too early, 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. @@ -907,11 +920,15 @@ 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 @@ -1048,7 +1065,7 @@ to invert the sort order. @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 @@ -1912,7 +1929,8 @@ could have the same effects on the mode line if the value of @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 @@ -1943,11 +1961,11 @@ Its default value displays the buffer name, padded with spaces to at 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 @@ -1956,11 +1974,11 @@ and, if so, which kind. Its value is a string that appears in the mode 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 @@ -1993,6 +2011,21 @@ with the major mode as: @samp{(Shell:run)}. Normally this variable 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 @@ -2511,12 +2544,12 @@ Search-based fontification happens second. 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}. @@ -2563,10 +2596,10 @@ variable. The value assigned to this variable is used, if and when Font 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.