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: Mon, 15 Oct 2018 18:32:05 +0300 Message-ID: <83y3azrzt6.fsf@gnu.org> References: <20180928152832.GA5172@ACM> <837ej5710d.fsf@gnu.org> <20181015114803.GB5623@ACM> NNTP-Posting-Host: blaine.gmane.org X-Trace: blaine.gmane.org 1539617470 4982 195.159.176.226 (15 Oct 2018 15:31:10 GMT) X-Complaints-To: usenet@blaine.gmane.org NNTP-Posting-Date: Mon, 15 Oct 2018 15:31:10 +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 Mon Oct 15 17:31:06 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 1gC4pk-0001AU-BI for geb-bug-gnu-emacs@m.gmane.org; Mon, 15 Oct 2018 17:31:05 +0200 Original-Received: from localhost ([::1]:52832 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1gC4rq-0004DX-Td for geb-bug-gnu-emacs@m.gmane.org; Mon, 15 Oct 2018 11:33:14 -0400 Original-Received: from eggs.gnu.org ([2001:4830:134:3::10]:44235) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1gC4rj-0004DF-FT for bug-gnu-emacs@gnu.org; Mon, 15 Oct 2018 11:33:08 -0400 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1gC4re-0004nr-Ns for bug-gnu-emacs@gnu.org; Mon, 15 Oct 2018 11:33:07 -0400 Original-Received: from debbugs.gnu.org ([208.118.235.43]:46728) by eggs.gnu.org with esmtps (TLS1.0:RSA_AES_128_CBC_SHA1:16) (Exim 4.71) (envelope-from ) id 1gC4re-0004na-JU for bug-gnu-emacs@gnu.org; Mon, 15 Oct 2018 11:33:02 -0400 Original-Received: from Debian-debbugs by debbugs.gnu.org with local (Exim 4.84_2) (envelope-from ) id 1gC4re-0002TP-C6 for bug-gnu-emacs@gnu.org; Mon, 15 Oct 2018 11:33:02 -0400 X-Loop: help-debbugs@gnu.org Resent-From: Eli Zaretskii Original-Sender: "Debbugs-submit" Resent-CC: bug-gnu-emacs@gnu.org Resent-Date: Mon, 15 Oct 2018 15:33: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.15396175297496 (code B ref 32863); Mon, 15 Oct 2018 15:33:02 +0000 Original-Received: (at 32863) by debbugs.gnu.org; 15 Oct 2018 15:32:09 +0000 Original-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 Original-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 Original-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 Original-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 Original-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 In-reply-to: <20181015114803.GB5623@ACM> (message from Alan Mackenzie on Mon, 15 Oct 2018 11:48:03 +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:151271 Archived-At: > 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.