If your question is what is the use of set-window-point
then the answer is that it sets the window-point value for the given window's buffer.
See the Elisp manual, node Window Point
. It starts by telling you this, which should already answer your question:
Each window has its own value of point (*note Point::), independent of
the value of point in other windows displaying the same buffer. This
makes it useful to have multiple windows showing one buffer.
set-window-point
gives you a way to set the point value for a given window.
Wrt the question of why the code you posted is used in append-to-buffer
-
Here is the full code:
(defun append-to-buffer (buffer start end)
"Append to specified buffer the text of the region.
It is inserted into that buffer before its point.
When calling from a program, give three arguments:
BUFFER (or buffer name), START and END.
START and END specify the portion of the current buffer to be copied."
(interactive
(list (read-buffer "Append to buffer: " (other-buffer (current-buffer) t))
(region-beginning) (region-end)))
(let* ((oldbuf (current-buffer))
(append-to (get-buffer-create buffer))
(windows (get-buffer-window-list append-to t t))
point)
(save-excursion
(with-current-buffer append-to
(setq point (point))
(barf-if-buffer-read-only)
(insert-buffer-substring oldbuf start end)
(dolist (window windows)
(when (= (window-point window) point)
(set-window-point window (point))))))))
The part you quoted comes right after (a) saving the current value of point to a variable named point
and then (b) inserting a string before point.
That last part is significant: point moves forward by the length of the inserted string. The doc string of insert-buffer-substring
does not say this explicitly - but it should. (The doc string of function insert
does say this explicitly. I just filed Emacs bug #20421, to ask that this doc string be improved this way.)
This means that after the string is inserted the saved position (in variable point
) typically is no longer equal to (point)
.
What the dolist
loop does is to check existing windows for the same buffer, to see if any of them still have their window-point
pointing to the saved position, point
, and if so, updating those window points to the new position of (point)
, that is, to where the cursor is now.
In sum, it resyncs all windows showing the same buffer, with respect to their cursor positions (their window points).
(More typically, the variable used to save the original value of (point)
would be called opoint
or orig-point
or some such, and not just point
. That would make the code a bit clearer - it is too easy to misread the difference between point
(a variable) and (point)
(the current point value).