From a30a6c3019ac09ede1cc47671083b2e9ecdbffdf Mon Sep 17 00:00:00 2001 From: Eli Zaretskii Date: Sat, 6 Apr 2019 11:22:13 +0300 Subject: [PATCH] Improve documentation of set-window-start * doc/lispref/windows.texi (Window Start and End): * src/window.c (Fset_window_start): Document that reliable setting of a window start position requires to adjust point to be visible. (Bug#34038) --- doc/lispref/windows.texi | 22 +++++++++++++++------- src/window.c | 7 ++++++- 2 files changed, 21 insertions(+), 8 deletions(-) diff --git a/doc/lispref/windows.texi b/doc/lispref/windows.texi index 27940e12c79..f4395c12d26 100644 --- a/doc/lispref/windows.texi +++ b/doc/lispref/windows.texi @@ -4625,13 +4625,14 @@ This function sets the display-start position of @var{window} to @var{position} in @var{window}'s buffer. It returns @var{position}. The display routines insist that the position of point be visible when a -buffer is displayed. Normally, they change the display-start position -(that is, scroll the window) whenever necessary to make point visible. -However, if you specify the start position with this function using -@code{nil} for @var{noforce}, it means you want display to start at -@var{position} even if that would put the location of point off the -screen. If this does place point off screen, the display routines move -point to the left margin on the middle line in the window. +buffer is displayed. Normally, they select the display-start position +according to their internal logic (and scroll the window if necessary) +to make point visible. However, if you specify the start position +with this function using @code{nil} for @var{noforce}, it means you +want display to start at @var{position} even if that would put the +location of point off the screen. If this does place point off +screen, the display routines attempt to move point to the left margin +on the middle line in the window. For example, if point @w{is 1} and you set the start of the window @w{to 37}, the start of the next line, point will be above the top @@ -4678,6 +4679,13 @@ it is still 1 when redisplay occurs. Here is an example: @end group @end example +If the attempt to make point visible (i.e., in a fully-visible screen +line) fails, the display routines will disregard the requested +window-start position and compute a new one anyway. Thus, for +reliable results Lisp programs that call this function should always +move point to be inside the window whose display starts at +@var{position}. + If @var{noforce} is non-@code{nil}, and @var{position} would place point off screen at the next redisplay, then redisplay computes a new window-start position that works well with point, and thus @var{position} is not used. diff --git a/src/window.c b/src/window.c index 04183abb7c5..dfac3b5b879 100644 --- a/src/window.c +++ b/src/window.c @@ -1704,7 +1704,12 @@ DEFUN ("set-window-start", Fset_window_start, Sset_window_start, 2, 3, 0, doc: /* Make display in WINDOW start at position POS in WINDOW's buffer. WINDOW must be a live window and defaults to the selected one. Return POS. Optional third arg NOFORCE non-nil inhibits next redisplay from -overriding motion of point in order to display at this exact start. */) +overriding motion of point in order to display at this exact start. + +For reliable setting of WINDOW start position, make sure point is +at a position that will be visible when that start is in effect, +otherwise there's a chance POS will be disregarded, e.g., if point +winds up in a partially-visible line. */) (Lisp_Object window, Lisp_Object pos, Lisp_Object noforce) { register struct window *w = decode_live_window (window); -- 2.39.2