From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.org!.POSTED!not-for-mail From: Eli Zaretskii Newsgroups: gmane.emacs.bugs Subject: bug#32863: Unsatisfactory "definition" of "vertical scroll position" in Emacs lisp manual and doc string of window-vscroll Date: Sat, 29 Sep 2018 00:41:54 +0300 Message-ID: <837ej5710d.fsf@gnu.org> References: <20180928152832.GA5172@ACM> NNTP-Posting-Host: blaine.gmane.org X-Trace: blaine.gmane.org 1538170866 29399 195.159.176.226 (28 Sep 2018 21:41:06 GMT) X-Complaints-To: usenet@blaine.gmane.org NNTP-Posting-Date: Fri, 28 Sep 2018 21:41:06 +0000 (UTC) Cc: 32863@debbugs.gnu.org To: Alan Mackenzie Original-X-From: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane.org@gnu.org Fri Sep 28 23:41:02 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 1g60VR-0007X0-Cc for geb-bug-gnu-emacs@m.gmane.org; Fri, 28 Sep 2018 23:41:01 +0200 Original-Received: from localhost ([::1]:46276 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1g60XX-0004a3-Om for geb-bug-gnu-emacs@m.gmane.org; Fri, 28 Sep 2018 17:43:11 -0400 Original-Received: from eggs.gnu.org ([2001:4830:134:3::10]:34128) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1g60XR-0004Zv-8C for bug-gnu-emacs@gnu.org; Fri, 28 Sep 2018 17:43:05 -0400 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1g60XO-0006dR-30 for bug-gnu-emacs@gnu.org; Fri, 28 Sep 2018 17:43:05 -0400 Original-Received: from debbugs.gnu.org ([208.118.235.43]:53876) by eggs.gnu.org with esmtps (TLS1.0:RSA_AES_128_CBC_SHA1:16) (Exim 4.71) (envelope-from ) id 1g60XN-0006dL-VB for bug-gnu-emacs@gnu.org; Fri, 28 Sep 2018 17:43:02 -0400 Original-Received: from Debian-debbugs by debbugs.gnu.org with local (Exim 4.84_2) (envelope-from ) id 1g60XN-0006xc-RQ for bug-gnu-emacs@gnu.org; Fri, 28 Sep 2018 17:43:01 -0400 X-Loop: help-debbugs@gnu.org Resent-From: Eli Zaretskii Original-Sender: "Debbugs-submit" Resent-CC: bug-gnu-emacs@gnu.org Resent-Date: Fri, 28 Sep 2018 21:43:01 +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.153817093926694 (code B ref 32863); Fri, 28 Sep 2018 21:43:01 +0000 Original-Received: (at 32863) by debbugs.gnu.org; 28 Sep 2018 21:42:19 +0000 Original-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 Original-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 Original-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 Original-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 Original-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 In-reply-to: <20180928152832.GA5172@ACM> (message from Alan Mackenzie on Fri, 28 Sep 2018 15:28:32 +0000) X-detected-operating-system: by eggs.gnu.org: GNU/Linux 2.2.x-3.x [generic] 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:150745 Archived-At: > 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.