[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
[Emacs-diffs] emacs-26 a30a6c3: Improve documentation of set-window-star
From: |
Eli Zaretskii |
Subject: |
[Emacs-diffs] emacs-26 a30a6c3: Improve documentation of set-window-start |
Date: |
Sat, 6 Apr 2019 04:23:05 -0400 (EDT) |
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);
[Prev in Thread] |
Current Thread |
[Next in Thread] |
- [Emacs-diffs] emacs-26 a30a6c3: Improve documentation of set-window-start,
Eli Zaretskii <=