changeset 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.

--- 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.