bug#57080: 28.1; The %m modeline construct does not work for emacs-lisp-mode

bug#57080: 28.1; The %m modeline construct does not work for emacs-lisp-mode

[diredwolf]

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

The name of the major mode is not displayed correctly when using the %m
modeline construct. The name is displayed correctly for every mode
except elisp-mode.

Steps to reproduce :
- Launch emacs -q
- Evaluate this :: (setq-default mode-line-format "[%m]")

For every major mode you should see for example [Message] or [Dired by
name] or [Help] but for elisp-mode you get [].

In GNU Emacs 28.1 (build 1, aarch64-apple-darwin21.1.0, NS appkit-2113.00 Version 12.0.1 (Build 21A559))
of 2022-05-11 built on armbob.lan
Windowing system distributor 'Apple', version 10.3.2113
System Description:  macOS 12.5

Configured using:
'configure --with-ns '--enable-locallisppath=/Library/Application
Support/Emacs/${version}/site-lisp:/Library/Application
Support/Emacs/site-lisp' --with-modules'

Configured features:
ACL GMP GNUTLS JSON LIBXML2 MODULES NOTIFY KQUEUE NS PDUMPER THREADS
TOOLKIT_SCROLL_BARS ZLIB

Important settings:
  value of $LANG: en_FR.UTF-8
  locale-coding-system: utf-8-unix

Major mode: Org

Minor modes in effect:
  display-time-mode: t
  display-battery-mode: t
  global-git-commit-mode: t
  magit-auto-revert-mode: t
  shell-dirtrack-mode: t
  global-org-modern-mode: t
  org-modern-mode: t
  meow-global-mode: t
  meow-mode: t
  meow-normal-mode: t
  marginalia-mode: t
  vertico-mode: t
  pulsar-global-mode: t
  pulsar-mode: t
  savehist-mode: t
  save-place-mode: t
  global-auto-revert-mode: t
  global-hl-line-mode: t
  global-subword-mode: t
  subword-mode: t
  delete-selection-mode: t
  tooltip-mode: t
  global-eldoc-mode: t
  show-paren-mode: t
  electric-indent-mode: t
  mouse-wheel-mode: t
  tab-bar-mode: t
  file-name-shadow-mode: t
  global-font-lock-mode: t
  font-lock-mode: t
  auto-composition-mode: t
  auto-encryption-mode: t
  auto-compression-mode: t
  line-number-mode: t
  global-visual-line-mode: t
  visual-line-mode: t
  indent-tabs-mode: t
  transient-mark-mode: t

Load-path shadows:
/Users/matthieu/.emacs.d/elpa/transient-20220806.2224/transient hides /Applications/Emacs.app/Contents/Resources/lisp/transient

