GNU Emacs Lisp Reference Manual

20.1.1: 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:

• 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 local variables in an existing buffer without changing the buffer's text.
• 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>', that enable the documentation to adapt automatically to the user's own key bindings. See Keys in Documentation.

• The major mode command should start by calling kill-all-local-variables. This is what gets rid of the 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 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). See Style Tips.
• 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 function should call use-local-map to install this local map. See Active Keymaps, for more information.

  This keymap should be kept in a global variable named modename-mode-map. Normally the library that defines the mode sets this variable.

• 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. See Syntax Tables.
• 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. See Abbrev Tables.
• Use defvar 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. See Buffer-Local Variables.

  It's ok to use make-variable-buffer-local, if you wish, for a variable used only within a single Lisp package.

• 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. See 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, the mode can set a local value for change-major-mode-hook.
• 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 has 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. See 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 `.emacs' files.
• 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.

Variable: change-major-mode-hook

This normal hook is run by kill-all-local-variables before it does anything else. This gives major modes a way to arrange for something special to be done if the user switches to a different major mode. For best results, make this variable buffer-local, so that it will disappear after doing its job and will not interfere with the subsequent major mode. See Hooks.