From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.org!.POSTED!not-for-mail From: Kaushal Modi 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:55:34 +0000 Message-ID: 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> <20170522182007.GA2899@acm.fritz.box> NNTP-Posting-Host: blaine.gmane.org Mime-Version: 1.0 Content-Type: multipart/alternative; boundary="f403045f844426cb610550216ba6" X-Trace: blaine.gmane.org 1495479357 9103 195.159.176.226 (22 May 2017 18:55:57 GMT) X-Complaints-To: usenet@blaine.gmane.org NNTP-Posting-Date: Mon, 22 May 2017 18:55:57 +0000 (UTC) Cc: Eli Zaretskii , emacs-devel@gnu.org To: Alan Mackenzie Original-X-From: emacs-devel-bounces+ged-emacs-devel=m.gmane.org@gnu.org Mon May 22 20:55:53 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 1dCsUj-0002GQ-6e for ged-emacs-devel@m.gmane.org; Mon, 22 May 2017 20:55:53 +0200 Original-Received: from localhost ([::1]:44419 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1dCsUo-0003RI-ME for ged-emacs-devel@m.gmane.org; Mon, 22 May 2017 14:55:58 -0400 Original-Received: from eggs.gnu.org ([2001:4830:134:3::10]:57107) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1dCsUh-0003RB-Ic for emacs-devel@gnu.org; Mon, 22 May 2017 14:55:53 -0400 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1dCsUg-0002cp-6z for emacs-devel@gnu.org; Mon, 22 May 2017 14:55:51 -0400 Original-Received: from mail-lf0-x235.google.com ([2a00:1450:4010:c07::235]:35709) by eggs.gnu.org with esmtps (TLS1.0:RSA_AES_128_CBC_SHA1:16) (Exim 4.71) (envelope-from ) id 1dCsUd-0002aL-3P; Mon, 22 May 2017 14:55:47 -0400 Original-Received: by mail-lf0-x235.google.com with SMTP id a5so22824988lfh.2; Mon, 22 May 2017 11:55:46 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20161025; h=mime-version:references:in-reply-to:from:date:message-id:subject:to :cc; bh=bkvW7AXsl/EVUugBR8eYR9evAfaTFxkMffb8fPhNUNk=; b=PV5K/IdkMv/9oADNsEbAW5mPLMHSZxmWi4Bnepe7AeNKdTM+Xt+79ztDPLdTfGnWb7 +G1HjQ+GDwcfiz74cFOeu/h1+Y1+U5Zuv3PhFKj888pmEcC9ezFMzySUAnCgVVL4ius7 RnoNh7tyByHaIc25rUIoUnV+81Sjd26CXNY0N7Kdi4Qp9kegnre4x11xDyiezMRKqr20 3qm0cRQj3UY6khLQ/pb5PKTo7Y8AnNAhuVZw2ZH6xFNnD7+/R2tX5/g0xfNsQDXQa59r AtdicHI05lOmsug14M6qWnkMVHKRHbGE1oyB5moZFjmGys7LqCoCQ9B+7taeu/HlKFWR S0BA== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20161025; h=x-gm-message-state:mime-version:references:in-reply-to:from:date :message-id:subject:to:cc; bh=bkvW7AXsl/EVUugBR8eYR9evAfaTFxkMffb8fPhNUNk=; b=ec8wLsOa+zx3mL/JFYzI+ZMhZZsiwvqB3j0XyZCiYzwUzDCr/v5JNF0ki5kNW0mqdH GkU4dG4M9vgvgkDpaTGfP7YI2iwDQrp3VDwQg1RBEsZzpV2+TrlfY6kvh+UFfRbSBtP1 Q0cUPJuh+X/onTvJNy11VE9wj5bibv5Wl+IpNU/4AIxN8+/w3UvzYCSbwWfebf8Xg2so QcBFta9lRr6TfZV8RsYPmgFML64wiGrqu6Q05Htzq8llTbE0oQG8QsRwNdBk4r7OezER Vj2fmJzybIrRfAEuO/xZiBbewDawtRPMMpGFyGoBvJdEj8bR2vM/jVaQsAdxwr0qqLm5 eiJg== X-Gm-Message-State: AODbwcBeIA1PWrOUsej79q3EYePBh9bXxpAbQZJwkEX0yQh5g56FbX8C kEFSIgTSlrntksutl5RpVI6iEDGBnA== X-Received: by 10.46.87.78 with SMTP id r14mr5125661ljd.114.1495479345390; Mon, 22 May 2017 11:55:45 -0700 (PDT) In-Reply-To: <20170522182007.GA2899@acm.fritz.box> X-detected-operating-system: by eggs.gnu.org: Genre and OS details not recognized. X-Received-From: 2a00:1450:4010:c07::235 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:215099 Archived-At: --f403045f844426cb610550216ba6 Content-Type: text/plain; charset="UTF-8" On Mon, May 22, 2017 at 2:21 PM Alan Mackenzie wrote: > Thanks for taking on the task of finishing up the documentation of this > new facility. > Sure. I was just attempting to clarify things that were not clear to me as the mode-line-format is not very familiar to me. > 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. > When I saw the defcustom options for mode-line-percent-position, it wasn't evident to me why %q had 6 as the first element and why the rest had -3. > How about: "Also add detail about what these elements typically are." > Sure. I was just reverse-engineering your patch, and documenting for my future-self :) > 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." > Same as above. > > +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. > I wasn't aware of that. Being not acquainted to mode-line-format. I thought that the the reason for -3 and 6 as first elements needed to be explained. mode-line-format docstring has this: > A list whose car is an integer is processed by processing the cadr of > the list, and padding (if the number is positive) or truncating (if > negative) to the width specified by that number. But I wanted the integer element description to be made even clearer. May be the mode-line-format docstring should be improved? > > +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\", ...." > OK. > 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". > At first, I could not understand what that meant. But the analogy of a/(a+b) earlier in the thread made complete sense to me. So I just spelled that out in English, while also stealing the verbiage used in the Info manual text. 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. ;-) > I learned that just now :) So in summary I was just attempting to explain the defcustom values of mode-line-percent-position better, by reverse-engineering. I had to refer to the initial discussion in this thread, docstring of mode-line-format and parts from the Info manual changes made by your commit to completely understand these options. So then I distilled all of that into the mode-line-percent-position docstring. Can you please rephrase the mode-line-format and mode-line-percent-position docstrings taking that into account? -- Kaushal Modi --f403045f844426cb610550216ba6 Content-Type: text/html; charset="UTF-8" Content-Transfer-Encoding: quoted-printable
On Mon, May 22= , 2017 at 2:21 PM Alan Mackenzie <acm@muc.= de> wrote:
Thanks for taking= on the task of finishing up the documentation of this
new facility.

Sure. I was just attempti= ng to clarify things that were not clear to me as the mode-line-format is n= ot very familiar to me.
=C2=A0
How about: "Also add detail= about what these elements typically are."

Sure. I was just reverse-engineering your patch, and documenting f= or my future-self :)
=C2=A0
O= r: "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 ....).=C2=A0 It could be nil, or any other va= lid mode
line format construct."

