comparison lispref/modes.texi @ 22252:40089afa2b1d

*** empty log message ***

22251:5989fa41cda6

Text mode except that it provides three additional commands.  Its
definition is distinct from that of Text mode, but was derived from it.

  Rmail Edit mode offers an example of changing the major mode
temporarily for a buffer, so it can be edited in a different way (with
ordinary Emacs commands rather than Rmail).  In such cases, the
temporary major mode usually has a command to switch back to the
buffer's usual mode (Rmail mode, in this case).  You might be tempted to
present the temporary redefinitions inside a recursive edit and restore
the usual ones when the user exits; but this is a bad idea because it
constrains the user's options when it is done in more than one buffer:

@item
@cindex mode variable
Make a variable whose name ends in @samp{-mode} to control the minor
mode.  We call this the @dfn{mode variable}.  The minor mode command
should set this variable (@code{nil} to disable; anything else to
enable.)

If it is possible, implement the mode so that setting the variable
automatically enables or disables the mode.  Then the minor mode command
does not need to do anything except the variable.

This variable is used in conjunction with the @code{minor-mode-alist} to
display the minor mode name in the mode line.  It can also enable
or disable a minor mode keymap.  Individual commands or hooks can also
check the variable's value.

    (setq minor-mode-alist
          (cons '(leif-mode " Leif") minor-mode-alist)))
@end group
@end smallexample
@end itemize

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

  Each minor mode can have its own keymap, which is active when the mode

   '(-3 . "%p")
   "-%-"))
@end group
@end example

@node Mode Line Variables
@subsection Variables Used in the Mode Line

  This section describes variables incorporated by the
standard value of @code{mode-line-format} into the text of the mode

frame at a time.
@end defvar

@defvar mode-line-buffer-identification
This variable identifies the buffer being displayed in the window.  Its
default value is @code{("%12b")}, which means that it usually
displays @samp{Emacs:} followed by seventeen characters of the buffer
name.  (In a terminal frame, it displays the frame name instead of
@samp{Emacs}; this has the effect of showing the frame number.)  You may
want to change this in modes such as Rmail that do not behave like a
``normal'' Emacs.
@end defvar

@defvar global-mode-string
This variable holds a mode line spec that appears in the mode line by
default, just after the buffer name.  The command @code{display-time}

@defvar mode-line-process
This buffer-local variable contains the mode line information on process
status in modes used for communicating with subprocesses.  It is
displayed immediately following the major mode name, with no intervening
space.  For example, its value in the @samp{*shell*} buffer is
@code{(":@: %s")}, which allows the shell to display its status along
with the major mode as: @samp{(Shell:@: run)}.  Normally this variable
is @code{nil}.
@end defvar

@defvar default-mode-line-format

Setting this variable makes it buffer-local in the current buffer.
@end defvar

@defvar imenu-syntax-alist
This variable is an alist of syntax table modifiers to use while
executing @code{imenu--generic-function} to override the syntax table of
the current buffer.  Each element should have this form:

@example
(@var{characters} . @var{syntax-description})
@end example

