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.
@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, ,
@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
substituting your own definition of @code{self-insert-command} for the
standard one. The editor command loop handles this function specially.)
+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
@cindex mode line
@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.
-
- Major mode functions are supposed to run a 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}).
+ 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.
+
+ 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.)
+
+ 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:
buffer. When a hook variable is local, it can have local and global
hook functions, and @code{run-hooks} runs all of them.
+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