Update of Mode Line Format in the Lisp Reference Manual.

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} @var{props}@dots{})
+ 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 non-@code{nil}
  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 non-@code{nil}
  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
!  "   %[("
!  ;; @r{@code{mode-line-mode-name} 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} @var{props}@dots{})} 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}.

Re: Update of Mode Line Format in the Lisp Reference Manual.

[Eli Zaretskii]

> From: Lute Kamstra <Lute.Kamstra@cwi.nl>
> Date: Thu, 25 Sep 2003 17:45:18 +0200
> 
> 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.

Thanks!

A few minor comments:

> + @item (:propertize @var{elt} @var{props}@dots{})
> + 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.

I think it's a good idea to add an index entry here, for users who
might be looking for information on putting text properties on
mode-line text.

In general, I'd suggest to re-read your changes and try to add index
entries for every piece of information that a user might need to find
quickly.  Think of programmers like you and me who need to write some
Lisp code related to the features you describe, but who do not know by
heart the names of functions/variables you are describing.

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

I see that you've consistently replaced "mode-line" with "mode line"
in this and similar contexts.  I'm not sure which variant is more
correct English; please note that the phrase "mode-line construct" can
be rephrased as "construct of the mode line".  I tend to write the
dash in the former, but not in the latter.  However, since English is
not my first language, I'll leave the decision to others.

> ! @defvar mode-line-position
> ! This variable indicates the position in the buffer.  The default value
> ! (with text properties omitted) is:

The Texinfo directive @defvar (as well as its other @def* brethren)
defines a @vindex entry for its argument, which is good.  However, if
a user looks for this information without knowing the name of the
variable, she will still be lost.  Thus, I think that, ideally, every
variable here should have a @cindex entry as well.  For example, the
variable mode-line-position might have these entries:

  @cindex buffer position indication, in mode line
  @cindex mode line, buffer position indication

Thanks again for all your work.

Re: Update of Mode Line Format in the Lisp Reference Manual.

[Richard Stallman]

    I see that you've consistently replaced "mode-line" with "mode line"
    in this and similar contexts.  I'm not sure which variant is more
    correct English; please note that the phrase "mode-line construct" can
    be rephrased as "construct of the mode line".  I tend to write the
    dash in the former, but not in the latter.

You are doing it right in both cases.

      Thus, I think that, ideally, every
    variable here should have a @cindex entry as well.  For example, the
    variable mode-line-position might have these entries:

      @cindex buffer position indication, in mode line
      @cindex mode line, buffer position indication

I think that is too much; it will make the index too big.  That makes
the index less useful and makes the manual more expensive to print.
Most of those index entries are not necessary.

This whole section is about the mode line.  As long as people can
easily find this section when they look for "mode line", that is good
enough.  It only needs one index entry about the mode line, for the
whole section.  So `@cindex mode line, buffer position indication' is
clearly unnecessary.

It is not so clear that `@cindex buffer position indication, in mode
line' is unnecessary, but I think it is.  If you want to find how to
display something in the mode line, you just need to find the section
about it.