From 73babba26aa714c34aa8d9473ba5b55ce110a215 Mon Sep 17 00:00:00 2001 From: Alan Mackenzie Date: Mon, 15 Oct 2018 19:04:05 +0000 Subject: [PATCH] Clarify documentation of fractional vertical scrolling and some doc strings * doc/lispref/windows.texi (vertical scrolling): Clarify the meaning of vertical scrolling by referring to tall screen lines, images, and the display action. Clarify an ambiguous English tense. * src/window.c (window-vscroll, set-window-vscroll): Amend doc strings to refer to display. --- doc/lispref/windows.texi | 20 +++++++++++--------- src/window.c | 4 ++++ 2 files changed, 15 insertions(+), 9 deletions(-) diff --git a/doc/lispref/windows.texi b/doc/lispref/windows.texi index 265067146da..960573d8653 100644 --- a/doc/lispref/windows.texi +++ b/doc/lispref/windows.texi @@ -4200,18 +4200,20 @@ point at the middle, top, and bottom of the window. @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 diff --git a/src/window.c b/src/window.c index 409b01f302e..9026a7b5f2a 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 displaying 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 displaying 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. -- 2.39.5