From 68418691267ad7cdbb2c5f0462a4f906e112f861 Mon Sep 17 00:00:00 2001
From: Martin Rudalics <rudalics@gmx.at>
Date: Mon, 5 Jan 2026 09:29:09 +0100
Subject: [PATCH] In Elisp manual warn about unpredictable changes of point
 (Bug#79927)

* doc/lispref/positions.texi (Point): Define "buffer point".
* doc/lispref/windows.texi (Window Point): Say that buffer point
can change in unpredictable ways when windows get selected
(Bug#79927).
---
 doc/lispref/positions.texi | 16 ++++++++++------
 doc/lispref/windows.texi   | 12 ++++++++++++
 2 files changed, 22 insertions(+), 6 deletions(-)

diff --git a/doc/lispref/positions.texi b/doc/lispref/positions.texi
index 89fdca1791e..9fcffee2ee0 100644
--- a/doc/lispref/positions.texi
+++ b/doc/lispref/positions.texi
@@ -57,14 +57,18 @@ buffer size plus 1.  If narrowing is in effect (@pxref{Narrowing}), then
 point is constrained to fall within the accessible portion of the buffer
 (possibly at one end of it).
 
+@cindex buffer point
   Each buffer has its own value of point, which is independent of the
 value of point in other buffers.  Each window also has a value of point,
-which is independent of the value of point in other windows on the same
-buffer.  This is why point can have different values in various windows
-that display the same buffer.  When a buffer appears in only one window,
-the buffer's point and the window's point normally have the same value,
-so the distinction is rarely important.  @xref{Window Point}, for more
-details.
+which is independent of the value of point in other windows showing the
+same buffer.  This is why the cursor may appear at different positions
+in various windows that display the same buffer.  Wherever necessary, we
+use the terms @dfn{buffer point} for the unique position of point of a
+specific buffer and the term @dfn{window point} for the position of
+point in a specific window showing that buffer.  When a buffer appears
+in only one window, its buffer's point and that window's point normally
+have the same value, so the distinction is rarely important.
+@xref{Window Point}, for more details.
 
 @defun point
 @cindex current buffer position
diff --git a/doc/lispref/windows.texi b/doc/lispref/windows.texi
index 786308dc310..940f19985ea 100644
--- a/doc/lispref/windows.texi
+++ b/doc/lispref/windows.texi
@@ -5872,6 +5872,18 @@ the other windows are stored in those windows.
 @item
 As long as the selected window displays the current buffer, the window's
 point and the buffer's point always move together; they remain equal.
+
+@item
+Many Emacs functions temporarily select a window in order to operate on
+its contents.  This will move the buffer point (@pxref{Point}) of that
+window's buffer to the position of the window point of that window and
+not restore the buffer point to its previous position when terminating
+the temporary selection.  This means that when one and the same buffer
+is simultaneously displayed in more than one window, its buffer point
+may change in unpredictable ways to the position of window point of any
+of these windows as a side-effect of things like redisplay, calling
+@code{with-selected-window} (@pxref{Selecting Windows}) or running
+@code{window-configuration-change-hook} (@pxref{Window Hooks}).
 @end itemize
 
 @cindex cursor