diff lispref/modes.texi @ 25751:467b88fab665

*** empty log message ***

--- a/lispref/modes.texi	Fri Sep 17 06:53:20 1999 +0000
+++ b/lispref/modes.texi	Fri Sep 17 06:59:04 1999 +0000
@@ -61,7 +61,7 @@
   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
+temporary major mode usually provides 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
@@ -70,8 +70,8 @@
 alternative major mode avoids this limitation.  @xref{Recursive
 Editing}.
 
-  The standard GNU Emacs Lisp library directory contains the code for
-several major modes, in files such as @file{text-mode.el},
+  The standard GNU Emacs Lisp library directory tree contains the code
+for several major modes, in files such as @file{text-mode.el},
 @file{texinfo.el}, @file{lisp-mode.el}, @file{c-mode.el}, and
 @file{rmail.el}.  You can study these libraries to see how modes are
 written.  Text mode is perhaps the simplest major mode aside from
@@ -245,7 +245,7 @@
 @end example
 
 @noindent
-This tells Emacs that new buffers created while the current buffer has
+This tells Emacs that new buffers created while the current buffer is in
 Funny mode should not inherit Funny mode.  Modes such as Dired, Rmail,
 and Buffer List use this feature.
 
@@ -368,7 +368,7 @@
 @group
       ;; @r{Set syntax of chars up to 0 to class of chars that are}
       ;;   @r{part of symbol names but not words.}
-      ;;   @r{(The number 0 is @code{48} in the @sc{ASCII} character set.)}
+      ;;   @r{(The number 0 is @code{48} in the @sc{ascii} character set.)}
       (while (< i ?0) 
         (modify-syntax-entry i "_   " emacs-lisp-mode-syntax-table)
         (setq i (1+ i)))
@@ -782,7 +782,8 @@
 ``generally available, optional feature modes,'' except that such a name
 would be unwieldy.
 
-  A minor mode is not usually a modification of single major mode.  For
+  A minor mode is not usually meant as a variation of a single major mode.
+Usually they are general and can apply to many major modes.  For
 example, Auto Fill mode works with any major mode that permits text
 insertion.  To be general, a minor mode must be effectively independent
 of the things major modes do.
@@ -825,7 +826,7 @@
 should set this variable (@code{nil} to disable; anything else to
 enable).
 
-If it is possible, implement the mode so that setting the variable
+If 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.
 
@@ -890,6 +891,40 @@
   You can also use @code{add-to-list} to add an element to this list
 just once (@pxref{Setting Variables}).
 
