# HG changeset patch # User Luc Teirlinck # Date 1116545718 0 # Node ID 14e404c9c65f2cbb9cdf4b9db8e0ee07dbe04590 # Parent 431e1a995da526e8affcd63c2fb7549e17d6611c (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. diff -r 431e1a995da5 -r 14e404c9c65f lispref/modes.texi --- a/lispref/modes.texi Thu May 19 23:29:21 2005 +0000 +++ b/lispref/modes.texi Thu May 19 23:35:18 2005 +0000 @@ -88,8 +88,7 @@ @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}. +run particular hooks. @defun run-hooks &rest hookvars This function takes one or more normal hook variable names as @@ -470,13 +469,13 @@ @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}. +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 @@ -1011,13 +1010,13 @@ @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}). +@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 @code{@var{variant}-hook}. +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 @@ -1262,8 +1261,9 @@ @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: +(@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}) @@ -1305,7 +1305,7 @@ 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}), + 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 @@ -1334,7 +1334,7 @@ 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}. +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 @@ -1628,7 +1628,9 @@ @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. +@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 @@ -1650,9 +1652,10 @@ 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. +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")}. @@ -1818,6 +1821,7 @@ @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: @@ -1889,7 +1893,8 @@ 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. +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 @@ -1994,7 +1999,7 @@ 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{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 @@ -2062,7 +2067,7 @@ 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. +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 @@ -2078,7 +2083,8 @@ 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}.) +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.