From unknown Fri Aug 15 12:51:40 2025 Content-Disposition: inline Content-Transfer-Encoding: quoted-printable MIME-Version: 1.0 X-Mailer: MIME-tools 5.509 (Entity 5.509) Content-Type: text/plain; charset=utf-8 From: bug#32863 <32863@debbugs.gnu.org> To: bug#32863 <32863@debbugs.gnu.org> Subject: Status: Unsatisfactory "definition" of "vertical scroll position" in Emacs lisp manual and doc string of window-vscroll Reply-To: bug#32863 <32863@debbugs.gnu.org> Date: Fri, 15 Aug 2025 19:51:40 +0000 retitle 32863 Unsatisfactory "definition" of "vertical scroll position" in = Emacs lisp manual and doc string of window-vscroll reassign 32863 emacs submitter 32863 Alan Mackenzie severity 32863 minor thanks From debbugs-submit-bounces@debbugs.gnu.org Fri Sep 28 11:34:20 2018 Received: (at submit) by debbugs.gnu.org; 28 Sep 2018 15:34:20 +0000 Received: from localhost ([127.0.0.1]:57778 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1g5uma-0001vZ-EW for submit@debbugs.gnu.org; Fri, 28 Sep 2018 11:34:20 -0400 Received: from eggs.gnu.org ([208.118.235.92]:44516) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1g5umZ-0001vN-Ds for submit@debbugs.gnu.org; Fri, 28 Sep 2018 11:34:19 -0400 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1g5umP-0007bi-Pj for submit@debbugs.gnu.org; Fri, 28 Sep 2018 11:34:12 -0400 X-Spam-Checker-Version: SpamAssassin 3.3.2 (2011-06-06) on eggs.gnu.org X-Spam-Level: X-Spam-Status: No, score=0.8 required=5.0 tests=BAYES_50 autolearn=disabled version=3.3.2 Received: from lists.gnu.org ([2001:4830:134:3::11]:56706) by eggs.gnu.org with esmtps (TLS1.0:RSA_AES_256_CBC_SHA1:32) (Exim 4.71) (envelope-from ) id 1g5umP-0007bK-Fv for submit@debbugs.gnu.org; Fri, 28 Sep 2018 11:34:09 -0400 Received: from eggs.gnu.org ([2001:4830:134:3::10]:54099) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1g5umO-0000Rx-B6 for bug-gnu-emacs@gnu.org; Fri, 28 Sep 2018 11:34:09 -0400 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1g5umK-0007Za-1A for bug-gnu-emacs@gnu.org; Fri, 28 Sep 2018 11:34:08 -0400 Received: from colin.muc.de ([193.149.48.1]:42494 helo=mail.muc.de) by eggs.gnu.org with smtp (Exim 4.71) (envelope-from ) id 1g5umJ-0007SG-4V for bug-gnu-emacs@gnu.org; Fri, 28 Sep 2018 11:34:03 -0400 Received: (qmail 42527 invoked by uid 3782); 28 Sep 2018 15:33:58 -0000 Received: from acm.muc.de (p5B146F39.dip0.t-ipconnect.de [91.20.111.57]) by colin.muc.de (tmda-ofmipd) with ESMTP; Fri, 28 Sep 2018 17:33:58 +0200 Received: (qmail 15859 invoked by uid 1000); 28 Sep 2018 15:28:32 -0000 Date: Fri, 28 Sep 2018 15:28:32 +0000 To: bug-gnu-emacs@gnu.org Subject: Unsatisfactory "definition" of "vertical scroll position" in Emacs lisp manual and doc string of window-vscroll Message-ID: <20180928152832.GA5172@ACM> MIME-Version: 1.0 Content-Type: text/plain; charset=us-ascii Content-Disposition: inline User-Agent: Mutt/1.10.1 (2018-07-13) X-Delivery-Agent: TMDA/1.1.12 (Macallan) From: Alan Mackenzie X-Primary-Address: acm@muc.de X-detected-operating-system: by eggs.gnu.org: FreeBSD 9.x [fuzzy] X-detected-operating-system: by eggs.gnu.org: GNU/Linux 2.6.x X-Received-From: 2001:4830:134:3::11 X-Spam-Score: -4.3 (----) X-Debbugs-Envelope-To: submit X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: debbugs-submit-bounces@debbugs.gnu.org Sender: "Debbugs-submit" X-Spam-Score: -5.3 (-----) Hello, Emacs. In the Emacs-26.1 Emacs Lisp manual, on page "Vertical Scrolling" there is an ostensible definition for "vertical scroll position". This "definition" says it "is a number, never less than zero. It specifies how far to raise the contents of the window." What should be doing this raising? When might it do this? For what purpose might the contents of the window be raised? I find this "definition" totally obscure. I can not make sense of it at all. Without understanding what "vertical scroll position" means, the entire manual page is meaningless. ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;; I came to this manual page through not understanding the doc string for the function window-vscroll. This says just "Return the amount by which WINDOW is scrolled vertically.". _Is_ scrolled vertically. What on earth does that mean? What is the zero point from which this scrolling is measured? Does this "is" refer to the current visible scrolling, or the intended scrolling after the next redisplay? This doc string needs clarification. -- Alan Mackenzie (Nuremberg, Germany). From debbugs-submit-bounces@debbugs.gnu.org Fri Sep 28 17:42:19 2018 Received: (at 32863) by debbugs.gnu.org; 28 Sep 2018 21:42:19 +0000 Received: from localhost ([127.0.0.1]:58134 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1g60Wh-0006wU-Co for submit@debbugs.gnu.org; Fri, 28 Sep 2018 17:42:19 -0400 Received: from eggs.gnu.org ([208.118.235.92]:52632) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1g60Wf-0006wI-AC for 32863@debbugs.gnu.org; Fri, 28 Sep 2018 17:42:17 -0400 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1g60WW-0006Nn-Ti for 32863@debbugs.gnu.org; Fri, 28 Sep 2018 17:42:12 -0400 X-Spam-Checker-Version: SpamAssassin 3.3.2 (2011-06-06) on eggs.gnu.org X-Spam-Level: X-Spam-Status: No, score=-0.0 required=5.0 tests=BAYES_40 autolearn=disabled version=3.3.2 Received: from fencepost.gnu.org ([2001:4830:134:3::e]:37111) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1g60WW-0006Nb-Pb; Fri, 28 Sep 2018 17:42:08 -0400 Received: from [176.228.60.248] (port=1350 helo=home-c4e4a596f7) by fencepost.gnu.org with esmtpsa (TLS1.2:RSA_AES_256_CBC_SHA1:256) (Exim 4.82) (envelope-from ) id 1g60WW-0000Bs-D0; Fri, 28 Sep 2018 17:42:08 -0400 Date: Sat, 29 Sep 2018 00:41:54 +0300 Message-Id: <837ej5710d.fsf@gnu.org> From: Eli Zaretskii To: Alan Mackenzie In-reply-to: <20180928152832.GA5172@ACM> (message from Alan Mackenzie on Fri, 28 Sep 2018 15:28:32 +0000) Subject: Re: bug#32863: Unsatisfactory "definition" of "vertical scroll position" in Emacs lisp manual and doc string of window-vscroll References: <20180928152832.GA5172@ACM> X-detected-operating-system: by eggs.gnu.org: GNU/Linux 2.2.x-3.x [generic] X-Received-From: 2001:4830:134:3::e X-Spam-Score: -5.0 (-----) X-Debbugs-Envelope-To: 32863 Cc: 32863@debbugs.gnu.org X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: debbugs-submit-bounces@debbugs.gnu.org Sender: "Debbugs-submit" X-Spam-Score: -6.0 (------) > Date: Fri, 28 Sep 2018 15:28:32 +0000 > From: Alan Mackenzie > > In the Emacs-26.1 Emacs Lisp manual, on page "Vertical Scrolling" there > is an ostensible definition for "vertical scroll position". > > This "definition" says it "is a number, never less than zero. It > specifies how far to raise the contents of the window." > > What should be doing this raising? The call to set-window-vscroll does that. > When might it do this? The automatic calls to set-window-vscroll happen when a screen line is too tall to be completely visible in a window, and Emacs is asked to scroll. Try scrolling or vertical motion commands when the window displays a tall image. > For what purpose might the contents of the window be raised? To show the portion of the current line that is not currently visible. > I find this "definition" totally obscure. I can not make sense of it at > all. Without understanding what "vertical scroll position" means, the > entire manual page is meaningless. Do you understand it now? > I came to this manual page through not understanding the doc string for > the function window-vscroll. This says just "Return the amount by which > WINDOW is scrolled vertically.". > > _Is_ scrolled vertically. What on earth does that mean? See above. > What is the zero point from which this scrolling is measured? The zero point is when the top pixel of the window's first screen line is visible. > Does this "is" refer to the current visible scrolling, or the > intended scrolling after the next redisplay? Since redisplay runs when Emacs is idle, the answer should be obvious, right? > This doc string needs clarification. I'm all ears. From debbugs-submit-bounces@debbugs.gnu.org Mon Oct 15 07:55:51 2018 Received: (at 32863) by debbugs.gnu.org; 15 Oct 2018 11:55:51 +0000 Received: from localhost ([127.0.0.1]:49866 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1gC1TS-0005hw-NT for submit@debbugs.gnu.org; Mon, 15 Oct 2018 07:55:51 -0400 Received: from colin.muc.de ([193.149.48.1]:24877 helo=mail.muc.de) by debbugs.gnu.org with smtp (Exim 4.84_2) (envelope-from ) id 1gC1TQ-0005hn-HF for 32863@debbugs.gnu.org; Mon, 15 Oct 2018 07:55:49 -0400 Received: (qmail 60130 invoked by uid 3782); 15 Oct 2018 11:55:47 -0000 Received: from acm.muc.de (p5B14745F.dip0.t-ipconnect.de [91.20.116.95]) by colin.muc.de (tmda-ofmipd) with ESMTP; Mon, 15 Oct 2018 13:55:45 +0200 Received: (qmail 6677 invoked by uid 1000); 15 Oct 2018 11:48:03 -0000 Date: Mon, 15 Oct 2018 11:48:03 +0000 To: Eli Zaretskii Subject: Re: bug#32863: Unsatisfactory "definition" of "vertical scroll position" in Emacs lisp manual and doc string of window-vscroll Message-ID: <20181015114803.GB5623@ACM> References: <20180928152832.GA5172@ACM> <837ej5710d.fsf@gnu.org> MIME-Version: 1.0 Content-Type: text/plain; charset=us-ascii Content-Disposition: inline In-Reply-To: <837ej5710d.fsf@gnu.org> User-Agent: Mutt/1.10.1 (2018-07-13) X-Delivery-Agent: TMDA/1.1.12 (Macallan) From: Alan Mackenzie X-Primary-Address: acm@muc.de X-Spam-Score: -0.0 (/) X-Debbugs-Envelope-To: 32863 Cc: 32863@debbugs.gnu.org X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: debbugs-submit-bounces@debbugs.gnu.org Sender: "Debbugs-submit" X-Spam-Score: -1.0 (-) Hello, Eli. Thanks very much for the explanations. On Sat, Sep 29, 2018 at 00:41:54 +0300, Eli Zaretskii wrote: > > Date: Fri, 28 Sep 2018 15:28:32 +0000 > > From: Alan Mackenzie > > In the Emacs-26.1 Emacs Lisp manual, on page "Vertical Scrolling" there > > is an ostensible definition for "vertical scroll position". > > This "definition" says it "is a number, never less than zero. It > > specifies how far to raise the contents of the window." > > What should be doing this raising? > The call to set-window-vscroll does that. > > When might it do this? > The automatic calls to set-window-vscroll happen when a screen line is > too tall to be completely visible in a window, and Emacs is asked to > scroll. Try scrolling or vertical motion commands when the window > displays a tall image. > > For what purpose might the contents of the window be raised? > To show the portion of the current line that is not currently visible. > > I find this "definition" totally obscure. I can not make sense of it at > > all. Without understanding what "vertical scroll position" means, the > > entire manual page is meaningless. > Do you understand it now? Yes, I do. :-) > > I came to this manual page through not understanding the doc string for > > the function window-vscroll. This says just "Return the amount by which > > WINDOW is scrolled vertically.". > > _Is_ scrolled vertically. What on earth does that mean? > See above. > > What is the zero point from which this scrolling is measured? > The zero point is when the top pixel of the window's first screen line > is visible. > > Does this "is" refer to the current visible scrolling, or the > > intended scrolling after the next redisplay? > Since redisplay runs when Emacs is idle, the answer should be obvious, > right? > > This doc string needs clarification. > I'm all ears. I propose to amend windows.texi, and two doc strings in windows.c in the emacs-26 branch as follows. I think that these amendments would have prevented my initial puzzlement. Any comments? diff --git a/doc/lispref/windows.texi b/doc/lispref/windows.texi index 265067146d..32546c544d 100644 --- a/doc/lispref/windows.texi +++ b/doc/lispref/windows.texi @@ -4200,18 +4200,19 @@ Vertical Scrolling @cindex vertical scroll position @dfn{Vertical fractional scrolling} means shifting text in a window -up or down by a specified multiple or fraction of a line. Each window +up or down by a specified multiple or fraction of a line. Emacs uses it +on images and text rows which are taller than the window. Each window has a @dfn{vertical scroll position}, which is a number, never less than -zero. It specifies how far to raise the contents of the window. -Raising the window contents generally makes all or part of some lines -disappear off the top, and all or part of some other lines appear at the -bottom. The usual value is zero. +zero. It specifies how far to raise the contents of the window when +redisplaying it. Raising the window contents generally makes all or +part of some lines disappear off the top, and all or part of some other +lines appear at the bottom. The usual value is zero. The vertical scroll position is measured in units of the normal line height, which is the height of the default font. Thus, if the value is -.5, that means the window contents are scrolled up half the normal line -height. If it is 3.3, that means the window contents are scrolled up -somewhat over three times the normal line height. +.5, that means the window contents will be scrolled up half the normal +line height. If it is 3.3, that means the window contents are scrolled +up somewhat over three times the normal line height. What fraction of a line the vertical scrolling covers, or how many lines, depends on what the lines contain. A value of .5 could scroll a diff --git a/src/window.c b/src/window.c index 409b01f302..0f784db77f 100644 --- a/src/window.c +++ b/src/window.c @@ -7322,6 +7322,8 @@ value. */) DEFUN ("window-vscroll", Fwindow_vscroll, Swindow_vscroll, 0, 2, 0, doc: /* Return the amount by which WINDOW is scrolled vertically. +This takes effect when redisplaying tall lines or images. + If WINDOW is omitted or nil, it defaults to the selected window. Normally, value is a multiple of the canonical character height of WINDOW; optional second arg PIXELS-P means value is measured in pixels. */) @@ -7344,6 +7346,8 @@ optional second arg PIXELS-P means value is measured in pixels. */) DEFUN ("set-window-vscroll", Fset_window_vscroll, Sset_window_vscroll, 2, 3, 0, doc: /* Set amount by which WINDOW should be scrolled vertically to VSCROLL. +This takes effect when redisplaying tall lines or images. + WINDOW nil means use the selected window. Normally, VSCROLL is a non-negative multiple of the canonical character height of WINDOW; optional third arg PIXELS-P non-nil means that VSCROLL is in pixels. -- Alan Mackenzie (Nuremberg, Germany). From debbugs-submit-bounces@debbugs.gnu.org Mon Oct 15 11:32:08 2018 Received: (at 32863) by debbugs.gnu.org; 15 Oct 2018 15:32:09 +0000 Received: from localhost ([127.0.0.1]:50986 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1gC4ql-0001vt-Ph for submit@debbugs.gnu.org; Mon, 15 Oct 2018 11:32:08 -0400 Received: from eggs.gnu.org ([208.118.235.92]:34392) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1gC4qj-0001qG-Cl for 32863@debbugs.gnu.org; Mon, 15 Oct 2018 11:32:06 -0400 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1gC4qZ-0003Hl-A8 for 32863@debbugs.gnu.org; Mon, 15 Oct 2018 11:32:00 -0400 X-Spam-Checker-Version: SpamAssassin 3.3.2 (2011-06-06) on eggs.gnu.org X-Spam-Level: X-Spam-Status: No, score=0.8 required=5.0 tests=BAYES_50 autolearn=disabled version=3.3.2 Received: from fencepost.gnu.org ([2001:4830:134:3::e]:44134) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1gC4qZ-0003Hf-6D; Mon, 15 Oct 2018 11:31:55 -0400 Received: from [176.228.60.248] (port=3001 helo=home-c4e4a596f7) by fencepost.gnu.org with esmtpsa (TLS1.2:RSA_AES_256_CBC_SHA1:256) (Exim 4.82) (envelope-from ) id 1gC4qY-0000jn-OY; Mon, 15 Oct 2018 11:31:55 -0400 Date: Mon, 15 Oct 2018 18:32:05 +0300 Message-Id: <83y3azrzt6.fsf@gnu.org> From: Eli Zaretskii To: Alan Mackenzie In-reply-to: <20181015114803.GB5623@ACM> (message from Alan Mackenzie on Mon, 15 Oct 2018 11:48:03 +0000) Subject: Re: bug#32863: Unsatisfactory "definition" of "vertical scroll position" in Emacs lisp manual and doc string of window-vscroll References: <20180928152832.GA5172@ACM> <837ej5710d.fsf@gnu.org> <20181015114803.GB5623@ACM> X-detected-operating-system: by eggs.gnu.org: GNU/Linux 2.2.x-3.x [generic] X-Received-From: 2001:4830:134:3::e X-Spam-Score: -5.0 (-----) X-Debbugs-Envelope-To: 32863 Cc: 32863@debbugs.gnu.org X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: debbugs-submit-bounces@debbugs.gnu.org Sender: "Debbugs-submit" X-Spam-Score: -6.0 (------) > Date: Mon, 15 Oct 2018 11:48:03 +0000 > Cc: 32863@debbugs.gnu.org > From: Alan Mackenzie > > I propose to amend windows.texi, and two doc strings in windows.c in the > emacs-26 branch as follows. I think that these amendments would have > prevented my initial puzzlement. Any comments? The changes to doc strings are fine (but please use "display" instead of "redisplay", as the latter is a technical term not necessarily accurate in this context). As for the changes to windows.texi, I admit that I don't really understand how such insignificant changes could prevent your puzzlement. Are you sure it isn't the result of reading my explanations, which caused the text to "talk" to you more clearly? > @dfn{Vertical fractional scrolling} means shifting text in a window > -up or down by a specified multiple or fraction of a line. Each window > +up or down by a specified multiple or fraction of a line. Emacs uses it > +on images and text rows which are taller than the window. Each window Here you added a sentence that tells when is this feature used. (Btw, nothing prevents Emacs from using it even with lines that are not taller than the window, and it even does so sometimes. So this is just an example, and I'd suggest to say that. Also, please don't use "rows" in the manual: that is the terminology of xdisp.c, but Lisp programmers are unfamiliar with it. I prefer to use "screen lines".) > has a @dfn{vertical scroll position}, which is a number, never less than > -zero. It specifies how far to raise the contents of the window. > -Raising the window contents generally makes all or part of some lines > -disappear off the top, and all or part of some other lines appear at the > -bottom. The usual value is zero. > +zero. It specifies how far to raise the contents of the window when > +redisplaying it. Raising the window contents generally makes all or > +part of some lines disappear off the top, and all or part of some other > +lines appear at the bottom. The usual value is zero. Here you just added "when redisplaying it". If this is such a crucially important detail, I'm all for it (but again, please say "displaying"). However, I wonder whether it really is all that stood between you and the eureka. > The vertical scroll position is measured in units of the normal line > height, which is the height of the default font. Thus, if the value is > -.5, that means the window contents are scrolled up half the normal line > -height. If it is 3.3, that means the window contents are scrolled up > -somewhat over three times the normal line height. > +.5, that means the window contents will be scrolled up half the normal > +line height. If it is 3.3, that means the window contents are scrolled > +up somewhat over three times the normal line height. And here, you just replaced "are scrolled" with "will be scrolled" (only once out of 2 instances). Again, one wonders whether this is all that you missed to see the light. I'm not saying I object to these changes -- I don't -- but I'm a bit surprised that such minor changes could have such a profound effect on clarity. Thanks. From debbugs-submit-bounces@debbugs.gnu.org Mon Oct 15 14:40:48 2018 Received: (at 32863) by debbugs.gnu.org; 15 Oct 2018 18:40:48 +0000 Received: from localhost ([127.0.0.1]:51411 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1gC7nM-0000Oj-7W for submit@debbugs.gnu.org; Mon, 15 Oct 2018 14:40:48 -0400 Received: from colin.muc.de ([193.149.48.1]:16303 helo=mail.muc.de) by debbugs.gnu.org with smtp (Exim 4.84_2) (envelope-from ) id 1gC7nK-0000Oa-KM for 32863@debbugs.gnu.org; Mon, 15 Oct 2018 14:40:47 -0400 Received: (qmail 49514 invoked by uid 3782); 15 Oct 2018 18:40:44 -0000 Received: from acm.muc.de (p5B14745F.dip0.t-ipconnect.de [91.20.116.95]) by colin.muc.de (tmda-ofmipd) with ESMTP; Mon, 15 Oct 2018 20:40:43 +0200 Received: (qmail 28776 invoked by uid 1000); 15 Oct 2018 18:33:01 -0000 Date: Mon, 15 Oct 2018 18:33:01 +0000 To: Eli Zaretskii Subject: Re: bug#32863: Unsatisfactory "definition" of "vertical scroll position" in Emacs lisp manual and doc string of window-vscroll Message-ID: <20181015183301.GD5623@ACM> References: <20180928152832.GA5172@ACM> <837ej5710d.fsf@gnu.org> <20181015114803.GB5623@ACM> <83y3azrzt6.fsf@gnu.org> MIME-Version: 1.0 Content-Type: text/plain; charset=us-ascii Content-Disposition: inline In-Reply-To: <83y3azrzt6.fsf@gnu.org> User-Agent: Mutt/1.10.1 (2018-07-13) X-Delivery-Agent: TMDA/1.1.12 (Macallan) From: Alan Mackenzie X-Primary-Address: acm@muc.de X-Spam-Score: -0.0 (/) X-Debbugs-Envelope-To: 32863 Cc: 32863@debbugs.gnu.org X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: debbugs-submit-bounces@debbugs.gnu.org Sender: "Debbugs-submit" X-Spam-Score: -1.0 (-) Hello, Eli. Thanks for such a rapid review! On Mon, Oct 15, 2018 at 18:32:05 +0300, Eli Zaretskii wrote: > > Date: Mon, 15 Oct 2018 11:48:03 +0000 > > Cc: 32863@debbugs.gnu.org > > From: Alan Mackenzie > > I propose to amend windows.texi, and two doc strings in windows.c in the > > emacs-26 branch as follows. I think that these amendments would have > > prevented my initial puzzlement. Any comments? > The changes to doc strings are fine (but please use "display" instead > of "redisplay", as the latter is a technical term not necessarily > accurate in this context). Done. > As for the changes to windows.texi, I admit that I don't really > understand how such insignificant changes could prevent your > puzzlement. Are you sure it isn't the result of reading my > explanations, which caused the text to "talk" to you more clearly? I've thought of that, and been as careful as I can be to reconstruct my mental state at the time I raised the bug. I think my emphasis on "when displaying it" is sufficient to establish a context for understanding. > > @dfn{Vertical fractional scrolling} means shifting text in a window > > -up or down by a specified multiple or fraction of a line. Each window > > +up or down by a specified multiple or fraction of a line. Emacs uses it > > +on images and text rows which are taller than the window. Each window > Here you added a sentence that tells when is this feature used. (Btw, > nothing prevents Emacs from using it even with lines that are not > taller than the window, and it even does so sometimes. So this is > just an example, and I'd suggest to say that. Also, please don't use > "rows" in the manual: that is the terminology of xdisp.c, but Lisp > programmers are unfamiliar with it. I prefer to use "screen lines".) Done (both). > > has a @dfn{vertical scroll position}, which is a number, never less than > > -zero. It specifies how far to raise the contents of the window. > > -Raising the window contents generally makes all or part of some lines > > -disappear off the top, and all or part of some other lines appear at the > > -bottom. The usual value is zero. > > +zero. It specifies how far to raise the contents of the window when > > +redisplaying it. Raising the window contents generally makes all or > > +part of some lines disappear off the top, and all or part of some other > > +lines appear at the bottom. The usual value is zero. > Here you just added "when redisplaying it". If this is such a > crucially important detail, I'm all for it (but again, please say > "displaying"). However, I wonder whether it really is all that > stood between you and the eureka. I believe it is. > > The vertical scroll position is measured in units of the normal line > > height, which is the height of the default font. Thus, if the value is > > -.5, that means the window contents are scrolled up half the normal line > > -height. If it is 3.3, that means the window contents are scrolled up > > -somewhat over three times the normal line height. > > +.5, that means the window contents will be scrolled up half the normal > > +line height. If it is 3.3, that means the window contents are scrolled > > +up somewhat over three times the normal line height. > And here, you just replaced "are scrolled" with "will be scrolled" > (only once out of 2 instances). Again, one wonders whether this is > all that you missed to see the light. This attempts to fix a fundamental ambiguity in the use of the words "is" and "are" with a past participle. For example, compare these two sentences: 1. Emacs 26.1 is released. 2. Emacs is released every few months. In the first, "is released" refers to a one-time event in the past. In the second, it refers to a habitual action, still happening. That same ambiguity with "are" in "...means the window contents are scrolled up" confused me. The "will be" helps eliminate the interpretation "have ALREADY been scrolled up", the 1. above. > I'm not saying I object to these changes -- I don't -- but I'm a bit > surprised that such minor changes could have such a profound effect on > clarity. When I first read the page I was totally lacking in context. I think I've added enough context to have helped me, were I coming to it again for the first time. OK, amended (final?) version: diff --git a/doc/lispref/windows.texi b/doc/lispref/windows.texi index 265067146d..960573d865 100644 --- a/doc/lispref/windows.texi +++ b/doc/lispref/windows.texi @@ -4200,18 +4200,20 @@ Vertical Scrolling @cindex vertical scroll position @dfn{Vertical fractional scrolling} means shifting text in a window -up or down by a specified multiple or fraction of a line. Each window -has a @dfn{vertical scroll position}, which is a number, never less than -zero. It specifies how far to raise the contents of the window. -Raising the window contents generally makes all or part of some lines -disappear off the top, and all or part of some other lines appear at the -bottom. The usual value is zero. +up or down by a specified multiple or fraction of a line. Emacs uses +it, for example, on images and screen lines which are taller than the +window. Each window has a @dfn{vertical scroll position}, which is a +number, never less than zero. It specifies how far to raise the +contents of the window when displaying them. Raising the window +contents generally makes all or part of some lines disappear off the +top, and all or part of some other lines appear at the bottom. The +usual value is zero. The vertical scroll position is measured in units of the normal line height, which is the height of the default font. Thus, if the value is -.5, that means the window contents are scrolled up half the normal line -height. If it is 3.3, that means the window contents are scrolled up -somewhat over three times the normal line height. +.5, that means the window contents will be scrolled up half the normal +line height. If it is 3.3, that means the window contents are scrolled +up somewhat over three times the normal line height. What fraction of a line the vertical scrolling covers, or how many lines, depends on what the lines contain. A value of .5 could scroll a > Thanks. -- Alan Mackenzie (Nuremberg, Germany). From debbugs-submit-bounces@debbugs.gnu.org Mon Oct 15 14:47:45 2018 Received: (at 32863) by debbugs.gnu.org; 15 Oct 2018 18:47:45 +0000 Received: from localhost ([127.0.0.1]:51415 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1gC7u5-0000ZP-73 for submit@debbugs.gnu.org; Mon, 15 Oct 2018 14:47:45 -0400 Received: from eggs.gnu.org ([208.118.235.92]:39279) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1gC7u3-0000ZA-Mc for 32863@debbugs.gnu.org; Mon, 15 Oct 2018 14:47:43 -0400 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1gC7tq-0003Sr-O3 for 32863@debbugs.gnu.org; Mon, 15 Oct 2018 14:47:36 -0400 X-Spam-Checker-Version: SpamAssassin 3.3.2 (2011-06-06) on eggs.gnu.org X-Spam-Level: X-Spam-Status: No, score=-1.9 required=5.0 tests=BAYES_00 autolearn=disabled version=3.3.2 Received: from fencepost.gnu.org ([2001:4830:134:3::e]:49168) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1gC7tn-0003R9-9P; Mon, 15 Oct 2018 14:47:28 -0400 Received: from [176.228.60.248] (port=3508 helo=home-c4e4a596f7) by fencepost.gnu.org with esmtpsa (TLS1.2:RSA_AES_256_CBC_SHA1:256) (Exim 4.82) (envelope-from ) id 1gC7tl-0004FP-7E; Mon, 15 Oct 2018 14:47:26 -0400 Date: Mon, 15 Oct 2018 21:47:34 +0300 Message-Id: <83r2grrqrd.fsf@gnu.org> From: Eli Zaretskii To: Alan Mackenzie In-reply-to: <20181015183301.GD5623@ACM> (message from Alan Mackenzie on Mon, 15 Oct 2018 18:33:01 +0000) Subject: Re: bug#32863: Unsatisfactory "definition" of "vertical scroll position" in Emacs lisp manual and doc string of window-vscroll References: <20180928152832.GA5172@ACM> <837ej5710d.fsf@gnu.org> <20181015114803.GB5623@ACM> <83y3azrzt6.fsf@gnu.org> <20181015183301.GD5623@ACM> X-detected-operating-system: by eggs.gnu.org: GNU/Linux 2.2.x-3.x [generic] X-Received-From: 2001:4830:134:3::e X-Spam-Score: -5.0 (-----) X-Debbugs-Envelope-To: 32863 Cc: 32863@debbugs.gnu.org X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: debbugs-submit-bounces@debbugs.gnu.org Sender: "Debbugs-submit" X-Spam-Score: -6.0 (------) > Date: Mon, 15 Oct 2018 18:33:01 +0000 > Cc: 32863@debbugs.gnu.org > From: Alan Mackenzie > > OK, amended (final?) version: LGTM, thanks. From debbugs-submit-bounces@debbugs.gnu.org Mon Oct 15 15:21:40 2018 Received: (at 32863-done) by debbugs.gnu.org; 15 Oct 2018 19:21:40 +0000 Received: from localhost ([127.0.0.1]:51453 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1gC8Qu-0001OH-BE for submit@debbugs.gnu.org; Mon, 15 Oct 2018 15:21:40 -0400 Received: from colin.muc.de ([193.149.48.1]:27805 helo=mail.muc.de) by debbugs.gnu.org with smtp (Exim 4.84_2) (envelope-from ) id 1gC8Qs-0001O9-A4 for 32863-done@debbugs.gnu.org; Mon, 15 Oct 2018 15:21:38 -0400 Received: (qmail 75618 invoked by uid 3782); 15 Oct 2018 19:21:37 -0000 Received: from acm.muc.de (p5B14745F.dip0.t-ipconnect.de [91.20.116.95]) by colin.muc.de (tmda-ofmipd) with ESMTP; Mon, 15 Oct 2018 21:21:36 +0200 Received: (qmail 29024 invoked by uid 1000); 15 Oct 2018 19:13:54 -0000 Date: Mon, 15 Oct 2018 19:13:54 +0000 To: Eli Zaretskii Subject: Re: bug#32863: Unsatisfactory "definition" of "vertical scroll position" in Emacs lisp manual and doc string of window-vscroll Message-ID: <20181015191354.GE5623@ACM> References: <20180928152832.GA5172@ACM> <837ej5710d.fsf@gnu.org> <20181015114803.GB5623@ACM> <83y3azrzt6.fsf@gnu.org> <20181015183301.GD5623@ACM> <83r2grrqrd.fsf@gnu.org> MIME-Version: 1.0 Content-Type: text/plain; charset=us-ascii Content-Disposition: inline In-Reply-To: <83r2grrqrd.fsf@gnu.org> User-Agent: Mutt/1.10.1 (2018-07-13) X-Delivery-Agent: TMDA/1.1.12 (Macallan) From: Alan Mackenzie X-Primary-Address: acm@muc.de X-Spam-Score: -0.0 (/) X-Debbugs-Envelope-To: 32863-done Cc: 32863-done@debbugs.gnu.org X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: debbugs-submit-bounces@debbugs.gnu.org Sender: "Debbugs-submit" X-Spam-Score: -1.0 (-) Hello, Eli. On Mon, Oct 15, 2018 at 21:47:34 +0300, Eli Zaretskii wrote: > > Date: Mon, 15 Oct 2018 18:33:01 +0000 > > Cc: 32863@debbugs.gnu.org > > From: Alan Mackenzie > > OK, amended (final?) version: > LGTM, thanks. I've committed it, and I'm closing the bug. -- Alan Mackenzie (Nuremberg, Germany). From unknown Fri Aug 15 12:51:40 2025 Received: (at fakecontrol) by fakecontrolmessage; To: internal_control@debbugs.gnu.org From: Debbugs Internal Request Subject: Internal Control Message-Id: bug archived. Date: Tue, 13 Nov 2018 12:24:11 +0000 User-Agent: Fakemail v42.6.9 # This is a fake control message. # # The action: # bug archived. thanks # This fakemail brought to you by your local debbugs # administrator