Update of Mode Line Format in the Lisp Reference Manual.

[Lute Kamstra]

I've updated the Mode Line Format node of the Lisp Reference Manual.
I documented a couple of new features like the (:propertize elt
props...) construct and the mode-line-position and mode-line-modes
variables.  It would be nice if people involved in their
implementation would look at it before I commit the update.


  Lute.


Index: lispref/modes.texi
===================================================================
RCS file: /cvsroot/emacs/emacs/lispref/modes.texi,v
retrieving revision 1.63
diff -c -r1.63 modes.texi
*** lispref/modes.texi  8 Sep 2003 07:59:06 -0000       1.63
--- lispref/modes.texi  25 Sep 2003 15:32:13 -0000
***************
*** 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
***************
*** 1191,1200 ****
  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.
--- 1191,1202 ----
  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.
***************
*** 1231,1236 ****
--- 1233,1246 ----
  @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
***************
*** 1312,1324 ****
  @code{mode-line-format} were changed to use them.
  
  @defvar mode-line-mule-info
! This variable holds the value of the mode-line construct that displays
  information about the language environment, buffer coding system, and
  current input method.  @xref{Non-ASCII Characters}.
  @end defvar
  
  @defvar mode-line-modified
! This variable holds the value of the mode-line construct that displays
  whether the current buffer is modified.
  
  The default value of @code{mode-line-modified} is @code{("%1*%1+")}.
--- 1322,1334 ----
  @code{mode-line-format} were changed to use them.
  
  @defvar mode-line-mule-info
! This variable holds the value of the mode line construct that displays
  information about the language environment, buffer coding system, and
  current input method.  @xref{Non-ASCII Characters}.
  @end defvar
  
  @defvar mode-line-modified
! This variable holds the value of the mode line construct that displays
  whether the current buffer is modified.
  
  The default value of @code{mode-line-modified} is @code{("%1*%1+")}.
***************
*** 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,1427 ----
  with spaces to at least 12 columns.
  @end defvar
  
! @defvar mode-line-position
! This variable indicates the position in the buffer.  The default value
! (with text properties omitted) is:
  
! @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.  Its default
! value (with text properties omitted) is:
! 
! @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
***************
*** 1377,1393 ****
  @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
  
--- 1438,1461 ----
  @var{minor-mode-variable} for a specific mode is set to a address@hidden
  value when that minor mode is activated.
  
! The default value (without text properties) of @code{minor-mode-alist}
! is:
  
  @example
  @group
! ((ispell-minor-mode " Spell")
!  (checkdoc-minor-mode " CDoc")
!  (view-mode " View")
! @end group
!  (server-buffer-clients " Server")
!  (visible-mode " Vis")
!  (flyspell-mode flyspell-mode-line-string)
!  (abbrev-mode " Abbrev")
!  (overwrite-mode overwrite-mode)
! @group
!  (auto-fill-function " Fill")
!  (defining-kbd-macro " Def")
!  (isearch-mode isearch-mode))
  @end group
  @end example
  
***************
*** 1396,1420 ****
  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
--- 1464,1479 ----
  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
--- 1484,1491 ----
  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 (text
! properties omitted):
  
  @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
--- 1496,1508 ----
   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
***************
*** 1500,1507 ****
  
  @item %p
  The percentage of the buffer text above the @strong{top} of window, or
! @samp{Top}, @samp{Bottom} or @samp{All}.  Note that the default
! mode-line specification truncates this to three characters.
  
  @item %P
  The percentage of the buffer text that is above the @strong{bottom} of
--- 1550,1557 ----
  
  @item %p
  The percentage of the buffer text above the @strong{top} of window, or
! @samp{Top}, @samp{Bottom} or @samp{All}.  Note that the default mode
! line specification truncates this to three characters.
  
  @item %P
  The percentage of the buffer text that is above the @strong{bottom} of
***************
*** 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
--- 1614,1646 ----
  
  @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
***************
*** 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}.
  
--- 2268,2274 ----
  @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}.