Features:
(shadow sort mail-extr emacsbug sendmail dired-aux org-element ol-eww
eww xdg mm-url ol-rmail ol-mhe ol-irc ol-info ol-gnus nnselect
gnus-search eieio-opt speedbar ezimage dframe gnus-art mm-uu mml2015
mm-view mml-smime smime dig gnus-sum gnus-group gnus-undo gnus-start
gnus-dbus gnus-cloud nnimap nnmail mail-source utf7 netrc nnoo
parse-time gnus-spec gnus-int gnus-range gnus-win gnus nnheader
ol-docview doc-view jka-compr image-mode exif ol-bibtex ol-bbdb ol-w3m
ol-doi org-link-doi time battery dbus elfeed-show elfeed-search vc-git
vc-dispatcher shr kinsoku svg dom elfeed-csv elfeed elfeed-curl
elfeed-log elfeed-db elfeed-lib avl-tree generator url-queue xml-query
xml format-all language-id inheritenv magit-bookmark magit-submodule
magit-obsolete magit-blame magit-stash magit-reflog magit-bisect
magit-push magit-pull magit-fetch magit-clone magit-remote magit-commit
magit-sequence magit-notes magit-worktree magit-tag magit-merge
magit-branch magit-reset magit-files magit-refs magit-status magit
magit-repos magit-apply magit-wip magit-log which-func magit-diff
smerge-mode diff diff-mode git-commit log-edit pcvs-util add-log
magit-core magit-autorevert magit-margin magit-transient magit-process
with-editor shell server magit-mode transient magit-git magit-base
magit-section crm compat-27 compat-26 org-modern org ob ob-tangle ob-ref
ob-lob ob-table ob-exp org-macro org-footnote org-src ob-comint
org-pcomplete pcomplete org-list org-faces org-entities noutline outline
org-version ob-emacs-lisp ob-core ob-eval org-table oc-basic bibtex
iso8601 ol rx org-keys oc org-compat advice org-macs org-loaddefs
format-spec cal-menu calendar cal-loaddefs denote meow meow-tutor
meow-cheatsheet meow-cheatsheet-layout meow-core meow-shims meow-esc
meow-command array meow-beacon meow-thing meow-visual meow-keypad
meow-helpers meow-util meow-keymap meow-face meow-var embark ffap
thingatpt marginalia helpful imenu trace edebug backtrace info-look f
f-shortdoc shortdoc help-fns elisp-refs s orderless corfu
consult-vertico consult compat-28 compat recentf tree-widget wid-edit
bookmark pp vertico modus-operandi-theme modus-themes edmacro kmacro
olivetti pulsar pulse color cl-extra help-mode savehist saveplace
autorevert filenotify hl-line cap-words superword subword delsel pcase
xref project compile comint ansi-color ring find-func autoload
radix-tree lisp-mnt tar-mode arc-mode archive-mode mm-archive message
dired dired-loaddefs rfc822 mml mml-sec epa derived epg rfc6068
gnus-util rmail rmail-loaddefs text-property-search mailabbrev gmm-utils
mailheader mm-decode mm-bodies mm-encode mail-utils gnutls
network-stream url-http mail-parse rfc2231 rfc2047 rfc2045 mm-util
ietf-drums mail-prsvr url-gw nsm rmc puny url-cache url-auth epg-config
time-date auto-package-update dash diminish use-package
use-package-ensure use-package-delight use-package-diminish
use-package-bind-key bind-key easy-mmode use-package-core finder-inf
info package browse-url url url-proxy url-privacy url-expand url-methods
url-history url-cookie url-domsuf url-util mailcap url-handlers
url-parse auth-source cl-seq eieio eieio-core cl-macs eieio-loaddefs
password-cache json subr-x map url-vars seq byte-opt gv bytecomp
byte-compile cconv cl-loaddefs cl-lib iso-transl tooltip eldoc paren
electric uniquify ediff-hook vc-hooks lisp-float-type elisp-mode mwheel
term/ns-win ns-win ucs-normalize mule-util term/common-win tool-bar dnd
fontset image regexp-opt fringe tabulated-list replace newcomment
text-mode lisp-mode prog-mode register page tab-bar menu-bar rfn-eshadow
isearch easymenu timer select scroll-bar mouse jit-lock font-lock syntax
font-core term/tty-colors frame minibuffer cl-generic cham georgian
utf-8-lang misc-lang vietnamese tibetan thai tai-viet lao korean
japanese eucjp-ms cp51932 hebrew greek romanian slovak czech european
ethiopic indian cyrillic chinese composite emoji-zwj charscript charprop
case-table epa-hook jka-cmpr-hook help simple abbrev obarray
cl-preloaded nadvice button loaddefs faces cus-face macroexp files
window text-properties overlay sha1 md5 base64 format env code-pages
mule custom widget hashtable-print-readable backquote threads kqueue
cocoa ns multi-tty make-network-process emacs)

Memory information:
((conses 16 604371 43389)
(symbols 48 40916 9)
(strings 32 195283 14959)
(string-bytes 1 5733155)
(vectors 16 76142)
(vector-slots 8 861099 43431)
(floats 8 1770 1217)
(intervals 56 5647 5580)
(buffers 992 23))

