comparison lispref/modes.texi @ 62539:14e404c9c65f

(Hooks): Delete confusing and unnecessary sentence. (Major Mode Conventions): Refer to `Auto Major Mode' in more appropriate place. (Derived Modes): Small clarifications. (Minor Mode Conventions, Keymaps and Minor Modes): Replace references to nodes with references to anchors. (Mode Line Data): Warn that `(:eval FORM)' should not load any files. Clarify description of lists whose first element is an integer. (Mode Line Variables): Add anchor. (%-Constructs): Clarify description of integer after %. (Emulating Mode Line): Describe nil value for FACE.

62538:431e1a995da5

@example
(add-hook 'lisp-interaction-mode-hook 'turn-on-auto-fill)
@end example

  At the appropriate time, Emacs uses the @code{run-hooks} function to
run particular hooks.  This function calls the hook functions that have
been added with @code{add-hook}.

@defun run-hooks &rest hookvars
This function takes one or more normal hook variable names as
arguments, and runs each hook in turn.  Each argument should be a
symbol that is a normal hook variable.  These arguments are processed

and Buffer List use this feature.

@item
If you want to make the new mode the default for files with certain
recognizable names, add an element to @code{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
@code{autoload}.  If you use an autoload cookie for the mode command,
you can also use an autoload cookie for the form that adds the element
(@pxref{autoload cookie}).  If you do not autoload the mode command,
it is sufficient to add the element in the file that contains the mode
definition.  @xref{Auto Major Mode}.

@item
In the comments that document the file, you should provide a sample
@code{autoload} form and an example of how to add to
@code{auto-mode-alist}, that users can include in their init files

@code{:abbrev-table} keyword (see below).

@item
The new mode has its own mode hook, @code{@var{variant}-hook}.  It
runs this hook, after running the hooks of its ancestor modes, with
@code{run-mode-hooks} (@pxref{Mode Hooks}).
@end itemize

In addition, you can specify how to override other aspects of
@var{parent} with @var{body}.  The command @var{variant}
evaluates the forms in @var{body} after setting up all its usual
overrides, just before running @code{@var{variant}-hook}.

You can also specify @code{nil} for @var{parent}.  This gives the new
mode no parent.  Then @code{define-derived-mode} behaves as described
above, but, of course, omits all actions connected with @var{parent}.

@end group
@end smallexample

@item
Add an element to @code{minor-mode-alist} for each minor mode
(@pxref{Mode Line Variables}), if you want to indicate the minor mode in
the mode line.  This element should be a list of the following form:

@smallexample
(@var{mode-variable} @var{string})
@end smallexample

  If just setting the variable is not sufficient to enable the mode, you
should also specify a @code{:set} method which enables the mode by
invoking the mode command.  Note in the variable's documentation string that
setting the variable other than via Custom may not take effect.

  Also mark the definition with an autoload cookie (@pxref{Autoload}),
and specify a @code{:require} so that customizing the variable will load
the library that defines the mode.  This will copy suitable definitions
into @file{loaddefs.el} so that users can use @code{customize-option} to
enable the mode.  For example:

@node Keymaps and Minor Modes
@subsection Keymaps and Minor Modes

  Each minor mode can have its own keymap, which is active when the mode
is enabled.  To set up a keymap for a minor mode, add an element to the
alist @code{minor-mode-map-alist}.  @xref{Active Keymaps}.

@cindex @code{self-insert-command}, minor modes
  One use of minor mode keymaps is to modify the behavior of certain
self-inserting characters so that they do something else as well as
self-insert.  In general, this is the only way to do that, since the

elements recursively and concatenate the results.  This is the most
common form of mode-line construct.

@item (:eval @var{form})
A list whose first element is the symbol @code{:eval} says to evaluate
@var{form}, and use the result as a string to display.

@item (:propertize @var{elt} @var{props}@dots{})
A list whose first element is the symbol @code{:propertize} says to
process the mode-line construct @var{elt} recursively and add the text
properties specified by @var{props} to the result.  The argument

@item (@var{width} @var{rest}@dots{})
A list whose first element is an integer specifies truncation or
padding of the results of @var{rest}.  The remaining elements
@var{rest} are processed recursively as mode-line constructs and
concatenated together.  Then the result is space filled (if
@var{width} is positive) or truncated (to @minus{}@var{width} columns,
if @var{width} is negative) on the right.

For example, the usual way to show what percentage of a buffer is above
the top of the window is to use a list like this: @code{(-3 "%p")}.
@end table

with the major mode as: @samp{(Shell:run)}.  Normally this variable
is @code{nil}.
@end defvar

@defvar minor-mode-alist
This variable holds an association list whose elements specify how the
mode line should indicate that a minor mode is active.  Each element of
the @code{minor-mode-alist} should be a two-element list:

@example

@node %-Constructs
@subsection @code{%}-Constructs in the Mode Line

  The following table lists the recognized @code{%}-constructs and what
they mean.  In any construct except @samp{%%}, you can add a decimal
integer after the @samp{%} to specify how many characters to display.

@table @code
@item %b
The current buffer name, obtained with the @code{buffer-name} function.
@xref{Buffer Names}.

@subsection Properties in the Mode Line
@cindex text properties in the mode line

  Certain text properties are meaningful in the
mode line.  The @code{face} property affects the appearance of text; the
@code{help-echo} property associate help strings with the text, and
@code{local-map} can make the text mouse-sensitive.

  There are four ways to specify text properties for text in the mode
line:

@node Emulating Mode Line
@subsection Emulating Mode-Line Formatting

  You can use the function @code{format-mode-line} to compute
the text that would appear in a mode line or header line
based on certain mode-line specification.

@defun format-mode-line format &optional face window buffer
This function formats a line of text according to @var{format} as if
it were generating the mode line for @var{window}, but instead of
displaying the text in the mode line or the header line, it returns

The value string normally has text properties that correspond to the
faces, keymaps, etc., that the mode line would have.  And any character
for which no @code{face} property is specified gets a default
value which is usually @var{face}.  (If @var{face} is @code{t},
that stands for either @code{mode-line} if @var{window} is selected,
otherwise @code{mode-line-inactive}.)

However, if @var{face} is an integer, the value has no text properties.

For example, @code{(format-mode-line header-line-format)} returns the
text that would appear in the selected window's header line (@code{""}

62539:14e404c9c65f

@example
(add-hook 'lisp-interaction-mode-hook 'turn-on-auto-fill)
@end example

  At the appropriate time, Emacs uses the @code{run-hooks} function to
run particular hooks.

@defun run-hooks &rest hookvars
This function takes one or more normal hook variable names as
arguments, and runs each hook in turn.  Each argument should be a
symbol that is a normal hook variable.  These arguments are processed

and Buffer List use this feature.

@item
If you want to make the new mode the default for files with certain
recognizable names, add an element to @code{auto-mode-alist} to select
the mode for those file names (@pxref{Auto Major Mode}).  If you
define the mode command to autoload, you should add this element in
the same file that calls @code{autoload}.  If you use an autoload
cookie for the mode command, you can also use an autoload cookie for
the form that adds the element (@pxref{autoload cookie}).  If you do
not autoload the mode command, it is sufficient to add the element in
the file that contains the mode definition.

@item
In the comments that document the file, you should provide a sample
@code{autoload} form and an example of how to add to
@code{auto-mode-alist}, that users can include in their init files

@code{:abbrev-table} keyword (see below).

@item
The new mode has its own mode hook, @code{@var{variant}-hook}.  It
runs this hook, after running the hooks of its ancestor modes, with
@code{run-mode-hooks}, as the last thing it does. @xref{Mode Hooks}.
@end itemize

In addition, you can specify how to override other aspects of
@var{parent} with @var{body}.  The command @var{variant}
evaluates the forms in @var{body} after setting up all its usual
overrides, just before running the mode hooks.

You can also specify @code{nil} for @var{parent}.  This gives the new
mode no parent.  Then @code{define-derived-mode} behaves as described
above, but, of course, omits all actions connected with @var{parent}.

@end group
@end smallexample

@item
Add an element to @code{minor-mode-alist} for each minor mode
(@pxref{Definition of minor-mode-alist}), if you want to indicate the
minor mode in the mode line.  This element should be a list of the
following form:

@smallexample
(@var{mode-variable} @var{string})
@end smallexample

  If just setting the variable is not sufficient to enable the mode, you
should also specify a @code{:set} method which enables the mode by
invoking the mode command.  Note in the variable's documentation string that
setting the variable other than via Custom may not take effect.

  Also mark the definition with an autoload cookie (@pxref{autoload cookie}),
and specify a @code{:require} so that customizing the variable will load
the library that defines the mode.  This will copy suitable definitions
into @file{loaddefs.el} so that users can use @code{customize-option} to
enable the mode.  For example:

@node Keymaps and Minor Modes
@subsection Keymaps and Minor Modes

  Each minor mode can have its own keymap, which is active when the mode
is enabled.  To set up a keymap for a minor mode, add an element to the
alist @code{minor-mode-map-alist}.  @xref{Definition of minor-mode-map-alist}.

@cindex @code{self-insert-command}, minor modes
  One use of minor mode keymaps is to modify the behavior of certain
self-inserting characters so that they do something else as well as
self-insert.  In general, this is the only way to do that, since the

elements recursively and concatenate the results.  This is the most
common form of mode-line construct.

@item (:eval @var{form})
A list whose first element is the symbol @code{:eval} says to evaluate
@var{form}, and use the result as a string to display.  Make sure this
evaluation cannot load any files, as doing so could cause infinite
recursion.

@item (:propertize @var{elt} @var{props}@dots{})
A list whose first element is the symbol @code{:propertize} says to
process the mode-line construct @var{elt} recursively and add the text
properties specified by @var{props} to the result.  The argument

@item (@var{width} @var{rest}@dots{})
A list whose first element is an integer specifies truncation or
padding of the results of @var{rest}.  The remaining elements
@var{rest} are processed recursively as mode-line constructs and
concatenated together.  When @var{width} is positive, the result is
space filled on the right if its width is less than @var{width}.  When
@var{width} is negative, the result is truncated on the right to
@minus{}@var{width} columns if its width exceeds @minus{}@var{width}.

For example, the usual way to show what percentage of a buffer is above
the top of the window is to use a list like this: @code{(-3 "%p")}.
@end table

with the major mode as: @samp{(Shell:run)}.  Normally this variable
is @code{nil}.
@end defvar

@defvar minor-mode-alist
@anchor{Definition of minor-mode-alist}
This variable holds an association list whose elements specify how the
mode line should indicate that a minor mode is active.  Each element of
the @code{minor-mode-alist} should be a two-element list:

@example

@node %-Constructs
@subsection @code{%}-Constructs in the Mode Line

  The following table lists the recognized @code{%}-constructs and what
they mean.  In any construct except @samp{%%}, you can add a decimal
integer after the @samp{%} to specify a minimum field width.  If the
width is less, the field is padded with spaces to the right.

@table @code
@item %b
The current buffer name, obtained with the @code{buffer-name} function.
@xref{Buffer Names}.

@subsection Properties in the Mode Line
@cindex text properties in the mode line

  Certain text properties are meaningful in the
mode line.  The @code{face} property affects the appearance of text; the
@code{help-echo} property associates help strings with the text, and
@code{local-map} can make the text mouse-sensitive.

  There are four ways to specify text properties for text in the mode
line:

@node Emulating Mode Line
@subsection Emulating Mode-Line Formatting

  You can use the function @code{format-mode-line} to compute
the text that would appear in a mode line or header line
based on a certain mode-line specification.

@defun format-mode-line format &optional face window buffer
This function formats a line of text according to @var{format} as if
it were generating the mode line for @var{window}, but instead of
displaying the text in the mode line or the header line, it returns

The value string normally has text properties that correspond to the
faces, keymaps, etc., that the mode line would have.  And any character
for which no @code{face} property is specified gets a default
value which is usually @var{face}.  (If @var{face} is @code{t},
that stands for either @code{mode-line} if @var{window} is selected,
otherwise @code{mode-line-inactive}.  If @var{face} is @code{nil} or
omitted, that stands for no face property.)

However, if @var{face} is an integer, the value has no text properties.

For example, @code{(format-mode-line header-line-format)} returns the
text that would appear in the selected window's header line (@code{""}