Why do org-agenda-switch-to and org-agenda-goto put the point in different spots in the target buffer?

Why do org-agenda-switch-to and org-agenda-goto put the point in different spots in the target buffer?

[Rohit Patnaik]

I've gotten back into using org-agenda to manage my todos, and I noticed an odd discrepancy in behavior. When I hit RET in the agenda buffer to go to the TODO entry in the original org file, I see that the point is on the DEADLINE line. However, when I hit TAB, I find that the point is placed at the beginning of the heading. Looking at the source of org-agenda.el, I find that TAB is bound to `org-agenda-goto', which does the following:

(recenter (/ (window-height) 2))
(org-back-to-heading t)

RET, on the other hand, is bound to `org-agenda-switch-to', which does not have these lines, and thus does not place the point on the heading.

Is there a reason for this discrepancy between the two functions? I'm asking because I prefer the point placement behavior of `org-agenda-goto', but I use `org-agenda-switch-to' because switches to the target org file in the current window rather than opening a new window. Would there be any issues with me taking the recentering and point placement behavior from `org-agenda-goto' and adding it to `org-agenda-switch-to`?

Thanks,
Rohit

Re: Why do org-agenda-switch-to and org-agenda-goto put the point in different spots in the target buffer?

[Ihor Radchenko]

"Rohit Patnaik" <quanticle@quanticle.net> writes:

> I've gotten back into using org-agenda to manage my todos, and I noticed an odd discrepancy in behavior. When I hit RET in the agenda buffer to go to the TODO entry in the original org file, I see that the point is on the DEADLINE line. However, when I hit TAB, I find that the point is placed at the beginning of the heading. Looking at the source of org-agenda.el, I find that TAB is bound to `org-agenda-goto', which does the following:
>
> (recenter (/ (window-height) 2))
> (org-back-to-heading t)
>
> RET, on the other hand, is bound to `org-agenda-switch-to', which does not have these lines, and thus does not place the point on the heading.
>
> Is there a reason for this discrepancy between the two functions? I'm
> asking because I prefer the point placement behavior of
> `org-agenda-goto', but I use `org-agenda-switch-to' because switches
> to the target org file in the current window rather than opening a new
> window.

org-agenda-switch-to jumps to the actual agenda match (usually a
timestamp). It may or may not be close to the headline (think of active
timestamp inside notes). Such behaviour, albeit undocumented, may be
useful for some users. I'd rather not change it.

If you want to force org-agenda-switch-to to jump back to headline, you
can modify org-agenda-after-show-hook.

> Would there be any issues with me taking the recentering and point
> placement behavior from `org-agenda-goto' and adding it to
> `org-agenda-switch-to`?

Recentering is purely a visual thing. It should be safe to add.

-- 
Ihor Radchenko,
Org mode contributor,
Learn more about Org mode at https://orgmode.org/.
Support Org development at https://liberapay.com/org-mode,
or support my work at https://liberapay.com/yantar92

Re: Why do org-agenda-switch-to and org-agenda-goto put the point in different spots in the target buffer?

[Rohit Patnaik]

[-- Attachment #1: Type: text/plain, Size: 751 bytes --]

> org-agenda-switch-to jumps to the actual agenda match (usually a timestamp).
> It may or may not be close to the headline (think of active timestamp inside
> notes). Such behaviour, albeit undocumented, may be useful for some users. I'd
> rather not change it.

Okay, that makes sense.

> Recentering is purely a visual thing. It should be safe to add.

I've added the recentering behavior in the attached patch. The recentering part
was more important for me than the point jumping to the heading, because
sometimes the match would appear at the very top of the screen and I'd have to
scroll up manually to see the heading. If the screen is centered on the match,
then it's likely that the heading will also be visible in the window.

Thanks,
Rohit

[-- Attachment #2: 0001-org-agenda.el-Make-org-agenda-switch-to-recenter-on-.patch --]
[-- Type: application/octet-stream, Size: 2009 bytes --]

From c92917f09eb1b1ef043dd92c914bd88fa72e79d9 Mon Sep 17 00:00:00 2001
From: Rohit Patnaik <quanticle@quanticle.net>
Date: Fri, 9 Sep 2022 14:55:04 -0500
Subject: [PATCH] org-agenda.el: Make `org-agenda-switch-to' recenter on the
 match

