[Emacs-diffs] emacs-26 a30a6c3: Improve documentation of set-window-start

[Eli Zaretskii]

branch: emacs-26
commit a30a6c3019ac09ede1cc47671083b2e9ecdbffdf
Author: Eli Zaretskii <address@hidden>
Commit: Eli Zaretskii <address@hidden>

    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 27940e12..f4395c1 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
address@hidden for @var{noforce}, it means you want display to start at
address@hidden 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
address@hidden
+
 If @var{noforce} is address@hidden, 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 04183ab..dfac3b5 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);