[-- Attachment #2: Type: text/html, Size: 34946 bytes --]

bug#57080: 28.1; The %m modeline construct does not work for emacs-lisp-mode

[Eli Zaretskii]

> From: diredwolf <diredwolf1@gmail.com>
> Date: Tue, 9 Aug 2022 18:06:16 +0200
> 
> - Launch emacs -q
> - Evaluate this :: (setq-default mode-line-format "[%m]")
> 
> For every major mode you should see for example [Message] or [Dired by
> name] or [Help] but for elisp-mode you get [].

%m in mode-line-format is obsolete; use the variable mode-name
instead.

(The technical reason behind what you see is that %m displays the mode
name only if the value of mode-name is a string, which in this case it
isn't.)

bug#57080: 28.1; The %m modeline construct does not work for emacs-lisp-mode

[Eli Zaretskii]

> From: diredwolf <diredwolf1@gmail.com>
> Date: Tue, 9 Aug 2022 18:55:33 +0200
> 
> Thank you very much for your explanation, using mode-name instead of %m fixed the problem.

Thanks, I'm therefore closing the bug.

bug#57080: 28.1; The %m modeline construct does not work for emacs-lisp-mode

[Phil Sainty]

On 2022-08-10 05:06, Eli Zaretskii wrote:
>> From: diredwolf <diredwolf1@gmail.com>
>> Thank you very much for your explanation, using mode-name instead of 
>> %m fixed the problem.
> 
> Thanks, I'm therefore closing the bug.

I think some documentation updates are needed here?

In my month-old build from master, at any rate:

(info "(elisp) %-Constructs") states that ‘%m’ and ‘mode-name’
are equivalent, which is evidentially wrong.

Tangentially, (info "(elisp) Mode Line Variables") makes mention
of %M as being an obsolete version of ‘global-mode-string’, and
the %M construct is not listed in that other node at all (and
conversely, 'mode-name' is mentioned in the latter node without
any reference to %m.)

bug#57080: 28.1; The %m modeline construct does not work for emacs-lisp-mode

[Eli Zaretskii]

> Date: Wed, 10 Aug 2022 12:23:05 +1200
> From: Phil Sainty <psainty@orcon.net.nz>
> 
> On 2022-08-10 05:06, Eli Zaretskii wrote:
> >> From: diredwolf <diredwolf1@gmail.com>
> >> Thank you very much for your explanation, using mode-name instead of 
> >> %m fixed the problem.
> > 
> > Thanks, I'm therefore closing the bug.
> 
> I think some documentation updates are needed here?
> 
> In my month-old build from master, at any rate:
> 
> (info "(elisp) %-Constructs") states that ‘%m’ and ‘mode-name’
> are equivalent, which is evidentially wrong.

It also says %m is obsolete, which you didn't mention.

I won't object to telling there that %m doesn't work with non-string
mode-name, if that's your suggestion.

bug#57080: 28.1; The %m modeline construct does not work for emacs-lisp-mode

[Phil Sainty]

On 2022-08-10 14:40, Eli Zaretskii wrote:
>> From: Phil Sainty <psainty@orcon.net.nz>
>> (info "(elisp) %-Constructs") states that ‘%m’ and ‘mode-name’
>> are equivalent, which is evidentially wrong.
> 
> It also says %m is obsolete, which you didn't mention.

Ah, I didn't even see that -- I'd thought that paragraph was part
of the details for '%%' immediately above, and hadn't read it.

> I won't object to telling there that %m doesn't work with non-
> string mode-name, if that's your suggestion.

I'll do this, and also move the whole description below the '%m'.

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]

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

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

[Eli Zaretskii]

> Date: Sat, 18 Mar 2023 20:22:24 +1300
> From: Phil Sainty <psainty@orcon.net.nz>
> Cc: diredwolf1@gmail.com, 57080@debbugs.gnu.org
> 
> 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 goes too far, IMO, see below.

> 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).

But you moved it from its place near the end of the node (as
appropriate for obsolete features) to the mainline.  Why not leave it
where it was, and just add the explanation why its usage is not
advised?

> * The %M documentation was also not up to date.
> * The %t construct was obsolete but still documented.

So let's move %t to where %m is.

> * The %o and %q constructs were lacking documentation.

In the manual? I don't see them being added there.

