From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.org!.POSTED!not-for-mail From: Alan Mackenzie Newsgroups: gmane.emacs.bugs Subject: bug#32863: Unsatisfactory "definition" of "vertical scroll position" in Emacs lisp manual and doc string of window-vscroll Date: Mon, 15 Oct 2018 11:48:03 +0000 Message-ID: <20181015114803.GB5623@ACM> References: <20180928152832.GA5172@ACM> <837ej5710d.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 1539605920 32498 195.159.176.226 (15 Oct 2018 12:18:40 GMT) X-Complaints-To: usenet@blaine.gmane.org NNTP-Posting-Date: Mon, 15 Oct 2018 12:18:40 +0000 (UTC) User-Agent: Mutt/1.10.1 (2018-07-13) Cc: 32863@debbugs.gnu.org To: Eli Zaretskii Original-X-From: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane.org@gnu.org Mon Oct 15 14:18:36 2018 Return-path: Envelope-to: geb-bug-gnu-emacs@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 1gC1pT-0008M6-Hl for geb-bug-gnu-emacs@m.gmane.org; Mon, 15 Oct 2018 14:18:35 +0200 Original-Received: from localhost ([::1]:51958 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1gC1rZ-0008TY-CD for geb-bug-gnu-emacs@m.gmane.org; Mon, 15 Oct 2018 08:20:45 -0400 Original-Received: from eggs.gnu.org ([2001:4830:134:3::10]:41001) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1gC1Tj-0006GS-Oc for bug-gnu-emacs@gnu.org; Mon, 15 Oct 2018 07:56:08 -0400 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1gC1Te-00047J-Nz for bug-gnu-emacs@gnu.org; Mon, 15 Oct 2018 07:56:07 -0400 Original-Received: from debbugs.gnu.org ([208.118.235.43]:45608) by eggs.gnu.org with esmtps (TLS1.0:RSA_AES_128_CBC_SHA1:16) (Exim 4.71) (envelope-from ) id 1gC1Te-000470-H2 for bug-gnu-emacs@gnu.org; Mon, 15 Oct 2018 07:56:02 -0400 Original-Received: from Debian-debbugs by debbugs.gnu.org with local (Exim 4.84_2) (envelope-from ) id 1gC1Te-0005iN-6A for bug-gnu-emacs@gnu.org; Mon, 15 Oct 2018 07:56:02 -0400 X-Loop: help-debbugs@gnu.org Resent-From: Alan Mackenzie Original-Sender: "Debbugs-submit" Resent-CC: bug-gnu-emacs@gnu.org Resent-Date: Mon, 15 Oct 2018 11:56:02 +0000 Resent-Message-ID: Resent-Sender: help-debbugs@gnu.org X-GNU-PR-Message: followup 32863 X-GNU-PR-Package: emacs X-GNU-PR-Keywords: Original-Received: via spool by 32863-submit@debbugs.gnu.org id=B32863.153960455121948 (code B ref 32863); Mon, 15 Oct 2018 11:56:02 +0000 Original-Received: (at 32863) by debbugs.gnu.org; 15 Oct 2018 11:55:51 +0000 Original-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 Original-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 Original-Received: (qmail 60130 invoked by uid 3782); 15 Oct 2018 11:55:47 -0000 Original-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 Original-Received: (qmail 6677 invoked by uid 1000); 15 Oct 2018 11:48:03 -0000 Content-Disposition: inline In-Reply-To: <837ej5710d.fsf@gnu.org> X-Delivery-Agent: TMDA/1.1.12 (Macallan) X-Primary-Address: acm@muc.de X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list X-detected-operating-system: by eggs.gnu.org: GNU/Linux 2.2.x-3.x [generic] X-Received-From: 208.118.235.43 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.org@gnu.org Original-Sender: "bug-gnu-emacs" Xref: news.gmane.org gmane.emacs.bugs:151263 Archived-At: 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).