Same as ab= ove.
=C2=A0
> +WIDTH is sp= ecified as an integer.=C2=A0 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.=C2=A0 This meaning of an integer applies throughout the whole of the mode line format, not just in
mode-line-percent-position.

I wasn'= t aware of that. Being not acquainted to mode-line-format. I thought that t= he the reason for -3 and 6 as first elements needed to be explained. mode-l= ine-format docstring has this:

> A list whose c= ar is an integer is processed by processing the cadr of
> the = list, and padding (if the number is positive) or truncating (if
&= gt; negative) to the width specified by that number.

But I wanted the integer element description to be made even clearer.=C2= =A0 May be the mode-line-format docstring should be improved?
=C2= =A0
> +TYPE can be one of \"%o\= ", \"%p\", \"%P\" or \"%q\".=C2=A0 See > +`mode-line-format' for more information on these % constructs.&qu= ot;
>=C2=A0 =C2=A0 :type `(radio
>=C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 (const :tag "nil:=C2=A0 = No offset is displayed" nil)
>=C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 (const :tag "\"%o\&= quot;: Proportion of \"travel\" of the window through the buffer&= quot;

or ... "TYPE is typically=C2=A0 one of \"%o\", ...."

OK.
=C2=A0
This description of %o seems a bit clumsy and unintuitive, even though it is accurate.=C2=A0 What was wrong with my phrase "the proportion of \"travel\" of the window through the buffer".

At first, I could not understand what that meant. But= the analogy of a/(a+b) earlier in the thread made complete sense to me. So= I just spelled that out in English, while also stealing the verbiage used = in the Info manual text.=C2=A0

The last clause should be "or Top, BotTOM, or All".=C2=A0 %o, %p,= and %P
actually output "Bottom"; it is only the field width (-3) which truncates it to "Bot".=C2=A0 (I just learned that over the weeken= d.=C2=A0 ;-)

I learned that just now :)=

So in summary I was just attempting to explain th= e defcustom values of mode-line-percent-position better, by reverse-enginee= ring. I had to refer to the initial discussion in this thread, docstring of= mode-line-format and parts from the Info manual changes made by your commi= t to completely understand these options. So then I distilled all of that i= nto the mode-line-percent-position docstring.

Can = you please rephrase the mode-line-format and mode-line-percent-position doc= strings taking that into account?
--
=

Kaushal Modi

--f403045f844426cb610550216ba6--