From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.org!.POSTED!not-for-mail From: Alan Mackenzie Newsgroups: gmane.emacs.devel Subject: Re: Proposal: new mode-line `%'-construct %o meaning "Degree of travel of window through buffer". Date: Mon, 22 May 2017 18:20:07 +0000 Message-ID: <20170522182007.GA2899@acm.fritz.box> References: <83r2zm3zqz.fsf@gnu.org> <20170518124541.4cce1567@jabberwock.cb.piermont.com> <83pof63q9f.fsf@gnu.org> <20170518161304.456e6dce@jabberwock.cb.piermont.com> <83lgpt52uh.fsf@gnu.org> <20170518165124.7f19ef9b@jabberwock.cb.piermont.com> <83fug14bg0.fsf@gnu.org> <83bmqlo7ep.fsf@gnu.org> NNTP-Posting-Host: blaine.gmane.org Mime-Version: 1.0 Content-Type: text/plain; charset=us-ascii X-Trace: blaine.gmane.org 1495477281 27394 195.159.176.226 (22 May 2017 18:21:21 GMT) X-Complaints-To: usenet@blaine.gmane.org NNTP-Posting-Date: Mon, 22 May 2017 18:21:21 +0000 (UTC) User-Agent: Mutt/1.5.24 (2015-08-30) Cc: Eli Zaretskii , emacs-devel@gnu.org To: Kaushal Modi Original-X-From: emacs-devel-bounces+ged-emacs-devel=m.gmane.org@gnu.org Mon May 22 20:21:17 2017 Return-path: Envelope-to: ged-emacs-devel@m.gmane.org Original-Received: from lists.gnu.org ([208.118.235.17]) by blaine.gmane.org with esmtp (Exim 4.84_2) (envelope-from ) id 1dCrxA-0006s4-K4 for ged-emacs-devel@m.gmane.org; Mon, 22 May 2017 20:21:12 +0200 Original-Received: from localhost ([::1]:44298 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1dCrxG-00025z-9o for ged-emacs-devel@m.gmane.org; Mon, 22 May 2017 14:21:18 -0400 Original-Received: from eggs.gnu.org ([2001:4830:134:3::10]:46027) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1dCrxA-00025s-4P for emacs-devel@gnu.org; Mon, 22 May 2017 14:21:13 -0400 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1dCrx6-0004NC-Kv for emacs-devel@gnu.org; Mon, 22 May 2017 14:21:12 -0400 Original-Received: from ocolin.muc.de ([193.149.48.4]:59441 helo=mail.muc.de) by eggs.gnu.org with smtp (Exim 4.71) (envelope-from ) id 1dCrx6-0004N2-7u for emacs-devel@gnu.org; Mon, 22 May 2017 14:21:08 -0400 Original-Received: (qmail 58770 invoked by uid 3782); 22 May 2017 18:21:05 -0000 Original-Received: from acm.muc.de (p548C712B.dip0.t-ipconnect.de [84.140.113.43]) by colin.muc.de (tmda-ofmipd) with ESMTP; Mon, 22 May 2017 20:21:02 +0200 Original-Received: (qmail 3169 invoked by uid 1000); 22 May 2017 18:20:07 -0000 Content-Disposition: inline In-Reply-To: X-Delivery-Agent: TMDA/1.1.12 (Macallan) X-Primary-Address: acm@muc.de X-detected-operating-system: by eggs.gnu.org: FreeBSD 9.x [fuzzy] X-Received-From: 193.149.48.4 X-BeenThere: emacs-devel@gnu.org X-Mailman-Version: 2.1.21 Precedence: list List-Id: "Emacs development discussions." List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: emacs-devel-bounces+ged-emacs-devel=m.gmane.org@gnu.org Original-Sender: "Emacs-devel" Xref: news.gmane.org gmane.emacs.devel:215093 Archived-At: Hello, Kaushal. Thanks for taking on the task of finishing up the documentation of this new facility. On Mon, May 22, 2017 at 13:38:51 +0000, Kaushal Modi wrote: > On Mon, May 22, 2017 at 12:14 AM Eli Zaretskii wrote: > > Our style for documenting Lisp data structures is less abstract: > > This option's value is a list of the form (WIDTH TYPE), > > where WIDTH specifies ... > Attached patch has docstring updates for both mode-line-percentage-position > and mode-line-format. I'm not completely happy with these changes, because I think they're a bit misleading. Primarily, mode-line-percent-position _DOESN'T_ require a 2-element list - just that that's what's most likely to be used. It could also be nil, or (I think) a bare "%o", etc., or any other valid mode line format fragment. > From 3c5dd77ad2c59c64e96456c2629c446f3a8c4107 Mon Sep 17 00:00:00 2001 > From: Kaushal Modi > Date: Sun, 21 May 2017 22:16:57 -0400 > Subject: [PATCH] Add detail to mode-line-percentage-position and > mode-line-format doc > > * lisp/bindings.el (mode-line-percent-position): Mention that this > variable requires a 2-element list. Also add detail about what > those elements should be. How about: "Also add detail about what these elements typically are." > > * src/buffer.c (syms_of_buffer): Add description for the new %o and %q > constructs in `mode-line-format'. > --- > lisp/bindings.el | 17 +++++++++++++---- > src/buffer.c | 5 +++++ > 2 files changed, 18 insertions(+), 4 deletions(-) > > diff --git a/lisp/bindings.el b/lisp/bindings.el > index 0e6ffc275e..895faa8a7e 100644 > --- a/lisp/bindings.el > +++ b/lisp/bindings.el > @@ -366,10 +366,19 @@ column-number-indicator-zero-based > :version "26.1") > > (defcustom mode-line-percent-position '(-3 "%p") > - "Specification of \"percentage offset\" of window through buffer > -This option specifies both the field width and the type of offset > -displayed in `mode-line-position', a component of the default > -`mode-line-format'." > + "Specification of \"percentage offset\" of window through buffer. > + > +This option's value is a list of the form (WIDTH TYPE) where > +WIDTH specifies the field width to space-fill or truncate to, > +and TYPE specifies the type of buffer offset to display in > +`mode-line-position'. > + Or: "The option's value is typically a list of the form (WIDTH TYPE) where WIDTH specifies the field width ... to display in `mode-line-position' (see ....). It could be nil, or any other valid mode line format construct." > +WIDTH is specified as an integer. If the integer is negative (-N), > +the width is truncated to N characters, and if it is positive (N), > +padding is added, if needed, to make the field N characters wide. > + Here, I'm a bit bothered that we'd be documenting something which doesn't really belong here. This meaning of an integer applies throughout the whole of the mode line format, not just in mode-line-percent-position. > +TYPE can be one of \"%o\", \"%p\", \"%P\" or \"%q\". See > +`mode-line-format' for more information on these % constructs." > :type `(radio > (const :tag "nil: No offset is displayed" nil) > (const :tag "\"%o\": Proportion of \"travel\" of the window through the buffer" or ... "TYPE is typically one of \"%o\", ...." > diff --git a/src/buffer.c b/src/buffer.c > index 80dbd3318d..9fd39c5fb4 100644 > --- a/src/buffer.c > +++ b/src/buffer.c > @@ -5496,6 +5496,11 @@ A string is printed verbatim in the mode line except for %-constructs: > %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 percentages of buffer above both the top and the bottom > + of the window, separated by -, or All. > + %o -- print percent of buffer above top of window vs the total buffer > + content excluding the text visible in the window, or Top, Bot > + or All. This description of %o seems a bit clumsy and unintuitive, even though it is accurate. What was wrong with my phrase "the proportion of \"travel\" of the window through the buffer". The last clause should be "or Top, BotTOM, or All". %o, %p, and %P actually output "Bottom"; it is only the field width (-3) which truncates it to "Bot". (I just learned that over the weekend. ;-) > %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. > -- > 2.13.0 > -- > Kaushal Modi -- Alan Mackenzie (Nuremberg, Germany).