comparison lispref/modes.texi @ 17278:8ed8412c1ce7

Document key binding conventions for major modes and minor modes.

17277:6ee6f94817dc

@item
@cindex functions in modes
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}.

@item
@cindex keymaps in modes
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

@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
@cindex syntax tables in modes
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

@cindex mode hook
@cindex major mode hook
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}.

@item
The major mode command may also run the hooks of some more basic modes.
For example, @code{indented-text-mode} runs @code{text-mode-hook} as
well as @code{indented-text-mode-hook}.  It may run these other hooks

facilities for customizing @code{self-insert-command} are limited to
special cases (designed for abbrevs and Auto Fill mode).  (Do not try
substituting your own definition of @code{self-insert-command} for the
standard one.  The editor command loop handles this function specially.)

@node Mode Line Format
@section Mode Line Format
@cindex mode line

  Each Emacs window (aside from minibuffer windows) includes a mode line,

17278:8ed8412c1ce7

@item
@cindex functions in modes
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{Coding Conventions}.

@item
@cindex keymaps in modes
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

@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
related modes.  If it has its own syntax table, it should store this in

@cindex mode hook
@cindex major mode hook
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}.

@item
The major mode command may also run the hooks of some more basic modes.
For example, @code{indented-text-mode} runs @code{text-mode-hook} as
well as @code{indented-text-mode-hook}.  It may run these other hooks

facilities for customizing @code{self-insert-command} are limited to
special cases (designed for abbrevs and Auto Fill mode).  (Do not try
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

  Each Emacs window (aside from minibuffer windows) includes a mode line,