+  Global minor modes distributed with Emacs should if possible support
+enabling and disabling via Custom (@pxref{Customization}).  To do this,
+the first step is to define the mode variable with @code{defcustom}, and
+specify @code{:type boolean}.
+
+  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
+invoke 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:
+
+@smallexample
+@group
+
+;;;###autoload
+(defcustom msb-mode nil
+  "Toggle msb-mode.
+Setting this variable directly does not take effect;
+use either \\[customize] or the function `msb-mode'."
+  :set (lambda (symbol value)
+	 (msb-mode (or value 0)))
+  :initialize 'custom-initialize-default
+  :version "20.4"
+  :type    'boolean
+  :group   'msb
+  :require 'msb)
+@end group
+@end smallexample
+
 @node Keymaps and Minor Modes
 @subsection Keymaps and Minor Modes
 
@@ -908,15 +943,15 @@
 
 The key sequences bound in a minor mode should consist of @kbd{C-c}
 followed by a punctuation character @emph{other than} @kbd{@{},
-@kbd{@}}, @kbd{<}, @kbd{>}, @kbd{:} or @kbd{;}.  (Those few punctuation
+@kbd{@}}, @kbd{<}, @kbd{>}, @kbd{:}, and @kbd{;}.  (Those few punctuation
 characters are reserved for major modes.)
 
 @node Easy-Mmode
 @subsection Easy-Mmode
 
   The easy-mmode package provides a convenient way of implementing a
-minor mode; with it, you can specify everything about a simple minor
-mode in one self-contained definition.
+mode in one self-contained definition.  It currently supports only
+buffer-local minor modes, not global ones.
 
 @defmac easy-mmode-define-minor-mode mode doc &optional init-value mode-indicator keymap
 @tindex easy-mmode-define-minor-mode
@@ -978,35 +1013,39 @@
 @section Mode Line Format
 @cindex mode line
 
-  Each Emacs window (aside from minibuffer windows) includes a mode line,
-which displays status information about the buffer displayed in the
-window.  The mode line contains information about the buffer, such as its
-name, associated file, depth of recursive editing, and the major and
-minor modes.
+  Each Emacs window (aside from minibuffer windows) typically has a mode
+line at the bottom, which displays status information about the buffer
+displayed in the window.  The mode line contains information about the
+buffer, such as its name, associated file, depth of recursive editing,
+and major and minor modes.  A window can also have a @dfn{header
+line}, which is much like the mode line but appears at the top of the
+window (starting in Emacs 21).
 
-  This section describes how the contents of the mode line are
-controlled.  We include it in this chapter because much of the
+  This section describes how to control the contents of the mode line
+and header line.  We include it in this chapter because much of the
 information displayed in the mode line relates to the enabled major and
 minor modes.
 
   @code{mode-line-format} is a buffer-local variable that holds a
 template used to display the mode line of the current buffer.  All
-windows for the same buffer use the same @code{mode-line-format} and
-their mode lines appear the same (except for scrolling percentages, and
-line and column numbers).
+windows for the same buffer use the same @code{mode-line-format}, so
+their mode lines appear the same---except for scrolling percentages, and
+line and column numbers, since those depend on point and on how the
+window is scrolled.  @code{header-line-format} is used likewise for
+header lines.
 
-  The mode line of a window is normally updated whenever a different
-buffer is shown in the window, or when the buffer's modified-status
-changes from @code{nil} to @code{t} or vice-versa.  If you modify any of
-the variables referenced by @code{mode-line-format} (@pxref{Mode Line
-Variables}), or any other variables and data structures that affect how
-text is displayed (@pxref{Display}), you may want to force an update of
-the mode line so as to display the new information or display it in
-the new way.
+  The mode line and header line of a window are normally updated
+whenever a different buffer is shown in the window, or when the buffer's
+modified-status changes from @code{nil} to @code{t} or vice-versa.  If
+you modify any of the variables referenced by @code{mode-line-format}
+(@pxref{Mode Line Variables}), or any other variables and data
+structures that affect how text is displayed (@pxref{Display}), you may
+want to force an update of the mode line so as to display the new
+information or display it in the new way.
 
 @c Emacs 19 feature
 @defun force-mode-line-update
-Force redisplay of the current buffer's mode line.
+Force redisplay of the current buffer's mode line and header line.
 @end defun
 
   The mode line is usually displayed in inverse video; see
@@ -1016,6 +1055,8 @@
 * Mode Line Data::        The data structure that controls the mode line.
 * Mode Line Variables::   Variables used in that data structure.
 * %-Constructs::          Putting information into a mode line.
+* Properties in Mode::    Using text properties in the mode line.
+* Header Lines::          Like a mode line, but at the top.
 @end menu
 
 @node Mode Line Data
@@ -1034,6 +1075,9 @@
 responsibility for the mode line format.  The value of this variable
 controls which other variables are used to form the mode line text, and
 where they appear.
+
+If you set this variable to @code{nil} in a buffer, that buffer does not
+have a mode line.  (This feature was added in Emacs 21.)
 @end defvar
 
   A mode line construct may be as simple as a fixed string of text, but
@@ -1050,6 +1094,11 @@
   A mode line construct may be a list, a symbol, or a string.  If the
 value is a list, each element may be a list, a symbol, or a string.
 
+  The mode line can display various faces, if the strings that control
+it have the @code{face} property.  @xref{Properties in Mode}.  In
+addition, the face @code{mode-line} is used as a default for the whole
+mode line (@pxref{Standard Faces}).
+
 @table @code
 @cindex percent symbol in mode line
 @item @var{string}
@@ -1061,7 +1110,7 @@
 @item @var{symbol}
 A symbol as a mode line construct stands for its value.  The value of
 @var{symbol} is used as a mode line construct, in place of @var{symbol}.
-However, the symbols @code{t} and @code{nil} are ignored; so is any
+However, the symbols @code{t} and @code{nil} are ignored, as is any
 symbol whose value is void.
 
 There is one exception: if the value of @var{symbol} is a string, it is
@@ -1072,14 +1121,19 @@
 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.
+(This feature is new as of Emacs 21.)
+
 @item (@var{symbol} @var{then} @var{else})
-A list whose first element is a symbol is a conditional.  Its meaning
-depends on the value of @var{symbol}.  If the value is non-@code{nil},
-the second element, @var{then}, is processed recursively as a mode line
-element.  But if the value of @var{symbol} is @code{nil}, the third
-element, @var{else}, is processed recursively.  You may omit @var{else};
-then the mode line element displays nothing if the value of @var{symbol}
-is @code{nil}.
+A list whose first element is a symbol that is not a keyword specifies a
+conditional.  Its meaning depends on the value of @var{symbol}.  If the
+value is non-@code{nil}, the second element, @var{then}, is processed
+recursively as a mode line element.  But if the value of @var{symbol} is
+@code{nil}, the third element, @var{else}, is processed recursively.
+You may omit @var{else}; then the mode line element displays nothing if
+the value of @var{symbol} is @code{nil}.
 
 @item (@var{width} @var{rest}@dots{})
 A list whose first element is an integer specifies truncation or
@@ -1124,7 +1178,7 @@
    "   "
    'global-mode-string
    "   %[("
-   'mode-name 
+   '(:eval (mode-line-mode-name))
    'mode-line-process  
    'minor-mode-alist 
    "%n" 
@@ -1268,7 +1322,7 @@
  global-mode-string
 @group
  "   %[("
- mode-name 
+ (:eval (mode-line-mode-name))
  mode-line-process
  minor-mode-alist 
  "%n" 
@@ -1315,7 +1369,8 @@
 The current column number of point.
 
 @item %l
-The current line number of point.
+The current line number of point, counting within the accessible portion
+of the buffer.
 
 @item %*
 @samp{%} if the buffer is read only (see @code{buffer-read-only}); @*
@@ -1383,6 +1438,64 @@
 @code{display-time} modifies the value of @code{global-mode-string}.
 @end table
 
+@node Properties in Mode
+@subsection Properties in the Mode Line
+
+  Starting in Emacs 21, 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 three ways to specify text properties for text in the mode
+line:
+
+@enumerate
+@item
+Put a string with the @code{local-map} property directly into the
+mode-line data structure.
+
+@item
+Put a @code{local-map} property on a mode-line %-construct
+such as @samp{%12b}; then the expansion of the %-construct
+will have that same text property.
+
+@item
+Use a list containing @code{:eval @var{form}} in the mode-line data
+structure, and make @var{form} evaluate to a string that has a
+@code{local-map} property.
+@end enumerate
+
+  You use the @code{local-map} property to specify a keymap.  Like any
+keymap, it can bind character keys and function keys; but that has no
+effect, since is impossible to move point into the mode line, This
+keymap can only take real effect for mouse clicks.
+
+@node Header Lines
+@subsection Window Header Lines
+@cindex header line (of a window)
+@cindex window header line
+
+  Starting in Emacs 21, a window can have a @dfn{header line} at the
+top, just as it can have a mode line at the bottom.  The header line
+feature works just like the mode line feature, except that it's
+controlled by different variables.
+
+@tindex header-line-format
+@defvar header-line-format
+This variable, local in every buffer, specifies how to display the
+header line, for windows displaying the buffer.  The format of the value
+is the same as for @code{mode-line-format} (@xref{Mode Line Data}).
+@end defvar
+
+@tindex default-header-line-format
+@defvar default-header-line-format
+This variable holds the default @code{header-line-format} for buffers
+that do not override it.  This is the same as @code{(default-value
+'header-line-format)}.
+
+It is normally @code{nil}, so that ordinary buffers have no header line.
+@end defvar
+
 @node Imenu
 @section Imenu
 
@@ -1390,9 +1503,10 @@
   @dfn{Imenu} is a feature that lets users select a definition or
 section in the buffer, from a menu which lists all of them, to go
 directly to that location in the buffer.  Imenu works by constructing a
-buffer index which lists the names and positions of the definitions or
-portions of in the buffer, so the user can pick one of them to move to.
-This section explains how to customize Imenu for a major mode.
+buffer index which lists the names and buffer positions of the
+definitions, or portions of the buffer, so the user can pick one of them
+to move to.  This section explains how to customize Imenu for a major
+mode.
 
   The usual and simplest way is to set the variable
 @code{imenu-generic-expression}:
@@ -1413,9 +1527,10 @@
 in the top level of the buffer index.
 
 The second item in the list, @var{regexp}, is a regular expression
-(@pxref{Regular Expressions}); wherever it matches, that is a definition
-to mention in the buffer index.  The third item, @var{subexp}, indicates
-which subexpression in @var{regexp} matches the definition's name.
+(@pxref{Regular Expressions}); anything in the buffer that it matches is
+considered a definition, to mention in the buffer index.  The third
+item, @var{subexp}, indicates which subexpression in @var{regexp}
+matches the definition's name.
 
 An element can also look like this:
 
@@ -1483,7 +1598,7 @@
 
 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
+inconvenient when the mode needs to limit the initial character
 of a name to a smaller set of characters than are allowed in the rest
 of a name.
 
@@ -1682,7 +1797,7 @@
 highlighted (instead of the entire text that @var{matcher} matched).
 
 @example
-;; @r{Highlight the @samp{bar} in each occurrences of @samp{fubar},}
+;; @r{Highlight the @samp{bar} in each occurrence of @samp{fubar},}
 ;; @r{using @code{font-lock-keyword-face}.}
 ("fu\\(bar\\)" . 1)
 @end example
@@ -1734,7 +1849,7 @@
 ;; @r{@code{foo-bar-face} should be a variable whose value is a face.}
 ("foo\\|bar" 0 foo-bar-face t)
 
-;; @r{Highlight the first subexpression within each occurrences}
+;; @r{Highlight the first subexpression within each occurrence}
 ;; @r{that the function @code{fubar-match} finds,}
 ;; @r{using the face which is the value of @code{fubar-face}.}
 (fubar-match 1 fubar-face)