[Emacs-diffs] Changes to emacs/lispref/modes.texi

[Lute Kamstra]

Index: emacs/lispref/modes.texi
diff -c emacs/lispref/modes.texi:1.63 emacs/lispref/modes.texi:1.64
*** emacs/lispref/modes.texi:1.63       Mon Sep  8 03:59:06 2003
--- emacs/lispref/modes.texi    Fri Sep 26 08:15:32 2003
***************
*** 274,280 ****
  but this is not required.  Such a mode should use
  @code{delay-mode-hooks} around its entire body, including the call to
  the parent mode command and the final call to @code{run-mode-hooks}.
! (Using @code{define-derived-mode} does this automatically.) 
  
  @item
  If something special should be done if the user switches a buffer from
--- 274,280 ----
  but this is not required.  Such a mode should use
  @code{delay-mode-hooks} around its entire body, including the call to
  the parent mode command and the final call to @code{run-mode-hooks}.
! (Using @code{define-derived-mode} does this automatically.)
  
  @item
  If something special should be done if the user switches a buffer from
***************
*** 1101,1107 ****
  @end smallexample
  
  @node Mode Line Format
! @section Mode Line Format
  @cindex mode line
  
    Each Emacs window (aside from minibuffer windows) typically has a mode
--- 1101,1107 ----
  @end smallexample
  
  @node Mode Line Format
! @section Mode-Line Format
  @cindex mode line
  
    Each Emacs window (aside from minibuffer windows) typically has a mode
***************
*** 1166,1202 ****
  
  @node Mode Line Data
  @subsection The Data Structure of the Mode Line
! @cindex mode line construct
  
!   The mode line contents are controlled by a data structure of lists,
  strings, symbols, and numbers kept in buffer-local variables.  The data
! structure is called a @dfn{mode line construct}, and it is built in
! recursive fashion out of simpler mode line constructs.  The same data
  structure is used for constructing frame titles (@pxref{Frame Titles})
  and header lines (@pxref{Header Lines}).
  
  @defvar mode-line-format
! The value of this variable is a mode line construct with overall
! 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
  it usually specifies how to use other variables to construct the text.
! Many of these variables are themselves defined to have mode line
  constructs as their values.
  
    The default value of @code{mode-line-format} incorporates the values
! of variables such as @code{mode-name} and @code{minor-mode-alist}.
! Because of this, very few modes need to alter @code{mode-line-format}
! itself.  For most purposes, it is sufficient to alter some of the
! variables that @code{mode-line-format} refers to.
  
!   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
--- 1166,1204 ----
  
  @node Mode Line Data
  @subsection The Data Structure of the Mode Line
! @cindex mode-line construct
  
!   The mode-line contents are controlled by a data structure of lists,
  strings, symbols, and numbers kept in buffer-local variables.  The data
! structure is called a @dfn{mode-line construct}, and it is built in
! recursive fashion out of simpler mode-line constructs.  The same data
  structure is used for constructing frame titles (@pxref{Frame Titles})
  and header lines (@pxref{Header Lines}).
  
  @defvar mode-line-format
! The value of this variable is a mode-line construct with overall
! 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
  it usually specifies how to use other variables to construct the text.
! Many of these variables are themselves defined to have mode-line
  constructs as their values.
  
    The default value of @code{mode-line-format} incorporates the values
! of variables such as @code{mode-line-position} and
! @code{mode-line-modes} (which in turn incorporates the values of the
! variables @code{mode-name} and @code{minor-mode-alist}).  Because of
! this, very few modes need to alter @code{mode-line-format} itself.  For
! most purposes, it is sufficient to alter some of the variables that
! @code{mode-line-format} either directly or indirectly refers to.
  
!   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
***************
*** 1207,1220 ****
  @table @code
  @cindex percent symbol in mode line
  @item @var{string}
! A string as a mode line construct is displayed verbatim in the mode line
  except for @address@hidden  Decimal digits after the @samp{%}
  specify the field width for space filling on the right (i.e., the data
  is left justified).  @xref{%-Constructs}.
  
  @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, as is any
  symbol whose value is void.
  
--- 1209,1222 ----
  @table @code
  @cindex percent symbol in mode line
  @item @var{string}
! A string as a mode-line construct is displayed verbatim in the mode line
  except for @address@hidden  Decimal digits after the @samp{%}
  specify the field width for space filling on the right (i.e., the data
  is left justified).  @xref{%-Constructs}.
  
  @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, as is any
  symbol whose value is void.
  
***************
*** 1224,1249 ****
  @item (@var{string} @address@hidden) @r{or} (@var{list} @address@hidden)
  A list whose first element is a string or list means to process all the
  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 that is not a keyword specifies a
  conditional.  Its meaning depends on the value of @var{symbol}.  If the
  value is address@hidden, 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} @address@hidden)
  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 @address@hidden columns,
  if @var{width} is negative) on the right.
--- 1226,1259 ----
  @item (@var{string} @address@hidden) @r{or} (@var{list} @address@hidden)
  A list whose first element is a string or list means to process all the
  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 (:propertize @var{elt} @address@hidden)
