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

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

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