(lispref.info)Major Mode Conventions


Next: Example Major Modes Prev: Major Modes Up: Major Modes

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 keep these conventions in mind when you
create 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 which describes the
     special commands available in this mode.  `C-h m'
     (`describe-mode') will print this.

     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.  Note: Keys in Documentation.  The `describe-mode'
     function replaces these special documentation substrings with
     their current meanings.  Note: Accessing Documentation.

   * 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).  Note: 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.
     Note: 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.  Use `defvar' to set the variable, so that it
     is not reinitialized if it already has a value.  (Such
     reinitialization could discard customizations made by the user.)

   * 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'.  The reasons
     for this are the same as for using a keymap variable.  *Note
     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'.  *Note
     Abbrev Tables::.

   * To give a variable a buffer-local binding, 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::.

   * If hooks are appropriate for the mode, the major mode command
     should run the hooks after completing all other initialization so
     the user may further customize any of the settings.  Note: Hooks.

   * 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 it is desirable that Emacs use the new mode by default after
     visiting 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 `.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.


automatically generated by info2www