* org-agenda.el (org-agenda-switch-to): Port the recentering behavior from
`org-agenda-goto' to `org-agenda-switch-to'.

This change centers the screen on the match that `org-agenda-switch-to' jumps to
when the user hits RET in the agenda buffer.  This prevents the match from
appearing at the very top or very bottom of the screen, allowing the user to see
more context around the match.

TINYCHANGE
---
 etc/ORG-NEWS       | 9 +++++++++
 lisp/org-agenda.el | 1 +
 2 files changed, 10 insertions(+)

diff --git a/etc/ORG-NEWS b/etc/ORG-NEWS
index a7f32671e..82eca2d62 100644
--- a/etc/ORG-NEWS
+++ b/etc/ORG-NEWS
@@ -489,6 +489,15 @@ support in LaTeX.  The new =babel= syntax for loading languages via
 =ini= files and the new command =\babelprovide= (see:
 https://mirrors.ctan.org/macros/latex/required/babel/base/babel.pdf)
 are also supported.
+
+*** ~org-agenda-switch-to~ recenters the window on the agenda match
+
+~org-agenda-switch-to~ now recenters the window on the agenda match,
+similar to ~org-agenda-goto~. This ensures that the user can see more
+of the context for the agenda match, whereas previously the match may
+have appeared at the top of the window, requiring the user to scroll
+up to see the headline or other context around the match.
+
 * Version 9.5
 
 ** Important announcements and breaking changes
diff --git a/lisp/org-agenda.el b/lisp/org-agenda.el
index 053232078..e9ab54527 100644
--- a/lisp/org-agenda.el
+++ b/lisp/org-agenda.el
@@ -9741,6 +9741,7 @@ displayed Org file fills the frame."
       (goto-char pos)
       (when (derived-mode-p 'org-mode)
 	(org-fold-show-context 'agenda)
+        (recenter (/ (window-height) 2))
 	(run-hooks 'org-agenda-after-show-hook)))))
 
 (defun org-agenda-goto-mouse (ev)
-- 
2.37.3.windows.1

Re: Why do org-agenda-switch-to and org-agenda-goto put the point in different spots in the target buffer?

[Ihor Radchenko]

"Rohit Patnaik" <quanticle@quanticle.net> writes:

>> Recentering is purely a visual thing. It should be safe to add.
>
> I've added the recentering behavior in the attached patch. The recentering part
> was more important for me than the point jumping to the heading, because
> sometimes the match would appear at the very top of the screen and I'd have to
> scroll up manually to see the heading. If the screen is centered on the match,
> then it's likely that the heading will also be visible in the window.

Note that your previous contribution was around 15LOC. To contribute
further, you need to complete the FSF copyright assignment. See
https://orgmode.org/worg/org-contribute.html#copyright
The process normally takes less than 5 working days.

> @@ -9741,6 +9741,7 @@ displayed Org file fills the frame."
>        (goto-char pos)
>        (when (derived-mode-p 'org-mode)
>  	(org-fold-show-context 'agenda)
> +        (recenter (/ (window-height) 2))

Another option could be extending org-fold-show-context-detail so that
one can set something like

((agenda . local recenter) ;; <---
 (bookmark-jump . lineage)
 (isearch . lineage)
 (default . ancestors))

It will be more flexible.

-- 
Ihor Radchenko,
Org mode contributor,
Learn more about Org mode at https://orgmode.org/.
Support Org development at https://liberapay.com/org-mode,
or support my work at https://liberapay.com/yantar92

Re: Why do org-agenda-switch-to and org-agenda-goto put the point in different spots in the target buffer?

[Max Nikulin]

On 10/09/2022 03:00, Rohit Patnaik wrote:
> 
> sometimes the match would appear at the very top of the screen and I'd have to
> scroll up manually to see the heading.

 From my point of view, "have to scroll up manually" sounds too dramatic 
for the C-l (`recenter-top-bottom') keystroke. On the other hand I can 
not say that I believe that current position in the window after various 
jumps is optimal, but I can not describe what I would like to have in 
each case, so C-l is a rescue.