From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.io!.POSTED.blaine.gmane.org!not-for-mail From: Phil Sainty Newsgroups: gmane.emacs.bugs Subject: bug#57080: 29.0.60; [PATCH] Updates to mode line construct documentation Date: Sat, 18 Mar 2023 21:38:16 +1300 Message-ID: <546c5d0399490a2bb4bcd202693db46b@webmail.orcon.net.nz> References: <1A5F4673-FA9C-4E23-A0C1-5125764E0EE7@gmail.com> <83v8r1tlgy.fsf@gnu.org> <83o7wttkha.fsf@gnu.org> <83h72kstxb.fsf@gnu.org> <8f76c5fd3cf4bda02f9b55c3df55a47c@webmail.orcon.net.nz> <87bdaf86c1edac42a5c004c14364608b@webmail.orcon.net.nz> <834jqicxht.fsf@gnu.org> Mime-Version: 1.0 Content-Type: text/plain; charset=US-ASCII; format=flowed Content-Transfer-Encoding: 7bit Injection-Info: ciao.gmane.io; posting-host="blaine.gmane.org:116.202.254.214"; logging-data="37205"; mail-complaints-to="usenet@ciao.gmane.io" User-Agent: Orcon Webmail Cc: 57080@debbugs.gnu.org To: Eli Zaretskii Original-X-From: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane-mx.org@gnu.org Sat Mar 18 09:39:18 2023 Return-path: Envelope-to: geb-bug-gnu-emacs@m.gmane-mx.org Original-Received: from lists.gnu.org ([209.51.188.17]) by ciao.gmane.io with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.92) (envelope-from ) id 1pdS5t-0009ZU-BA for geb-bug-gnu-emacs@m.gmane-mx.org; Sat, 18 Mar 2023 09:39:17 +0100 Original-Received: from localhost ([::1] helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1pdS5h-0008L5-Dv; Sat, 18 Mar 2023 04:39:05 -0400 Original-Received: from eggs.gnu.org ([2001:470:142:3::10]) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1pdS5f-0008Kw-IP for bug-gnu-emacs@gnu.org; Sat, 18 Mar 2023 04:39:03 -0400 Original-Received: from debbugs.gnu.org ([209.51.188.43]) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_128_GCM_SHA256:128) (Exim 4.90_1) (envelope-from ) id 1pdS5e-0007WR-4C for bug-gnu-emacs@gnu.org; Sat, 18 Mar 2023 04:39:03 -0400 Original-Received: from Debian-debbugs by debbugs.gnu.org with local (Exim 4.84_2) (envelope-from ) id 1pdS5d-000588-Tc for bug-gnu-emacs@gnu.org; Sat, 18 Mar 2023 04:39:01 -0400 X-Loop: help-debbugs@gnu.org Resent-From: Phil Sainty Original-Sender: "Debbugs-submit" Resent-CC: bug-gnu-emacs@gnu.org Resent-Date: Sat, 18 Mar 2023 08:39:01 +0000 Resent-Message-ID: Resent-Sender: help-debbugs@gnu.org X-GNU-PR-Message: followup 57080 X-GNU-PR-Package: emacs Original-Received: via spool by 57080-submit@debbugs.gnu.org id=B57080.167912870219673 (code B ref 57080); Sat, 18 Mar 2023 08:39:01 +0000 Original-Received: (at 57080) by debbugs.gnu.org; 18 Mar 2023 08:38:22 +0000 Original-Received: from localhost ([127.0.0.1]:46172 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1pdS50-00057D-5O for submit@debbugs.gnu.org; Sat, 18 Mar 2023 04:38:22 -0400 Original-Received: from smtp-3.orcon.net.nz ([60.234.4.44]:37553) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1pdS4y-000573-AX for 57080@debbugs.gnu.org; Sat, 18 Mar 2023 04:38:21 -0400 Original-Received: from [10.253.37.70] (port=34710 helo=webmail.orcon.net.nz) by smtp-3.orcon.net.nz with esmtpa (Exim 4.90_1) (envelope-from ) id 1pdS4v-0007v7-4p; Sat, 18 Mar 2023 21:38:17 +1300 Original-Received: from ip-180-148-124-51.kinect.net.nz ([180.148.124.51]) via [10.253.37.253] by webmail.orcon.net.nz with HTTP (HTTP/1.1 POST); Sat, 18 Mar 2023 21:38:16 +1300 In-Reply-To: <834jqicxht.fsf@gnu.org> X-Sender: psainty@orcon.net.nz X-GeoIP: -- X-Spam_score: -2.9 X-Spam_score_int: -28 X-Spam_bar: -- X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list X-BeenThere: bug-gnu-emacs@gnu.org List-Id: "Bug reports for GNU Emacs, the Swiss army knife of text editors" List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane-mx.org@gnu.org Original-Sender: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane-mx.org@gnu.org Xref: news.gmane.io gmane.emacs.bugs:258144 Archived-At: 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