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
+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 documentation string may include the special documentation
substrings, @samp{\[@var{command}]}, @samp{\@{@var{keymap}@}}, and
-@samp{\<@var{keymap}>}, that enable the documentation to adapt
+@samp{\<@var{keymap}>}, which enable the documentation to adapt
automatically to the user's own key bindings. @xref{Keys in
Documentation}.
@end smallexample
Finally, here is the complete major mode function definition for
-Emacs Lisp mode.
+Lisp mode.
@smallexample
@group
@defvar interpreter-mode-alist
This variable specifies major modes to use for scripts that specify a
-command interpreter in an @samp{#!} line. Its value is a list of
+command interpreter in a @samp{#!} line. Its value is a list of
elements of the form @code{(@var{interpreter} . @var{mode})}; for
example, @code{("perl" . perl-mode)} is one element present by default.
The element says to use mode @var{mode} if the file specifies
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.)
+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.
+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
@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
@subsection Easy-Mmode
The easy-mmode package provides a convenient way of implementing a
-minor mode; with it, you can specify all about a simple minor mode in
-one self-contained definition.
+minor mode; with it, you can specify everything about a simple minor
+mode in one self-contained definition.
@defmac easy-mmode-define-minor-mode mode doc &optional init-value mode-indicator keymap
@tindex easy-mmode-define-minor-mode
@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
@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.
+default value is @code{("%12b")}, which displays the buffer name, padded
+with spaces to at least 12 columns.
@end defvar
@defvar global-mode-string
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
+@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 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:
+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
The @code{imenu-generic-expression} patterns can then use @samp{\\sw+}
-instead of @samp{\\(\\sw\\|\\s_\\)\\}. Note that this technique may be
+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
+of a name to a smaller set of characters than are allowed in the rest
+of a name.
Setting this variable makes it buffer-local in the current buffer.
@end defvar
There are several variables that control how Font Lock mode highlights
text. But major modes should not set any of these variables directly.
-Instead, it should set @code{font-lock-defaults} as a buffer-local
+Instead, they should set @code{font-lock-defaults} as a buffer-local
variable. The value assigned to this variable is used, if and when Font
Lock mode is enabled, to set all the other variables.
The fifth element, @var{syntax-begin}, specifies the value of
@code{font-lock-beginning-of-syntax-function} (see below).
-Any further elements @var{other-vars} are have form
+Any further elements @var{other-vars} are of the form
@code{(@var{variable} . @var{value})}. This kind of element means to
make @var{variable} buffer-local and then set it to @var{value}. This
is used to set other variables that affect fontification.
match data to describe the match that was found.
@item (@var{matcher} . @var{match})
-In this kind of element, @var{matcher} stands for either a regular
+In this kind of element, @var{matcher} is either a regular
expression or a function, as described above. The @sc{cdr},
@var{match}, specifies which subexpression of @var{matcher} should be
highlighted (instead of the entire text that @var{matcher} matched).
@table @code
@item font-lock-comment-face
@vindex font-lock-comment-face
-@kindex font-lock-comment-face @r{(face name)}
Used (typically) for comments.
@item font-lock-string-face
@vindex font-lock-string-face
-@kindex font-lock-string-face @r{(face name)}
Used (typically) for string constants.
@item font-lock-keyword-face
@vindex font-lock-keyword-face
-@kindex font-lock-keyword-face @r{(face name)}
Used (typically) for keywords---names that have special syntactic
significance, like @code{for} and @code{if} in C.
@item font-lock-builtin-face
@vindex font-lock-builtin-face
-@kindex font-lock-builtin-face @r{(face name)}
Used (typically) for built-in function names.
@item font-lock-function-name-face
@vindex font-lock-function-name-face
-@kindex font-lock-function-name-face @r{(face name)}
Used (typically) for the name of a function being defined or declared,
in a function definition or declaration.
@item font-lock-variable-name-face
@vindex font-lock-variable-name-face
-@kindex font-lock-variable-name-face @r{(face name)}
Used (typically) for the name of a variable being defined or declared,
in a variable definition or declaration.
@item font-lock-type-face
@vindex font-lock-type-face
-@kindex font-lock-type-face @r{(face name)}
Used (typically) for names of user-defined data types,
where they are defined and where they are used.
@item font-lock-constant-face
@vindex font-lock-constant-face
-@kindex font-lock-constant-face @r{(face name)}
Used (typically) for constant names.
@item font-lock-warning-face
@vindex font-lock-warning-face
-@kindex font-lock-warning-face @r{(face name)}
Used (typically) for constructs that are peculiar, or that greatly
change the meaning of other text. For example, this is used for
@samp{;;;###autoload} cookies in Emacs Lisp, and for @code{#error}
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.
+@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
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.
+stops, and returns whatever was returned by the last hook function
+that was called.
@end defun
@defun add-hook hook function &optional append local
HCoop / bpt / emacs.git / blobdiff