> * The `mode-line-format' docstring for all of the constructs was
>    not as easy to read as it could have been.

I would leave this part alone on emacs-29, and only install the
reformatting of the doc string on master.

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

It also makes the text taller, thus requiring a larger Help window.
Is it still reasonably readable in "emacs -Q"?

Anyway, I think this part is for master.

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

tab-width is a user variable, so no Lisp program should set it, IMO.

Bottom line:

  . I'm okay with manual changes, modulo the movement of %m -- it
    should stay where it was.
  . I'm okay with adding %t to the manual (in the "obsolete" part).
  . I'm okay with removing %t from the doc string.
  . I'm okay with fixing the doc string of global-mode-string.
  . All the rest is okay for master.

Thanks.

bug#57080: 29.0.60; [PATCH] Updates to mode line construct documentation

[Phil Sainty]

On 2023-03-18 20:46, Eli Zaretskii wrote:
>> * The %m documentation was not entirely accurate (as discussed here).
> 
> But you moved it from its place near the end of the node (as
> appropriate for obsolete features) to the mainline.  Why not leave
> it where it was, and just add the explanation why its usage is not
> advised?

I moved it because it's still functional and so I thought it
warranted being listed in the sorted sequence between %l and %n
to make it easier to find.  To my mind this is still preferable,
but I can certainly move it back down below.


>> * The %t construct was obsolete but still documented.
> 
> So let's move %t to where %m is.

Since commit 8549f9e89bd9288c4c709d183a5bf8f07dbeed3d (in 2013)
this construct doesn't do anything at all, and the documentation
in doc/lispref/modes.texi was removed entirely at that time.
Is it still useful to document it anywhere at this point?


>> * The %o and %q constructs were lacking documentation.
> 
> In the manual? I don't see them being added there.

No, these was only missing from the docstring.  In the manual they
were documented in commit b0b02ca7f3e06d0f092df6f81babd1277bf93b0f
so this is a fixup for that commit.


>> * The `mode-line-format' docstring for all of the constructs was
>>    not as easy to read as it could have been.
> 
> I would leave this part alone on emacs-29, and only install the
> reformatting of the doc string on master.

Ok.


> It also makes the text taller, thus requiring a larger Help window.
> Is it still reasonably readable in "emacs -Q"?

I think so.  My take was that the formatting has its origins in the
days when 24-line terminals were the norm; but even in the current
state, the list of constructs is 27 lines long, so (a) we're already
past the point of anyone on a classic 24-line terminal being able to
fit that all on screen; (b) the new version is only 3 lines longer;
and (c) I think the vast majority of people will be looking at the
docstrings with many more lines than that.

I believe that the readability improvements warrant the slight
increase in line count in this instance.


> Anyway, I think this part is for master.

All good.


> Bottom line:
> 
>   . I'm okay with manual changes, modulo the movement of %m -- it
>     should stay where it was.
>   . I'm okay with adding %t to the manual (in the "obsolete" part).

Per comments above I'm not sure this will be useful, so I'll wait for
confirmation either way.

>   . I'm okay with removing %t from the doc string.
>   . I'm okay with fixing the doc string of global-mode-string.
>   . All the rest is okay for master.


Thanks Eli.

Phil

bug#57080: 29.0.60; [PATCH] Updates to mode line construct documentation

[Eli Zaretskii]

> Date: Sat, 18 Mar 2023 21:38:16 +1300
> From: Phil Sainty <psainty@orcon.net.nz>
> Cc: 57080@debbugs.gnu.org
> 
> >> * The %t construct was obsolete but still documented.
> > 
> > So let's move %t to where %m is.
> 
> Since commit 8549f9e89bd9288c4c709d183a5bf8f07dbeed3d (in 2013)
> this construct doesn't do anything at all, and the documentation
> in doc/lispref/modes.texi was removed entirely at that time.
> Is it still useful to document it anywhere at this point?

I thought you were talking about adding it (to the manual or
elsewhere)?  Are you instead suggesting to remove it from the doc
string?  That wasn't clear.

> >   . I'm okay with manual changes, modulo the movement of %m -- it
> >     should stay where it was.
> >   . I'm okay with adding %t to the manual (in the "obsolete" part).
> 
> Per comments above I'm not sure this will be useful, so I'll wait for
> confirmation either way.

What do you suggest instead? remove %t from the doc string?  That's
fine with me, on emacs-29:

> >   . I'm okay with removing %t from the doc string.
> >   . I'm okay with fixing the doc string of global-mode-string.
> >   . All the rest is okay for master.
> 
> 
> Thanks Eli.

Thanks.

bug#57080: 29.0.60; [PATCH] Updates to mode line construct documentation

[Phil Sainty]

On 2023-03-18 21:54, Eli Zaretskii wrote:
> I thought you were talking about adding it [%t] (to the manual or
> elsewhere)?  Are you instead suggesting to remove it from the doc
> string?

Yep, just removing it from the docstring.  That was the only place
it was still mentioned, that I could see.

> That's fine with me, on emacs-29

Thanks, will do.

bug#57080: 29.0.60; [PATCH] Updates to mode line construct documentation

[Phil Sainty]

I've now installed the changes on emacs-29 and master (in
accordance with the discussion here), so I'm closing this bug.

-Phil