+ A list whose first element is the symbol @code{:propertize} says to
+ process the mode-line construct @var{elt} recursively and add the text
+ properties specified by @var{props} to the result.  The argument
+ @var{props} should consist of zero or more pairs @var{text-property}
+ @var{value}.  (This feature is new as of Emacs 21.4.)
+ @c FIXME: This might be Emacs 21.5.
+ 
  @item (@var{symbol} @var{then} @var{else})
  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 address@hidden, 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} @address@hidden)
  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 @address@hidden columns,
  if @var{width} is negative) on the right.
***************
*** 1275,1281 ****
  @end group
  @group
     ;; @r{Note that this is evaluated while making the list.}
!    ;; @r{It makes a mode line construct which is just a string.}
     (getenv "HOST")
  @end group
     ":"
--- 1285,1291 ----
  @end group
  @group
     ;; @r{Note that this is evaluated while making the list.}
!    ;; @r{It makes a mode-line construct which is just a string.}
     (getenv "HOST")
  @end group
     ":"
***************
*** 1332,1339 ****
  
  @defvar mode-line-frame-identification
  This variable identifies the current frame.  The default value is
! @code{" "} if you are using a window system which can show multiple
! frames, or @code{"-%F "} on an ordinary terminal which shows only one
  frame at a time.
  @end defvar
  
--- 1342,1349 ----
  
  @defvar mode-line-frame-identification
  This variable identifies the current frame.  The default value is
! @code{"  "} if you are using a window system which can show multiple
! frames, or @code{"-%F  "} on an ordinary terminal which shows only one
  frame at a time.
  @end defvar
  
***************
*** 1343,1366 ****
  with spaces to at least 12 columns.
  @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}
! sets @code{global-mode-string} to refer to the variable
! @code{display-time-string}, which holds a string containing the time and
! load information.
  
! The @samp{%M} construct substitutes the value of
! @code{global-mode-string}, but that is obsolete, since the variable is
! included in the mode line from @code{mode-line-format}.
  @end defvar
  
  @defvar mode-name
  This buffer-local variable holds the ``pretty'' name of the current
  buffer's major mode.  Each major mode should set this variable so that the
  mode name will appear in the mode line.
  @end defvar
  
  @defvar 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
--- 1353,1426 ----
  with spaces to at least 12 columns.
  @end defvar
  
! @defvar mode-line-position
! This variable indicates the position in the buffer.  Here is a
! simplified version of its default value.  The actual default value
! also specifies addition of the @code{help-echo} text property.
  
! @example
! @group
! ((-3 . "%p")
!  (size-indication-mode (8 " of %I"))
! @end group
! @group
!  (line-number-mode
!   ((column-number-mode
!     (10 " (%l,%c)")
!     (6 " L%l")))
!   ((column-number-mode
!     (5 " C%c")))))
! @end group
! @end example
! 
! This means that @code{mode-line-position} displays at least the buffer
! percentage and possibly the buffer size, the line number and the column
! number.
  @end defvar
  
+ @defvar vc-mode
+ The variable @code{vc-mode}, buffer-local in each buffer, records
+ whether the buffer's visited file is maintained with version control,
+ and, if so, which kind.  Its value is a string that appears in the mode
+ line, or @code{nil} for no version control.
+ @end defvar
+ 
+ @defvar mode-line-modes
+ This variable displays the buffer's major and minor modes.  Here is a
+ simplified version of its default value.  The real default value also
+ specifies addition of text properties.
+ 
+ @example
+ @group
+ ("%[(" mode-name
+  mode-line-process minor-mode-alist
+  "%n" ")%]--")
+ @end group
+ @end example
+ 
+ So @code{mode-line-modes} normally also displays the recursive editing
+ level, information on the process status and whether narrowing is in
+ effect.
+ @end defvar
+ 
+   The following three variables are used in @code{mode-line-modes}:
+ 
  @defvar mode-name
  This buffer-local variable holds the ``pretty'' name of the current
  buffer's major mode.  Each major mode should set this variable so that the
  mode name will appear in the mode line.
  @end defvar
  
+ @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 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
***************
*** 1370,1420 ****
  (@var{minor-mode-variable} @var{mode-line-string})
  @end example
  
! More generally, @var{mode-line-string} can be any mode line spec.  It
! appears in the mode line when the value of @var{minor-mode-variable} is
! address@hidden, and not otherwise.  These strings should begin with
  spaces so that they don't run together.  Conventionally, the
! @var{minor-mode-variable} for a specific mode is set to a address@hidden
! value when that minor mode is activated.
! 
! The default value of @code{minor-mode-alist} is:
! 
! @example
! @group
! minor-mode-alist
! @result{} ((vc-mode vc-mode)
!     (abbrev-mode " Abbrev")
!     (overwrite-mode overwrite-mode)
!     (auto-fill-function " Fill")
!     (defining-kbd-macro " Def")
!     (isearch-mode isearch-mode))
! @end group
! @end example
  
  @code{minor-mode-alist} itself is not buffer-local.  Each variable
  mentioned in the alist should be buffer-local if its minor mode can be
  enabled separately in each buffer.
  @end defvar
  
