bug#57080: 29.0.60; [PATCH] Updates to mode line construct documentation (was: The %m modeline construct does not work for emacs-lisp-mode)

[Phil Sainty <psainty@orcon.net.nz>]

[-- Attachment #1: Type: text/plain, Size: 4727 bytes --]

Does anyone object to me merging branch 
fix/bug-57080-mode-line-format-docs
( https://lists.gnu.org/archive/html/emacs-diffs/2023-03/msg00453.html )
to the emacs-29 branch?

It addresses the issue from this bug along with several related things
that I found in the process of looking at that.

* The %m documentation was not entirely accurate (as discussed here).
* The %M documentation was also not up to date.
* The %t construct was obsolete but still documented.
* The %o and %q constructs were lacking documentation.
* The `mode-line-format' docstring for all of the constructs was
   not as easy to read as it could have been.

I'm attaching the patch series.  The individual commit messages have
more details.

The final reformatting of the `mode-line-format' docstring sorts the
constructs by letter (which makes everything easier to find); eliminates
multiple constructs being crammed into single lines (which also makes
everything easier to find); and rephrases some things for (IMHO) easier
readability and comprehension.

This is the 'before' state:

   %b -- print buffer name.      %f -- print visited file name.
   %F -- print frame name.
   %* -- print %, * or hyphen.   %+ -- print *, % or hyphen.
	%& is like %*, but ignore read-only-ness.
	% means buffer is read-only and * means it is modified.
	For a modified read-only buffer, %* gives % and %+ gives *.
   %s -- print process status.   %l -- print the current line number.
   %c -- print the current column number (this makes editing slower).
         Columns are numbered starting from the left margin, and the
         leftmost column is displayed as zero.
         To make the column number update correctly in all cases,
	`column-number-mode' must be non-nil.
   %C -- Like %c, but the leftmost column is displayed as one.
   %i -- print the size of the buffer.
   %I -- like %i, but use k, M, G, etc., to abbreviate.
   %o -- print percent of window travel through buffer, or Top, Bot or 
All.
   %p -- print percent of buffer above top of window, or Top, Bot or All.
   %P -- print percent of buffer above bottom of window, perhaps plus 
Top,
         or print Bottom or All.
   %q -- print percent of buffer above both the top and the bottom of the
         window, separated by ‘-’, or ‘All’.
   %n -- print Narrow if appropriate.
   %z -- print mnemonics of keyboard, terminal, and buffer coding 
systems.
   %Z -- like %z, but including the end-of-line format.
   %e -- print error message about full memory.
   %@ -- print @ or hyphen.  @ means that default-directory is on a
         remote machine.
   %[ -- print one [ for each recursive editing level.  %] similar.
   %% -- print %.   %- -- print infinitely many dashes.


And this is the 'after' state (which is only 3 lines longer):

   %b -- print buffer name.
   %c -- print the current column number (this makes editing slower).
         Columns are numbered starting from the left margin, and the
         leftmost column is displayed as zero.
         To make the column number update correctly in all cases,
         `column-number-mode' must be non-nil.
   %C -- Like %c, but the leftmost column is displayed as one.
   %e -- print error message about full memory.
   %f -- print visited file name.
   %F -- print frame name.
   %i -- print the size of the buffer.
   %I -- like %i, but use k, M, G, etc., to abbreviate.
   %l -- print the current line number.
   %n -- print Narrow if appropriate.
   %o -- print percent of window travel through buffer, or Top, Bot or 
All.
   %p -- print percent of buffer above top of window, or Top, Bot or All.
   %P -- print percent of buffer above bottom of window, perhaps plus 
Top,
         or print Bottom or All.
   %q -- print percent of buffer above both the top and the bottom of the
         window, separated by ‘-’, or ‘All’.
   %s -- print process status.
   %z -- print mnemonics of keyboard, terminal, and buffer coding 
systems.
   %Z -- like %z, but including the end-of-line format.
   %& -- print * if the buffer is modified, otherwise hyphen.
   %+ -- print *, % or hyphen (modified, read-only, neither).
   %* -- print %, * or hyphen (read-only, modified, neither).
         For a modified read-only buffer, %+ prints * and %* prints %.
   %@ -- print @ if default-directory is on a remote machine, else 
hyphen.
   %[ -- print one [ for each recursive editing level.
   %] -- print one ] for each recursive editing level.
   %- -- print enough dashes to fill the mode line.
   %% -- print %.


I untabified the indentation, as that didn't render correctly with a
tab-width of anything other than 8, which might be a problem for other
docstrings as well.  Should help-mode set tab-width to 8 ??


-Phil

[-- Attachment #2: 0001-src-buffer.c-mode-line-format-Remove-docs-for-obsole.patch --]
[-- Type: text/x-diff, Size: 1514 bytes --]

From d1de8f6dd8de9de80dc3574dd06eec1801436c4c Mon Sep 17 00:00:00 2001
From: Phil Sainty <psainty@orcon.net.nz>
Date: Sun, 14 Aug 2022 22:34:41 +1200
Subject: [PATCH 1/5] * src/buffer.c (mode-line-format): Remove docs for
 obsolete %t construct

This documentation had been previously removed in 1999 in [1]
but was subsequently restored again in a different form in 2006
in [2] as the construct was still supported on some systems.
However it looks like it hasn't done what that documentation
indicated since [3] in 2011, and the final remnant of this
functionality was removed in [4] in 2013; so it seems clear that
it's no longer supported and shouldn't be documented now.

[1] commit 08de62001945d4dd32a3d6af44da05804cb296d5
[2] commit dafbe726b89a36010f3f24bb1efe4ace0a5f7f0f
[3] commit 05c652517317d10690aaf0a6aa0bc876382b9d82
[4] commit 8549f9e89bd9288c4c709d183a5bf8f07dbeed3d
---
 src/buffer.c | 1 -
 1 file changed, 1 deletion(-)

diff --git a/src/buffer.c b/src/buffer.c
index df1f5206668..3bcd387f0c5 100644
--- a/src/buffer.c
+++ b/src/buffer.c
@@ -5143,7 +5143,6 @@ syms_of_buffer (void)
   %P -- print percent of buffer above bottom of window, perhaps plus Top,
         or print Bottom or All.
   %n -- print Narrow if appropriate.
-  %t -- visited file is text or binary (if OS supports this distinction).
   %z -- print mnemonics of keyboard, terminal, and buffer coding systems.
   %Z -- like %z, but including the end-of-line format.
   %e -- print error message about full memory.
-- 
2.17.1


[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #3: 0002-src-buffer.c-mode-line-format-Document-o-and-q-const.patch --]
[-- Type: text/x-diff; charset=us-ascii; name=0002-src-buffer.c-mode-line-format-Document-o-and-q-const.patch, Size: 1245 bytes --]

From d160933bca201cf252c225919d404517f55ca8de Mon Sep 17 00:00:00 2001
From: Phil Sainty <psainty@orcon.net.nz>
Date: Sun, 14 Aug 2022 23:11:43 +1200
Subject: [PATCH 2/5] * src/buffer.c (mode-line-format): Document %o and %q
 constructs

Missed from commit b0b02ca7f3e06d0f092df6f81babd1277bf93b0f.
---
 src/buffer.c | 3 +++
 1 file changed, 3 insertions(+)

diff --git a/src/buffer.c b/src/buffer.c
index 3bcd387f0c5..0c740775e5b 100644
--- a/src/buffer.c
+++ b/src/buffer.c
@@ -5139,9 +5139,12 @@ syms_of_buffer (void)
   %C -- Like %c, but the leftmost column is displayed as one.
   %i -- print the size of the buffer.
   %I -- like %i, but use k, M, G, etc., to abbreviate.
+  %o -- print percent of window travel through buffer, or Top, Bot or All.
   %p -- print percent of buffer above top of window, or Top, Bot or All.
   %P -- print percent of buffer above bottom of window, perhaps plus Top,
         or print Bottom or All.
+  %q -- print percent of buffer above both the top and the bottom of the
+        window, separated by ‘-’, or ‘All’.
   %n -- print Narrow if appropriate.
   %z -- print mnemonics of keyboard, terminal, and buffer coding systems.
   %Z -- like %z, but including the end-of-line format.
-- 
2.17.1


[-- Attachment #4: 0003-Improve-docs-for-global-mode-string-M-construct.patch --]
[-- Type: text/x-diff, Size: 3074 bytes --]

From 6ef00bb9ef6aa016e306925391d4753cf99515ab Mon Sep 17 00:00:00 2001
From: Phil Sainty <psainty@orcon.net.nz>
Date: Sun, 14 Aug 2022 23:14:51 +1200
Subject: [PATCH 3/5] Improve docs for global-mode-string / %M construct

* src/xdisp.c (global-mode-string): Update docstring.
* doc/lispref/modes.texi: Update manual.
---
 doc/lispref/modes.texi | 25 +++++++++++++++----------
 src/xdisp.c            |  2 +-
 2 files changed, 16 insertions(+), 11 deletions(-)

diff --git a/doc/lispref/modes.texi b/doc/lispref/modes.texi
index fff1ea65b07..30baa7f4d80 100644
--- a/doc/lispref/modes.texi
+++ b/doc/lispref/modes.texi
@@ -2349,18 +2349,19 @@ Mode Line Variables
 
 @defvar global-mode-string
 This variable holds a mode line construct that, by default, appears in
-the mode line just after the @code{which-function-mode} minor mode if
-set, else after @code{mode-line-modes}.  Elements that are added to
-this construct should normally end in a space (to ensure that
-consecutive @code{global-mode-string} elements display properly).  For
-instance, 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 mode line as part of @code{mode-line-misc-info}, just after the
+@code{which-function-mode} information if that minor mode is enabled,
+else after @code{mode-line-modes}.  Elements that are added to this
+construct should normally end in a space (to ensure that consecutive
+@code{global-mode-string} elements display properly).  For instance,
+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}.
+@code{global-mode-string}.  This construct is not used by the default
+mode line, as the variable itself is used in
+@code{mode-line-misc-info}.
 @end defvar
 
 Here is a simplified version of the default value of
@@ -2440,6 +2441,10 @@ %-Constructs
 The current line number of point, counting within the accessible portion
 of the buffer.
 
+@item %M
+The value of @code{global-mode-string} (which is part of
+@code{mode-line-misc-info} by default).
+
 @item %n
 @samp{Narrow} when narrowing is in effect; nothing otherwise (see
 @code{narrow-to-region} in @ref{Narrowing}).
diff --git a/src/xdisp.c b/src/xdisp.c
index 6219bb9ec6e..0b190529404 100644
--- a/src/xdisp.c
+++ b/src/xdisp.c
@@ -36470,7 +36470,7 @@ syms_of_xdisp (void)
   Vinhibit_redisplay = Qnil;
 
   DEFVAR_LISP ("global-mode-string", Vglobal_mode_string,
-    doc: /* String (or mode line construct) included (normally) in `mode-line-format'.  */);
+    doc: /* String (or mode line construct) included (normally) in `mode-line-misc-info'.  */);
   Vglobal_mode_string = Qnil;
 
   DEFVAR_LISP ("overlay-arrow-position", Voverlay_arrow_position,
-- 
2.17.1


[-- Attachment #5: 0004-doc-lispref-modes.texi-Improve-docs-for-obsolete-m-c.patch --]
[-- Type: text/x-diff, Size: 1466 bytes --]

From b2225d849c58ec68bf1dba325aad25505a053455 Mon Sep 17 00:00:00 2001
From: Phil Sainty <psainty@orcon.net.nz>
Date: Sun, 14 Aug 2022 23:16:48 +1200
Subject: [PATCH 4/5] * doc/lispref/modes.texi: Improve docs for obsolete '%m'
 construct

Bug #57080.
---
 doc/lispref/modes.texi | 15 ++++++---------
 1 file changed, 6 insertions(+), 9 deletions(-)

diff --git a/doc/lispref/modes.texi b/doc/lispref/modes.texi
index 30baa7f4d80..3da716a3b8a 100644
--- a/doc/lispref/modes.texi
+++ b/doc/lispref/modes.texi
@@ -2441,6 +2441,12 @@ %-Constructs
 The current line number of point, counting within the accessible portion
 of the buffer.
 
+@item %m
+Obsolete; use the @code{mode-name} variable instead.  The @code{%m}
+construct is still supported, but it is inadequate, as it produces an
+empty string if the value of @code{mode-name} is a non-string
+mode-line construct (as in @code{emacs-lisp-mode}, for example).
+
 @item %M
 The value of @code{global-mode-string} (which is part of
 @code{mode-line-misc-info} by default).
@@ -2515,15 +2521,6 @@ %-Constructs
 string in which @code{%}-constructs are allowed.
 @end table
 
-The following @code{%}-construct is still supported, but it is
-obsolete, since you can get the same result using the variable
-@code{mode-name}.
-
-@table @code
-@item %m
-The value of @code{mode-name}.
-@end table
-
 @node Properties in Mode
 @subsection Properties in the Mode Line
 @cindex text properties in the mode line
-- 
2.17.1


[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #6: 0005-src-buffer.c-mode-line-format-Reorder-and-reformat-c.patch --]
[-- Type: text/x-diff; charset=us-ascii; name=0005-src-buffer.c-mode-line-format-Reorder-and-reformat-c.patch, Size: 4744 bytes --]

From e1ad7b86e148dd31133e6d3b7927b985a23e1979 Mon Sep 17 00:00:00 2001
From: Phil Sainty <psainty@orcon.net.nz>
Date: Sun, 14 Aug 2022 23:17:38 +1200
Subject: [PATCH 5/5] * src/buffer.c (mode-line-format): Reorder and reformat
 %-construct docs

The original formatting dates back to the earliest commits.  It saved
a few lines but was harder to follow.  As windows are typically taller
now than the terminals of the time, this reformatting now makes better
sense for readabiity.

* doc/lispref/modes.texi: Order change for consistency.  Add index.
---
 doc/lispref/modes.texi |  7 ++++---
 src/buffer.c           | 31 +++++++++++++++++--------------
 2 files changed, 21 insertions(+), 17 deletions(-)

diff --git a/doc/lispref/modes.texi b/doc/lispref/modes.texi
index 3da716a3b8a..c3abba368aa 100644
--- a/doc/lispref/modes.texi
+++ b/doc/lispref/modes.texi
@@ -2390,6 +2390,7 @@ Mode Line Variables
 
 @node %-Constructs
 @subsection @code{%}-Constructs in the Mode Line
+@cindex @code{%}-constructs in the mode line
 
   Strings used as mode line constructs can use certain
 @code{%}-constructs to substitute various kinds of data.  The
@@ -2486,6 +2487,9 @@ %-Constructs
 @item %Z
 Like @samp{%z}, but including the end-of-line format.
 
+@item %&
+@samp{*} if the buffer is modified, and @samp{-} otherwise.
+
 @item %*
 @samp{%} if the buffer is read only (see @code{buffer-read-only}); @*
 @samp{*} if the buffer is modified (see @code{buffer-modified-p}); @*
@@ -2497,9 +2501,6 @@ %-Constructs
 @samp{-} otherwise.  This differs from @samp{%*} only for a modified
 read-only buffer.  @xref{Buffer Modification}.
 
-@item %&
-@samp{*} if the buffer is modified, and @samp{-} otherwise.
-
 @item %@@
 @samp{@@} if the buffer's @code{default-directory} (@pxref{File Name
 Expansion}) is on a remote machine, and @samp{-} otherwise.
diff --git a/src/buffer.c b/src/buffer.c
index 0c740775e5b..31c08cf3650 100644
--- a/src/buffer.c
+++ b/src/buffer.c
@@ -5124,35 +5124,38 @@ syms_of_buffer (void)
  negative) to the width specified by that number.
 
 A string is printed verbatim in the mode line except for %-constructs:
-  %b -- print buffer name.      %f -- print visited file name.
-  %F -- print frame name.
-  %* -- print %, * or hyphen.   %+ -- print *, % or hyphen.
-	%& is like %*, but ignore read-only-ness.
-	% means buffer is read-only and * means it is modified.
-	For a modified read-only buffer, %* gives % and %+ gives *.
-  %s -- print process status.   %l -- print the current line number.
+  %b -- print buffer name.
   %c -- print the current column number (this makes editing slower).
         Columns are numbered starting from the left margin, and the
         leftmost column is displayed as zero.
         To make the column number update correctly in all cases,
-	`column-number-mode' must be non-nil.
+        `column-number-mode' must be non-nil.
   %C -- Like %c, but the leftmost column is displayed as one.
+  %e -- print error message about full memory.
+  %f -- print visited file name.
+  %F -- print frame name.
   %i -- print the size of the buffer.
   %I -- like %i, but use k, M, G, etc., to abbreviate.
+  %l -- print the current line number.
+  %n -- print Narrow if appropriate.
   %o -- print percent of window travel through buffer, or Top, Bot or All.
   %p -- print percent of buffer above top of window, or Top, Bot or All.
   %P -- print percent of buffer above bottom of window, perhaps plus Top,
         or print Bottom or All.
   %q -- print percent of buffer above both the top and the bottom of the
         window, separated by ‘-’, or ‘All’.
-  %n -- print Narrow if appropriate.
+  %s -- print process status.
   %z -- print mnemonics of keyboard, terminal, and buffer coding systems.
   %Z -- like %z, but including the end-of-line format.
-  %e -- print error message about full memory.
-  %@ -- print @ or hyphen.  @ means that default-directory is on a
-        remote machine.
-  %[ -- print one [ for each recursive editing level.  %] similar.
-  %% -- print %.   %- -- print infinitely many dashes.
+  %& -- print * if the buffer is modified, otherwise hyphen.
+  %+ -- print *, % or hyphen (modified, read-only, neither).
+  %* -- print %, * or hyphen (read-only, modified, neither).
+        For a modified read-only buffer, %+ prints * and %* prints %.
+  %@ -- print @ if default-directory is on a remote machine, else hyphen.
+  %[ -- print one [ for each recursive editing level.
+  %] -- print one ] for each recursive editing level.
+  %- -- print enough dashes to fill the mode line.
+  %% -- print %.
 Decimal digits after the % specify field width to which to pad.  */);
 
   DEFVAR_PER_BUFFER ("major-mode", &BVAR (current_buffer, major_mode),
-- 
2.17.1