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: Fri, 28 Sep 2018 15:28:32 +0000 Message-ID: <20180928152832.GA5172@ACM> NNTP-Posting-Host: blaine.gmane.org Mime-Version: 1.0 Content-Type: text/plain; charset=us-ascii X-Trace: blaine.gmane.org 1538148882 20684 195.159.176.226 (28 Sep 2018 15:34:42 GMT) X-Complaints-To: usenet@blaine.gmane.org NNTP-Posting-Date: Fri, 28 Sep 2018 15:34:42 +0000 (UTC) User-Agent: Mutt/1.10.1 (2018-07-13) To: 32863@debbugs.gnu.org Original-X-From: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane.org@gnu.org Fri Sep 28 17:34:38 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 1g5ums-0005GO-Cw for geb-bug-gnu-emacs@m.gmane.org; Fri, 28 Sep 2018 17:34:38 +0200 Original-Received: from localhost ([::1]:44050 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1g5uoz-0001af-3e for geb-bug-gnu-emacs@m.gmane.org; Fri, 28 Sep 2018 11:36:49 -0400 Original-Received: from eggs.gnu.org ([2001:4830:134:3::10]:54306) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1g5unU-0000jO-QG for bug-gnu-emacs@gnu.org; Fri, 28 Sep 2018 11:35:21 -0400 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1g5unG-0008Mb-9e for bug-gnu-emacs@gnu.org; Fri, 28 Sep 2018 11:35:07 -0400 Original-Received: from debbugs.gnu.org ([208.118.235.43]:53520) by eggs.gnu.org with esmtps (TLS1.0:RSA_AES_128_CBC_SHA1:16) (Exim 4.71) (envelope-from ) id 1g5unF-0008M0-SL for bug-gnu-emacs@gnu.org; Fri, 28 Sep 2018 11:35:02 -0400 Original-Received: from Debian-debbugs by debbugs.gnu.org with local (Exim 4.84_2) (envelope-from ) id 1g5unF-0001wc-Sb for bug-gnu-emacs@gnu.org; Fri, 28 Sep 2018 11:35:01 -0400 X-Loop: help-debbugs@gnu.org Resent-From: Alan Mackenzie Original-Sender: "Debbugs-submit" Resent-CC: bug-gnu-emacs@gnu.org Resent-Date: Fri, 28 Sep 2018 15:35:01 +0000 Resent-Message-ID: Resent-Sender: help-debbugs@gnu.org X-GNU-PR-Message: report 32863 X-GNU-PR-Package: emacs X-GNU-PR-Keywords: X-Debbugs-Original-To: bug-gnu-emacs@gnu.org Original-Received: via spool by submit@debbugs.gnu.org id=B.15381488607417 (code B ref -1); Fri, 28 Sep 2018 15:35:01 +0000 Original-Received: (at submit) by debbugs.gnu.org; 28 Sep 2018 15:34:20 +0000 Original-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 Original-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 Original-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 Original-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 Original-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 Original-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 Original-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 Original-Received: (qmail 42527 invoked by uid 3782); 28 Sep 2018 15:33:58 -0000 Original-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 Original-Received: (qmail 15859 invoked by uid 1000); 28 Sep 2018 15:28:32 -0000 Content-Disposition: inline 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-detected-operating-system: by eggs.gnu.org: GNU/Linux 2.6.x 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:150735 Archived-At: 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).