@example
  (setq imenu-syntax-alist '(("_$" . "w")))
@end example

The @code{imenu-generic-expression} patterns can then use @samp{\\sw+}
instead of @samp{\\(\\sw\\|\\s_\\)\\}.  Note that this technique may be
inconvenient to use when the mode needs to limit the initial character
of a name to a smaller set of characters

Setting this variable makes it buffer-local in the current buffer.
@end defvar

@defun run-hook-with-args-until-failure hook &rest args
This function is the way to run an abnormal hook which passes arguments
to the hook functions, and stops as soon as any hook function fails.  It
calls each of the hook functions, passing each of them the arguments
@var{args}, until some hook function returns @code{nil}.  Then it stops.
@end defun

@defun run-hook-with-args-until-success hook &rest args
This function is the way to run an abnormal hook which passes arguments
to the hook functions, and stops as soon as any hook function succeeds.
It calls each of the hook functions, passing each of them the arguments
@var{args}, until some hook function returns non-@code{nil}.  Then it
stops.
@end defun

@defun add-hook hook function &optional append local
This function is the handy way to add function @var{function} to hook
variable @var{hook}.  The argument @var{function} may be any valid Lisp

22252:40089afa2b1d

Text mode except that it provides three additional commands.  Its
definition is distinct from that of Text mode, but was derived from it.

  Rmail Edit mode offers an example of changing the major mode
temporarily for a buffer, so it can be edited in a different way (with
ordinary Emacs commands rather than Rmail commands).  In such cases, the
temporary major mode usually has a command to switch back to the
buffer's usual mode (Rmail mode, in this case).  You might be tempted to
present the temporary redefinitions inside a recursive edit and restore
the usual ones when the user exits; but this is a bad idea because it
constrains the user's options when it is done in more than one buffer:

@item
@cindex mode variable
Make a variable whose name ends in @samp{-mode} to control the minor
mode.  We call this the @dfn{mode variable}.  The minor mode command
should set this variable (@code{nil} to disable; anything else to
enable).

If it is possible, implement the mode so that setting the variable
automatically enables or disables the mode.  Then the minor mode command
does not need to do anything except set the variable.

This variable is used in conjunction with the @code{minor-mode-alist} to
display the minor mode name in the mode line.  It can also enable
or disable a minor mode keymap.  Individual commands or hooks can also
check the variable's value.

    (setq minor-mode-alist
          (cons '(leif-mode " Leif") minor-mode-alist)))
@end group
@end smallexample
@end itemize

  You can also use @code{add-to-list} to add an element to this list
just once (@pxref{Setting Variables}).

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

  Each minor mode can have its own keymap, which is active when the mode

   '(-3 . "%p")
   "-%-"))
@end group
@end example

@noindent
(The variables @code{line-number-mode}, @code{column-number-mode}
and @code{which-func-mode} enable particular minor modes; as usual,
these variable names are also the minor mode command names.)

@node Mode Line Variables
@subsection Variables Used in the Mode Line

  This section describes variables incorporated by the
standard value of @code{mode-line-format} into the text of the mode

frame at a time.
@end defvar

@defvar mode-line-buffer-identification
This variable identifies the buffer being displayed in the window.  Its
default value is @code{("%12b")}, which means that it usually displays
twelve characters of the buffer name.
@end defvar

@defvar global-mode-string
This variable holds a mode line spec that appears in the mode line by
default, just after the buffer name.  The command @code{display-time}

@defvar mode-line-process
This buffer-local variable contains the mode line information on process
status in modes used for communicating with subprocesses.  It is
displayed immediately following the major mode name, with no intervening
space.  For example, its value in the @samp{*shell*} buffer is
@code{(":%s")}, which allows the shell to display its status along
with the major mode as: @samp{(Shell:@: run)}.  Normally this variable
is @code{nil}.
@end defvar

@defvar default-mode-line-format

Setting this variable makes it buffer-local in the current buffer.
@end defvar

@defvar imenu-syntax-alist
This variable is an alist of syntax table modifiers to use while
processing @code{imenu-generic-expression}, to override the syntax table
of the current buffer.  Each element should have this form:

@example
(@var{characters} . @var{syntax-description})
@end example

@example
  (setq imenu-syntax-alist '(("_$" . "w")))
@end example

The @code{imenu-generic-expression} patterns can then use @samp{\\sw+}
instead of @samp{\\(\\sw\\|\\s_\\)+}.  Note that this technique may be
inconvenient to use when the mode needs to limit the initial character
of a name to a smaller set of characters

Setting this variable makes it buffer-local in the current buffer.
@end defvar

@defun run-hook-with-args-until-failure hook &rest args
This function is the way to run an abnormal hook which passes arguments
to the hook functions, and stops as soon as any hook function fails.  It
calls each of the hook functions, passing each of them the arguments
@var{args}, until some hook function returns @code{nil}.  Then it stops,
and returns @code{nil} if some hook function did, and otherwise
returns a non-@code{nil} value.
@end defun

@defun run-hook-with-args-until-success hook &rest args
This function is the way to run an abnormal hook which passes arguments
to the hook functions, and stops as soon as any hook function succeeds.
It calls each of the hook functions, passing each of them the arguments
@var{args}, until some hook function returns non-@code{nil}.  Then it
stops, and returns whatever was returned by the last hook function
that was called.
@end defun

@defun add-hook hook function &optional append local
This function is the handy way to add function @var{function} to hook
variable @var{hook}.  The argument @var{function} may be any valid Lisp