! @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
! 
!   Some variables are used by @code{minor-mode-alist} to display
! a string for various minor modes when enabled.  This is a typical
! example:
  
! @defvar vc-mode
! The variable @code{vc-mode}, buffer-local in each buffer, records
! whether the buffer's visited file is maintained with version control,
! and, if so, which kind.  Its value is a string that appears in the mode
! line, or @code{nil} for no version control.
  @end defvar
  
    The variable @code{default-mode-line-format} is where
--- 1430,1457 ----
  (@var{minor-mode-variable} @var{mode-line-string})
  @end example
  
! More generally, @var{mode-line-string} can be any mode-line spec.  It
! appears in the mode line when the value of @var{minor-mode-variable}
! is address@hidden, and not otherwise.  These strings should begin with
  spaces so that they don't run together.  Conventionally, the
! @var{minor-mode-variable} for a specific mode is set to a
! address@hidden value when that minor mode is activated.
  
  @code{minor-mode-alist} itself is not buffer-local.  Each variable
  mentioned in the alist should be buffer-local if its minor mode can be
  enabled separately in each buffer.
  @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}
! sets @code{global-mode-string} to refer to the variable
! @code{display-time-string}, which holds a string containing the time and
! load information.
  
! The @samp{%M} construct substitutes the value of
! @code{global-mode-string}, but that is obsolete, since the variable is
! included in the mode line from @code{mode-line-format}.
  @end defvar
  
    The variable @code{default-mode-line-format} is where
***************
*** 1425,1431 ****
  that do not override it.  This is the same as @code{(default-value
  'mode-line-format)}.
  
! The default value of @code{default-mode-line-format} is this list:
  
  @example
  @group
--- 1462,1470 ----
  that do not override it.  This is the same as @code{(default-value
  'mode-line-format)}.
  
! Here is a simplified version of the default value of
! @code{default-mode-line-format}.  The real default value also
! specifies addition of text properties.
  
  @example
  @group
***************
*** 1436,1458 ****
   mode-line-buffer-identification
  @end group
   "   "
!  global-mode-string
! @group
!  "   %[("
!  ;; @address@hidden is a function}
!  ;; @r{that copies the mode name and adds text}
!  ;; @r{properties to make it mouse-sensitive.}
!  (:eval (mode-line-mode-name))
!  mode-line-process
!  minor-mode-alist
!  "%n"
!  ")%]--"
! @end group
  @group
   (which-func-mode ("" which-func-format "--"))
!  (line-number-mode "L%l--")
!  (column-number-mode "C%c--")
!  (-3 . "%p")
   "-%-")
  @end group
  @end example
--- 1475,1487 ----
   mode-line-buffer-identification
  @end group
   "   "
!  mode-line-position
!  (vc-mode vc-mode)
!  "   "
  @group
+  mode-line-modes
   (which-func-mode ("" which-func-format "--"))
!  (global-mode-string ("--" global-mode-string))
   "-%-")
  @end group
  @end example
***************
*** 1564,1592 ****
  
  @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
--- 1593,1625 ----
  
  @node Properties in Mode
  @subsection Properties in the Mode Line
+ @cindex text 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 four ways to specify text properties for text in the mode
  line:
  
  @enumerate
  @item
! Put a string with a text property directly into the mode-line data
! structure.
! 
! @item
! Put a text 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 @code{(:propertize @var{elt} @address@hidden)} construct to
! give @var{elt} a text property specified by @var{props}.
  
  @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 text
! property.
  @end enumerate
  
    You use the @code{local-map} property to specify a keymap.  Like any
***************
*** 1601,1607 ****
  
    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
--- 1634,1640 ----
  
    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
***************
*** 1621,1631 ****
  @end defvar
  
  @node Emulating Mode Line
! @subsection Emulating Mode Line Formatting
  
    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.
  
  @defun format-mode-line &optional format window no-props
  This function formats a line of text according to @var{format} as if
--- 1654,1664 ----
  @end defvar
  
  @node Emulating Mode Line
! @subsection Emulating Mode-Line Formatting
  
    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.
  
  @defun format-mode-line &optional format window no-props
  This function formats a line of text according to @var{format} as if
***************
*** 2214,2220 ****
  @code{font-lock-face} (@pxref{Special Properties}).  This property
  acts just like the explicit @code{face} property, but its activation
  is toggled when the user calls @kbd{M-x font-lock-mode}.  Using
! @code{font-lock-face} is especially conveninent for special modes
  which construct their text programmatically, such as
  @code{list-buffers} and @code{occur}.
  
--- 2247,2253 ----
  @code{font-lock-face} (@pxref{Special Properties}).  This property
  acts just like the explicit @code{face} property, but its activation
  is toggled when the user calls @kbd{M-x font-lock-mode}.  Using
! @code{font-lock-face} is especially convenient for special modes
  which construct their text programmatically, such as
  @code{list-buffers} and @code{occur}.