Subject: bug#15783: 24.3; posn-at-x-y is relative to the buffer area, posn-at-point is relative to the text area.

From: Stefan Kangas <[email-masked]>
Date: Fri, 22 Oct 2021 19:27:38 -0400

tags 15783 + patch
thanks

Eli Zaretskii <[email-masked]> writes:

>>   3. Actual:
>>      WHOLE is nil:     X is relative to text area; Y to window area
>>      WHOLE is non-nil: X and Y are relative to the window area
>
> This is the same confusion about what "text area" means that is
> present in many of our conversations.  The manual says:
>
>   ‘Text Area’
>        The “text area” of a frame is a somewhat fictitious area that can
>        be embedded in the native frame.  Its position is unspecified.  Its
>        width can be obtained by removing from that of the native width the
>        widths of the internal border, one vertical scroll bar, and one
>        left and one right fringe if they are specified for this frame, see
>        *note Layout Parameters::.  Its height can be obtained by removing
>        from that of the native height the widths of the internal border
>        and the heights of the frame’s internal menu and tool bars and one
>        horizontal scroll bar if specified for this frame.
>
> This means the "text area" _includes_ the header line.  So when you
> get this result in "emacs -Q":
>
>   M-: (setq header-line-format "Hi There") RET
>   M-: (posn-at-x-y 0 0)
>    => (#<window 3 on *scratch*> header-line (8 . 0) 0 ("Hi There" . 1) nil (1 . -1) nil (0 . 0) (8 . 16))
>
> it tells you that the origin is the left corner of the text area,
> because the X coordinate is 8, not zero, and the position in the
> header-line string is 1, not zero.  If, OTOH, you invoke posn-at-x-y
> with last argument non-nil, you will get zero for X, which means the
> origin is the left corner of the window, which is at the left edge of
> the left fringe.
>
> Therefore, the doc string is accurately describing the actual behavior.
> Do you agree now?

I looked into this for a bit, and as far as I understand, Eli is
correct.

> We are not going back.  The current behavior, while less than ideal,
> caused zero bugs since it was introduced, AFAIK.  The documentation
> should be updated, of course (I see that the above-mentioned commit
> didn't do that, which is probably why the old description survived to
> this day).

How does the attached patch look?
From 20d555bff78de98a4cde7c04fa24b688b2a1d5cd Mon Sep 17 00:00:00 2001
From: Stefan Kangas <[email-masked]>
Date: Sat, 23 Oct 2021 01:19:48 +0200
Subject: [PATCH] Fix documentation of posn-at-x-y

* doc/lispref/commands.texi (Accessing Mouse): Fix documentation of
'posn-at-x-y' to match docstring.  (Bug#15783)
---
 doc/lispref/commands.texi | 9 +++++----
 1 file changed, 5 insertions(+), 4 deletions(-)

diff --git a/doc/lispref/commands.texi b/doc/lispref/commands.texi
index 3425880fec..6c853a3d23 100644
--- a/doc/lispref/commands.texi
+++ b/doc/lispref/commands.texi
@@ -2354,10 +2354,11 @@ Accessing Mouse
 coordinates @var{x} and @var{y} in a specified frame or window,
 @var{frame-or-window}, which defaults to the selected window.
 The coordinates @var{x} and @var{y} are relative to the
-frame or window used.
-If @var{whole} is @code{nil}, the coordinates are relative
-to the window text area, otherwise they are relative to
-the entire window area including scroll bars, margins and fringes.
+text area of the selected window.
+If @var{whole} is @code{nil}, the @var{x} coordinate is relative to
+the entire window area including scroll bars, margins and fringes,
+while the @var{y} coordinate remains unchanged and relative to the
+text area.
 @end defun
 
 @node Accessing Scroll
-- 
2.30.2