Since all global names are in the same name space, all the global
variables, constants, and functions that are part of the mode should
have names that start with the major mode name (or with an abbreviation
-of it if the name is long). @xref{Style Tips}.
+of it if the name is long). @xref{Coding Conventions}.
@item
@cindex keymaps in modes
@code{@var{modename}-mode-map}. Normally the library that defines the
mode sets this variable.
+@xref{Tips for Defining}, for advice about how to write the code to set
+up the mode's keymap variable.
+
+@item
+The key sequences bound in a major mode keymap should usually start with
+@kbd{C-c}, followed by a control-character, a digit, or @kbd{@{},
+@kbd{@}}, @kbd{<}, @kbd{>}, @kbd{:} or @kbd{;}. The other punctuation
+characters are reserved for minor modes, and ordinary letters are
+reserved for users.
+
+It is reasonable for a major mode to rebind a key sequence with a
+standard meaning, if it implements a command that does ``the same job''
+in a way that fits the major mode better. For example, a major mode for
+editing a programming language might redefine @kbd{C-M-a} to ``move to
+the beginning of a function'' in a way that works better for that
+language.
+
+Major modes such as Dired or Rmail that do not allow self-insertion of
+text can reasonably redefine letters and other printing characters as
+editing commands. Dired and Rmail both do this.
+
@item
@cindex syntax tables in modes
The mode may have its own syntax table or may share one with other
a variable named @code{@var{modename}-mode-syntax-table}. @xref{Syntax
Tables}.
+@item
+If the mode handles a language that has a syntax for comments, it should
+set the variables that define the comment syntax. @xref{Options for
+Comments,, Options Controlling Comments, emacs, The GNU Emacs Manual}.
+
@item
@cindex abbrev tables in modes
The mode may have its own abbrev table or may share one with other
a variable named @code{@var{modename}-mode-abbrev-table}. @xref{Abbrev
Tables}.
+@item
+@vindex font-lock-defaults
+The mode should specify how to do highlighting for Font Lock mode, by
+setting up a buffer-local value for the variable
+@code{font-lock-defaults}.
+
+@item
+@vindex imenu-generic-expression
+@vindex imenu-create-index-function
+The mode should specify how Imenu should find the definitions or
+sections of a buffer, by setting up a buffer-local value for the
+variable @code{imenu-generic-expression} or
+@code{imenu-create-index-function}.
+
@item
Use @code{defvar} to set mode-related variables, so that they are not
reinitialized if they already have a value. (Such reinitialization
Each major mode should have a @dfn{mode hook} named
@code{@var{modename}-mode-hook}. The major mode command should run that
hook, with @code{run-hooks}, as the very last thing it
-does. @xref{Hooks}.
+does. @xref{Hooks}.
@item
The major mode command may also run the hooks of some more basic modes.
@smallexample
@group
(make-local-variable 'paragraph-start)
+ ;; @r{Having @samp{^} is not clean, but @code{page-delimiter}}
+ ;; @r{has them too, and removing those is a pain.}
(setq paragraph-start (concat "^$\\|" page-delimiter))
@dots{}
@end group
@end deffn
@deffn Command normal-mode &optional find-file
- This function establishes the proper major mode and local variable
+This function establishes the proper major mode and local variable
bindings for the current buffer. First it calls @code{set-auto-mode},
then it runs @code{hack-local-variables} to parse, and bind or
evaluate as appropriate, any local variables.
- If the @var{find-file} argument to @code{normal-mode} is
+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 it. In this case, it may process a local variables
-list at the end of the file. The variable @code{enable-local-variables}
-controls whether to do so.
+list at the end of the file and in the @samp{-*-} line. The variable
+@code{enable-local-variables} controls whether to do so.
- If you run @code{normal-mode} interactively, the argument
+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 local variables list.
@xref{File variables, , Local Variables in Files, emacs, The GNU Emacs
Manual}, for the syntax of the local variables section of a file.
@cindex file mode specification error
- @code{normal-mode} uses @code{condition-case} around the call to the
+@code{normal-mode} uses @code{condition-case} around the call to the
major mode function, so errors are caught and reported as a @samp{File
mode specification error}, followed by the original error message.
@end deffn
ask the user what to do for each file. The default value is @code{t}.
@end defopt
+@defvar ignored-local-variables
+This variable holds a list of variables that should not be
+set by a local variables list. Any value specified
+for one of these variables is ignored.
+@end defvar
+
+In addition to this list, any variable whose name has a non-@code{nil}
+@code{risky-local-variable} property is also ignored.
+
@defopt enable-local-eval
This variable controls processing of @samp{Eval:} in local variables
lists in files being visited. A value of @code{t} means process them
@cindex visited file mode
This function selects the major mode that is appropriate for the
current buffer. It may base its decision on the value of the @w{@samp{-*-}}
-line, on the visited file name (using @code{auto-mode-alist}), or on the
+line, on the visited file name (using @code{auto-mode-alist}), on the
+@w{@samp{#!}} line (using @code{interpreter-mode-alist}), or on the
value of a local variable. However, this function does not look for
the @samp{mode:} local variable near the end of a file; the
@code{hack-local-variables} function does that. @xref{Choosing Modes, ,
been specially prepared.
@end defopt
+@defun set-buffer-major-mode buffer
+This function sets the major mode of @var{buffer} to the value of
+@code{default-major-mode}. If that variable is @code{nil}, it uses
+the current buffer's major mode (if that is suitable).
+
+The low-level primitives for creating buffers do not use this function,
+but medium-level commands such as @code{switch-to-buffer} and
+@code{find-file-noselect} use it whenever they create buffers.
+@end defun
+
@defvar initial-major-mode
@cindex @samp{*scratch*}
The value of this variable determines the major mode of the initial
@defvar interpreter-mode-alist
This variable specifes major modes to use for scripts that specify a
-command interpreter in an @samp{!#} line. Its value is a list of
+command interpreter in an @samp{#!} line. Its value is a list of
elements of the form @code{(@var{interpreter} . @var{mode})}; for
example, @code{("perl" . perl-mode)} is one element present by default.
The element says to use mode @var{mode} if the file specifies
Often the biggest problem in implementing a minor mode is finding a
way to insert the necessary hook into the rest of Emacs. Minor mode
-keymaps make this easier in Emacs 19 than it used to be.
+keymaps make this easier than it used to be.
@menu
* Minor Mode Conventions:: Tips for writing a minor mode.
list whose @sc{car} is such an integer or symbol; it should turn the
mode off otherwise.
-Here is an example taken from the definition of @code{overwrite-mode}.
-It shows the use of @code{overwrite-mode} as a variable that enables or
+Here is an example taken from the definition of @code{transient-mark-mode}.
+It shows the use of @code{transient-mark-mode} as a variable that enables or
disables the mode's behavior, and also shows the proper way to toggle,
enable or disable the minor mode based on the raw prefix argument value.
@smallexample
@group
-(setq overwrite-mode
- (if (null arg) (not overwrite-mode)
+(setq transient-mark-mode
+ (if (null arg) (not transient-mark-mode)
(> (prefix-numeric-value arg) 0)))
@end group
@end smallexample
@node Keymaps and Minor Modes
@subsection Keymaps and Minor Modes
-As of Emacs version 19, each minor mode can have its own keymap, which is
-active when the mode is enabled. @xref{Active Keymaps}. To set up a
-keymap for a minor mode, add an element to the alist
-@code{minor-mode-map-alist}.
+ Each minor mode can have its own keymap, which is active when the mode
+is enabled. To set up a keymap for a minor mode, add an element to the
+alist @code{minor-mode-map-alist}. @xref{Active Keymaps}.
@cindex @code{self-insert-command}, minor modes
One use of minor mode keymaps is to modify the behavior of certain
substituting your own definition of @code{self-insert-command} for the
standard one. The editor command loop handles this function specially.)
-@defvar minor-mode-map-alist
-This variable is an alist of elements that look like this:
-
-@example
-(@var{variable} . @var{keymap})
-@end example
-
-@noindent
-where @var{variable} is the variable that indicates whether the minor
-mode is enabled, and @var{keymap} is the keymap. The keymap
-@var{keymap} is active whenever @var{variable} has a non-@code{nil}
-value.
-
-Note that elements of @code{minor-mode-map-alist} do not have the same
-structure as elements of @code{minor-mode-alist}. The map must be the
-@sc{cdr} of the element; a list with the map as the second element will
-not do.
-
-What's more, the keymap itself must appear in the @sc{cdr}. It does not
-work to store a variable in the @sc{cdr} and make the map the value of
-that variable.
-
-When more than one minor mode keymap is active, their order of priority
-is the order of @code{minor-mode-map-alist}. But you should design
-minor modes so that they don't interfere with each other. If you do
-this properly, the order will not matter.
-@end defvar
+The key sequences bound in a minor mode should consist of @kbd{C-c}
+followed by a punctuation character @emph{other than} @kbd{@{},
+@kbd{@}}, @kbd{<}, @kbd{>}, @kbd{:} or @kbd{;}. (Those few punctuation
+characters are reserved for major modes.)
@node Mode Line Format
@section Mode Line Format
@code{mode-line-format} is a buffer-local variable that holds a
template used to display the mode line of the current buffer. All
-windows for the same buffer use the same @code{mode-line-format} and the
-mode lines will appear the same (except for scrolling percentages and
+windows for the same buffer use the same @code{mode-line-format} and
+their mode lines appear the same (except for scrolling percentages and
line numbers).
The mode line of a window is normally updated whenever a different
strings, symbols, and numbers kept in the buffer-local variable
@code{mode-line-format}. The data structure is called a @dfn{mode line
construct}, and it is built in recursive fashion out of simpler mode line
-constructs.
+constructs. The same data structure is used for constructing
+frame titles (@pxref{Frame Titles}).
@defvar mode-line-format
The value of this variable is a mode line construct with overall
@cindex percent symbol in mode line
@item @var{string}
A string as a mode line construct is displayed verbatim in the mode line
-except for @dfn{@code{%}-constructs}. Decimal digits after the @code{%}
+except for @dfn{@code{%}-constructs}. Decimal digits after the @samp{%}
specify the field width for space filling on the right (i.e., the data
is left justified). @xref{%-Constructs}.
use the same variables that appear in the default value (@pxref{Mode
Line Variables}), rather than duplicating their contents or displaying
the information in another fashion. This way, customizations made by
-the user, by libraries (such as @code{display-time}) and by major modes
-via changes to those variables remain effective.
+the user or by Lisp programs (such as @code{display-time} and major
+modes) via changes to those variables remain effective.
@cindex Shell mode @code{mode-line-format}
Here is an example of a @code{mode-line-format} that might be
"%n"
")%]----"
@group
- (line-number-mode "L%l--")
+ '(line-number-mode "L%l--")
'(-3 . "%p")
"-%-"))
@end group
This variable holds the value of the mode-line construct that displays
whether the current buffer is modified.
-The default value of @code{mode-line-modified} is
-@code{("--%1*%1*-")}. This means that the mode line displays
-@samp{--**-} if the buffer is modified, @samp{-----} if the buffer is
-not modified, and @samp{--%%-} if the buffer is read only.
+The default value of @code{mode-line-modified} is @code{("--%1*%1+-")}.
+This means that the mode line displays @samp{--**-} if the buffer is
+modified, @samp{-----} if the buffer is not modified, @samp{--%%-} if
+the buffer is read only, and @samp{--%*--} if the buffer is read only
+and modified.
Changing this variable does not force an update of the mode line.
@end defvar
@defvar mode-line-buffer-identification
This variable identifies the buffer being displayed in the window. Its
-default value is @code{("Emacs: %17b")}, which means that it displays
-@samp{Emacs:} followed by seventeen characters of the buffer name. You
-may want to change this in modes such as Rmail that do not behave like a
+default value is @code{("%F: %17b")}, which means that it usually
+displays @samp{Emacs:} followed by seventeen characters of the buffer
+name. (In a terminal frame, it displays the frame name instead of
+@samp{Emacs}; this has the effect of showing the frame number.) You may
+want to change this in modes such as Rmail that do not behave like a
``normal'' Emacs.
@end defvar
@example
@group
minor-mode-alist
-@result{} ((abbrev-mode " Abbrev")
- (overwrite-mode " Ovwrt")
+@result{} ((vc-mode vc-mode)
+ (abbrev-mode " Abbrev")
+ (overwrite-mode overwrite-mode)
(auto-fill-function " Fill")
- (defining-kbd-macro " Def"))
+ (defining-kbd-macro " Def")
+ (isearch-mode isearch-mode))
@end group
@end example
-@noindent
-(In earlier Emacs versions, @code{auto-fill-function} was called
-@code{auto-fill-hook}.)
-
- @code{minor-mode-alist} is not buffer-local. The variables mentioned
+@code{minor-mode-alist} is not buffer-local. The variables mentioned
in the alist should be buffer-local if the minor mode can be enabled
separately in each buffer.
@end defvar
mode-name
@end group
@group
+ mode-line-process
minor-mode-alist
"%n"
- mode-line-process
")%]----"
+ (line-number-mode "L%l--")
(-3 . "%p")
"-%-")
@end group
The visited file name, obtained with the @code{buffer-file-name}
function. @xref{Buffer File Name}.
+@item %F
+The name of the selected frame.
+
+@item %c
+The current column number of point.
+
+@item %l
+The current line number of point.
+
@item %*
@samp{%} if the buffer is read only (see @code{buffer-read-only}); @*
@samp{*} if the buffer is modified (see @code{buffer-modified-p}); @*
@samp{-} otherwise. @xref{Buffer Modification}.
@item %+
+@samp{*} if the buffer is modified (see @code{buffer-modified-p}); @*
+@samp{%} if the buffer is read only (see @code{buffer-read-only}); @*
+@samp{-} otherwise. This differs from @samp{%*} only for a modified
+read-only buffer. @xref{Buffer Modification}.
+
+@item %&
@samp{*} if the buffer is modified, and @samp{-} otherwise.
@item %s
The status of the subprocess belonging to the current buffer, obtained with
@code{process-status}. @xref{Process Information}.
+@item %t
+Whether the visited file is a text file or a binary file. (This is a
+meaningful distinction only on certain operating systems.)
+
@item %p
-The percent of the buffer above the @strong{top} of window, or
+The percentage of the buffer text above the @strong{top} of window, or
@samp{Top}, @samp{Bottom} or @samp{All}.
@item %P
@xref{Standard Hooks}, for a list of standard hook variables.
Most of the hooks in Emacs are @dfn{normal hooks}. These variables
-contain lists of functions to be called with no arguments. The reason
-most hooks are normal hooks is so that you can use them in a uniform
-way. You can always tell when a hook is a normal hook, because its
-name ends in @samp{-hook}.
+contain lists of functions to be called with no arguments. When the
+hook name ends in @samp{-hook}, that tells you it is normal. We try to
+make all hooks normal, as much as possible, so that you can use them in
+a uniform way.
+
+ Every major mode function is supposed to run a normal hook called the
+@dfn{mode hook} as the last step of initialization. This makes it easy
+for a user to customize the behavior of the mode, by overriding the
+local variable assignments already made by the mode. But hooks are used
+in other contexts too. For example, the hook @code{suspend-hook} runs
+just before Emacs suspends itself (@pxref{Suspending Emacs}).
The recommended way to add a hook function to a normal hook is by
calling @code{add-hook} (see below). The hook functions may be any of
a Function}). Most normal hook variables are initially void;
@code{add-hook} knows how to deal with this.
- As for abnormal hooks, those whose names end in @samp{-function} have
-a value that is a single function. Those whose names end in
-@samp{-hooks} have a value that is a list of functions. Any hook that
-is abnormal is abnormal because a normal hook won't do the job; either
-the functions are called with arguments, or their values are meaningful.
-The name shows you that the hook is abnormal and that you should look at
-its documentation string to see how to use it properly.
+ If the hook variable's name does not end with @samp{-hook}, that
+indicates it is probably an abnormal hook; you should look at its
+documentation to see how to use the hook properly.
- Most major modes run hooks as the last step of initialization. This
-makes it easy for a user to customize the behavior of the mode, by
-overriding the local variable assignments already made by the mode. But
-hooks are used in other contexts too. For example, the hook
-@code{suspend-hook} runs just before Emacs suspends itself
-(@pxref{Suspending Emacs}).
+ If the variable's name ends in @samp{-functions} or @samp{-hooks},
+then the value is a list of functions, but it is abnormal in that either
+these functions are called with arguments or their values are used in
+some way. You can use @code{add-hook} to add a function to the list,
+but you must take care in writing the function. (A few of these
+variables are actually normal hooks which were named before we
+established the convention of using @samp{-hook} for them.)
- Here's an expression you can put in your @file{.emacs} file to turn on
-Auto Fill mode when in Lisp Interaction mode:
+ If the variable's name ends in @samp{-function}, then its value
+is just a single function, not a list of functions.
+
+ Here's an expression that uses a mode hook to turn on Auto Fill mode
+when in Lisp Interaction mode:
@example
(add-hook 'lisp-interaction-mode-hook 'turn-on-auto-fill)
(setq c++-mode-hook c-mode-hook)
@end group
-@end example
-
- Finally, here is an example of how to use the Text mode hook to
-provide a customized mode line for buffers in Text mode, displaying the
-default directory in addition to the standard components of the
-mode line. (This may cause the mode line to run out of space if you
-have very long file names or display the time and load.)
-
-@example
-@group
-(add-hook 'text-mode-hook
- (function (lambda ()
- (setq mode-line-format
-@end group
- '(mode-line-modified
- "Emacs: %14b"
- " "
- default-directory
- " "
- global-mode-string
- "%[("
- mode-name
- minor-mode-alist
-@group
- "%n"
- mode-line-process
- ") %]---"
- (-3 . "%p")
- "-%-")))))
-@end group
@end example
At the appropriate time, Emacs uses the @code{run-hooks} function to
-run particular hooks. This function calls the hook functions you have
-added with @code{add-hooks}.
+run particular hooks. This function calls the hook functions that have
+been added with @code{add-hook}.
@defun run-hooks &rest hookvar
This function takes one or more hook variable names as arguments, and
called. If it is a list, the elements are called, in order.
The hook functions are called with no arguments.
-For example, here's how @code{emacs-lisp-hooks} runs its mode hook:
+For example, here's how @code{emacs-lisp-mode} runs its mode hook:
@example
(run-hooks 'emacs-lisp-mode-hook)
@end example
@end defun
-@defun add-hook hook function &optional append
+@defun add-hook hook function &optional append local
This function is the handy way to add function @var{function} to hook
variable @var{hook}. The argument @var{function} may be any valid Lisp
function with the proper number of arguments. For example,
If the optional argument @var{append} is non-@code{nil}, the new hook
function goes at the end of the hook list and will be executed last.
+
+If @var{local} is non-@code{nil}, that says to make the new hook
+function local to the current buffer. Before you can do this, you must
+make the hook itself buffer-local by calling @code{make-local-hook}
+(@strong{not} @code{make-local-variable}). If the hook itself is not
+buffer-local, then the value of @var{local} makes no difference---the
+hook function is always global.
@end defun
-@defun remove-hook hook function
+@defun remove-hook hook function &optional local
This function removes @var{function} from the hook variable @var{hook}.
-@end defun
-If you make a hook variable buffer-local, copy its value before you use
-@code{add-hook} or @code{remove-hook} to change it. For example,
+If @var{local} is non-@code{nil}, that says to remove @var{function}
+from the local hook list instead of from the global hook list. If the
+hook itself is not buffer-local, then the value of @var{local} makes no
+difference.
+@end defun
-@example
-(defun my-major-mode ()
- @dots{}
- (make-local-variable 'foo-hook)
- (if (boundp 'foo-hook)
- (setq foo-hook (copy-sequence foo-hook)))
- (add-hook 'foo-hook 'my-foo-function)"
- @dots{}
- )
-@end example
+@defun make-local-hook hook
+This function makes the hook variable @code{hook} local to the current
+buffer. When a hook variable is local, it can have local and global
+hook functions, and @code{run-hooks} runs all of them.
-Otherwise you may accidentally alter the list structure that forms part
-of the global value of the hook variable.
+This function works by making @code{t} an element of the buffer-local
+value. That serves as a flag to use the hook functions in the default
+value of the hook variable as well as those in the local value. Since
+@code{run-hooks} understands this flag, @code{make-local-hook} works
+with all normal hooks. It works for only some non-normal hooks---those
+whose callers have been updated to understand this meaning of @code{t}.
+Do not use @code{make-local-variable} directly for hook variables; it is
+not sufficient.
+@end defun
HCoop / bpt / emacs.git / blobdiff