GNU Info
(elisp)Major Mode Conventions
Major Mode Conventions
----------------------
The code for existing major modes follows various coding conventions,
including conventions for local keymap and syntax table initialization,
global names, and hooks. Please follow these conventions when you
define a new major mode.
This list of conventions is only partial, because each major mode
should aim for consistency in general with other Emacs major modes.
This makes Emacs as a whole more coherent. It is impossible to list
here all the possible points where this issue might come up; if the
Emacs developers point out an area where your major mode deviates from
the usual conventions, please make it compatible.
* Define a command whose name ends in `-mode', with no arguments,
that switches to the new mode in the current buffer. This command
should set up the keymap, syntax table, and buffer-local variables
in an existing buffer, without changing the buffer's contents.
* Write a documentation string for this command that describes the
special commands available in this mode. `C-h m'
(`describe-mode') in your mode will display this string.
The documentation string may include the special documentation
substrings, `\[COMMAND]', `\{KEYMAP}', and `\<KEYMAP>', which
enable the documentation to adapt automatically to the user's own
key bindings. Note: Keys in Documentation.
* The major mode command should start by calling
`kill-all-local-variables'. This is what gets rid of the
buffer-local variables of the major mode previously in effect.
* The major mode command should set the variable `major-mode' to the
major mode command symbol. This is how `describe-mode' discovers
which documentation to print.
* The major mode command should set the variable `mode-name' to the
"pretty" name of the mode, as a string. This string appears in the
mode line.
* 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). Note: Coding
Conventions.
* In a major mode for editing some kind of structured text, such as a
programming language, indentation of text according to structure is
probably useful. So the mode should set `indent-line-function' to
a suitable function, and probably customize other variables for
indentation.
* The major mode should usually have its own keymap, which is used
as the local keymap in all buffers in that mode. The major mode
command should call `use-local-map' to install this local map.
Note: Active Keymaps, for more information.
This keymap should be stored permanently in a global variable named
`MODENAME-mode-map'. Normally the library that defines the mode
sets this variable.
Note: Tips for Defining, for advice about how to write the code
to set up the mode's keymap variable.
* The key sequences bound in a major mode keymap should usually
start with `C-c', followed by a control character, a digit, or `{',
`}', `<', `>', `:' or `;'. 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
`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.
* Major modes must not define <RET> to do anything other than insert
a newline. The command to insert a newline and then indent is
`C-j'. Please keep this distinction uniform for all major modes.
* Major modes should not alter options that are primary a matter of
user preference, such as whether Auto-Fill mode is enabled. Leave
this to each user to decide. However, a major mode should
customize other variables so that Auto-Fill mode will work
usefully _if_ the user decides to use it.
* The mode may have its own syntax table or may share one with other
related modes. If it has its own syntax table, it should store
this in a variable named `MODENAME-mode-syntax-table'. Note:
Syntax Tables.
* If the mode handles a language that has a syntax for comments, it
should set the variables that define the comment syntax. Note:
Options Controlling Comments.
* The mode may have its own abbrev table or may share one with other
related modes. If it has its own abbrev table, it should store
this in a variable named `MODENAME-mode-abbrev-table'. Note:
Abbrev Tables.
* The mode should specify how to do highlighting for Font Lock mode,
by setting up a buffer-local value for the variable
`font-lock-defaults' (Note: Font Lock Mode).
* 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 `imenu-generic-expression' or
`imenu-create-index-function' (Note: Imenu).
* Use `defvar' or `defcustom' to set mode-related variables, so that
they are not reinitialized if they already have a value. (Such
reinitialization could discard customizations made by the user.)
* To make a buffer-local binding for an Emacs customization
variable, use `make-local-variable' in the major mode command, not
`make-variable-buffer-local'. The latter function would make the
variable local to every buffer in which it is subsequently set,
which would affect buffers that do not use this mode. It is
undesirable for a mode to have such global effects. Note:
Buffer-Local Variables.
With rare exceptions, the only reasonable way to use
`make-variable-buffer-local' in a Lisp package is for a variable
which is used only within that package. Using it on a variable
used by other packages would interfere with them.
* Each major mode should have a "mode hook" named
`MODENAME-mode-hook'. The major mode command should run that
hook, with `run-hooks', as the very last thing it does. Note:
Hooks.
* The major mode command may also run the hooks of some more basic
modes. For example, `indented-text-mode' runs `text-mode-hook' as
well as `indented-text-mode-hook'. It may run these other hooks
immediately before the mode's own hook (that is, after everything
else), or it may run them earlier.
* If something special should be done if the user switches a buffer
from this mode to any other major mode, this mode can set up a
buffer-local value for `change-major-mode-hook' (Note: Creating
Buffer-Local).
* If this mode is appropriate only for specially-prepared text, then
the major mode command symbol should have a property named
`mode-class' with value `special', put on as follows:
(put 'funny-mode 'mode-class 'special)
This tells Emacs that new buffers created while the current buffer
is in Funny mode should not inherit Funny mode. Modes such as
Dired, Rmail, and Buffer List use this feature.
* If you want to make the new mode the default for files with certain
recognizable names, add an element to `auto-mode-alist' to select
the mode for those file names. If you define the mode command to
autoload, you should add this element in the same file that calls
`autoload'. Otherwise, it is sufficient to add the element in the
file that contains the mode definition. Note: Auto Major Mode.
* In the documentation, you should provide a sample `autoload' form
and an example of how to add to `auto-mode-alist', that users can
include in their init files (Note: Init File).
* The top-level forms in the file defining the mode should be
written so that they may be evaluated more than once without
adverse consequences. Even if you never load the file more than
once, someone else will.
automatically generated by info2www version 1.2.2.9