Add final hooks to S-/M-/S-M-cursor commands

Add final hooks to S-/M-/S-M-cursor commands

[Evgenii Klimov]

`org-shiftup' and other S-cursor commands not only provide initial
hooks but also final hooks, while M-cursor and S-M-cursor commands
lack them. These patches add final hooks to all of these commands and
document both hooks in the docstring if they are not already present.

[PATCH 1/3] lisp/org.el: Add final hooks to the M-cursor commands

[Evgenii Klimov]

* lisp/org.el (org-metaleft-final-hook, org-metaright-final-hook,
org-metaup-final-hook, org-metadown-final-hook): Define final hooks
for S-cursor commands.
(org-metaleft, org-metaright, org-metaup, org-metadown): Add final
hooks to M-commands and document them in the docstring.
---
 lisp/org.el | 34 ++++++++++++++++++++++++++++++----
 1 file changed, 30 insertions(+), 4 deletions(-)

diff --git a/lisp/org.el b/lisp/org.el
index 4063ba98f..b396456a2 100644
--- a/lisp/org.el
+++ b/lisp/org.el
@@ -16714,15 +16714,27 @@ before indentation and \t insertion takes place.")
 (defvar org-metaleft-hook nil
   "Hook for functions attaching themselves to `M-left'.
 See `org-ctrl-c-ctrl-c-hook' for more information.")
+(defvar org-metaleft-final-hook nil
+  "Hook for functions attaching themselves to `M-left'.
+See `org-ctrl-c-ctrl-c-hook' for more information.")
 (defvar org-metaright-hook nil
   "Hook for functions attaching themselves to `M-right'.
 See `org-ctrl-c-ctrl-c-hook' for more information.")
+(defvar org-metaright-final-hook nil
+  "Hook for functions attaching themselves to `M-right'.
+See `org-ctrl-c-ctrl-c-hook' for more information.")
 (defvar org-metaup-hook nil
   "Hook for functions attaching themselves to `M-up'.
 See `org-ctrl-c-ctrl-c-hook' for more information.")
+(defvar org-metaup-final-hook nil
+  "Hook for functions attaching themselves to `M-up'.
+See `org-ctrl-c-ctrl-c-hook' for more information.")
 (defvar org-metadown-hook nil
   "Hook for functions attaching themselves to `M-down'.
 See `org-ctrl-c-ctrl-c-hook' for more information.")
+(defvar org-metadown-final-hook nil
+  "Hook for functions attaching themselves to `M-down'.
+See `org-ctrl-c-ctrl-c-hook' for more information.")
 (defvar org-shiftmetaleft-hook nil
   "Hook for functions attaching themselves to `M-S-left'.
 See `org-ctrl-c-ctrl-c-hook' for more information.")
@@ -16879,7 +16891,8 @@ default `backward-word'.  See the individual commands for more
 information.
 
 This function runs the hook `org-metaleft-hook' as a first step,
-and returns at first non-nil value."
+`org-metaleft-final-hook' as the penultimate step, and returns at
+first non-nil value."
   (interactive "P")
   (cond
    ((run-hook-with-args-until-success 'org-metaleft-hook))
@@ -16902,6 +16915,7 @@ and returns at first non-nil value."
 	       (org-at-item-p))))
     (when (org-check-for-hidden 'items) (org-hidden-tree-error))
     (call-interactively 'org-outdent-item))
+   ((run-hook-with-args-until-success 'org-metaleft-final-hook))
    (t (call-interactively 'backward-word))))
 
 (defun org-metaright (&optional _arg)
@@ -16915,7 +16929,8 @@ With no specific context, calls the Emacs default `forward-word'.
 See the individual commands for more information.
 
 This function runs the hook `org-metaright-hook' as a first step,
-and returns at first non-nil value."
+`org-metaright-final-hook' as the penultimate step, and returns
+at first non-nil value."
   (interactive "P")
   (cond
    ((run-hook-with-args-until-success 'org-metaright-hook))
@@ -16940,6 +16955,7 @@ and returns at first non-nil value."
 	       (org-at-item-p))))
     (when (org-check-for-hidden 'items) (org-hidden-tree-error))
     (call-interactively 'org-indent-item))
+   ((run-hook-with-args-until-success 'org-metaright-final-hook))
    (t (call-interactively 'forward-word))))
 
 (defun org-check-for-hidden (what)
@@ -16973,7 +16989,11 @@ this function returns t, nil otherwise."
   "Move subtree up or move table row up.
 Calls `org-move-subtree-up' or `org-table-move-row' or
 `org-move-item-up', depending on context.  See the individual commands
-for more information."
+for more information.
+
+This function runs the hook `org-metaup-hook' as a first step,
+`org-metaup-final-hook' as the penultimate step, and returns at
+first non-nil value."
   (interactive "P")
   (cond
    ((run-hook-with-args-until-success 'org-metaup-hook))
@@ -17030,13 +17050,18 @@ for more information."
     (org-drag-element-backward))
    ((org-at-heading-p) (call-interactively 'org-move-subtree-up))
    ((org-at-item-p) (call-interactively 'org-move-item-up))
+   ((run-hook-with-args-until-success 'org-metaup-final-hook))
    (t (org-drag-element-backward))))
 
 (defun org-metadown (&optional _arg)
   "Move subtree down or move table row down.
 Calls `org-move-subtree-down' or `org-table-move-row' or
 `org-move-item-down', depending on context.  See the individual
-commands for more information."
+commands for more information.
+
+This function runs the hook `org-metadown-hook' as a first step,
+`org-metadown-final-hook' as the penultimate step, and returns at
+first non-nil value."
   (interactive "P")
   (cond
    ((run-hook-with-args-until-success 'org-metadown-hook))
@@ -17089,6 +17114,7 @@ commands for more information."
     (org-drag-element-forward))
    ((org-at-heading-p) (call-interactively 'org-move-subtree-down))
    ((org-at-item-p) (call-interactively 'org-move-item-down))
+   ((run-hook-with-args-until-success 'org-metadown-final-hook))
    (t (org-drag-element-forward))))
 
 (defun org-shiftup (&optional arg)
-- 
2.34.1

[PATCH 2/3] lisp/org.el: Fix docstring for S-cursor commands

[Evgenii Klimov]

* lisp/org.el (org-shiftup, org-shiftdown, org-shiftright,
org-shiftleft): Document hooks for S-cursor commands in the docstring.
---
 lisp/org.el | 24 ++++++++++++++++++++----
 1 file changed, 20 insertions(+), 4 deletions(-)

diff --git a/lisp/org.el b/lisp/org.el
index b396456a2..bf61062b1 100644
--- a/lisp/org.el
+++ b/lisp/org.el
@@ -17121,7 +17121,11 @@ first non-nil value."
   "Act on current element according to context.
 Call `org-timestamp-up' or `org-priority-up', or
 `org-previous-item', or `org-table-move-cell-up'.  See the
-individual commands for more information."
+individual commands for more information.
+
+This function runs the hook `org-shiftup-hook' as a first step,
+`org-shiftup-final-hook' as the penultimate step, and returns at
+first non-nil value."
   (interactive "P")
   (cond
    ((run-hook-with-args-until-success 'org-shiftup-hook))
@@ -17149,7 +17153,11 @@ individual commands for more information."
   "Act on current element according to context.
 Call `org-timestamp-down' or `org-priority-down', or
 `org-next-item', or `org-table-move-cell-down'.  See the
-individual commands for more information."
+individual commands for more information.
+
+This function runs the hook `org-shiftdown-hook' as a first step,
+`org-shiftdown-final-hook' as the penultimate step, and returns
+at first non-nil value."
   (interactive "P")
   (cond
    ((run-hook-with-args-until-success 'org-shiftdown-hook))
@@ -17182,7 +17190,11 @@ This does one of the following:
 - on an item, switch entire list to the next bullet type
 - on a property line, switch to the next allowed value
 - on a clocktable definition line, move time block into the future
-- in a table, move a single cell right"
+- in a table, move a single cell right
+
+This function runs the hook `org-shiftright-hook' as a first
+step, `org-shiftright-final-hook' as the penultimate step, and
+returns at first non-nil value."
   (interactive "P")
   (cond
    ((run-hook-with-args-until-success 'org-shiftright-hook))
@@ -17222,7 +17234,11 @@ This does one of the following:
 - on an item, switch entire list to the previous bullet type
 - on a property line, switch to the previous allowed value
 - on a clocktable definition line, move time block into the past
-- in a table, move a single cell left"
+- in a table, move a single cell left
+
+This function runs the hook `org-shiftleft-hook' as a first step,
+`org-shiftleft-final-hook' as the penultimate step, and returns
+at first non-nil value."
   (interactive "P")
   (cond
    ((run-hook-with-args-until-success 'org-shiftleft-hook))
-- 
2.34.1

[PATCH 3/3] lisp/org.el: Add final hooks to the S-M-cursor commands

[Evgenii Klimov]

* lisp/org.el (org-shiftmetaleft-final-hook,
org-shiftmetaright-final-hook, org-shiftmetaup-final-hook,
org-shiftmetadown-final-hook): Define final hooks for the S-M-cursor
commands.
(org-shiftmetaleft, org-shiftmetaright, org-shiftmetaup,
org-shiftmetadown): Add final hooks to the S-M-cursor commands and
document hooks in the docstring.
---
 lisp/org.el | 40 ++++++++++++++++++++++++++++++++++++----
 1 file changed, 36 insertions(+), 4 deletions(-)

diff --git a/lisp/org.el b/lisp/org.el
index bf61062b1..326d3eed9 100644
--- a/lisp/org.el
+++ b/lisp/org.el
@@ -16738,15 +16738,27 @@ See `org-ctrl-c-ctrl-c-hook' for more information.")
 (defvar org-shiftmetaleft-hook nil
   "Hook for functions attaching themselves to `M-S-left'.
 See `org-ctrl-c-ctrl-c-hook' for more information.")
+(defvar org-shiftmetaleft-final-hook nil
+  "Hook for functions attaching themselves to `M-S-left'.
+See `org-ctrl-c-ctrl-c-hook' for more information.")
 (defvar org-shiftmetaright-hook nil
   "Hook for functions attaching themselves to `M-S-right'.
 See `org-ctrl-c-ctrl-c-hook' for more information.")
+(defvar org-shiftmetaright-final-hook nil
+  "Hook for functions attaching themselves to `M-S-right'.
+See `org-ctrl-c-ctrl-c-hook' for more information.")
 (defvar org-shiftmetaup-hook nil
   "Hook for functions attaching themselves to `M-S-up'.
 See `org-ctrl-c-ctrl-c-hook' for more information.")
+(defvar org-shiftmetaup-final-hook nil
+  "Hook for functions attaching themselves to `M-S-up'.
+See `org-ctrl-c-ctrl-c-hook' for more information.")
 (defvar org-shiftmetadown-hook nil
   "Hook for functions attaching themselves to `M-S-down'.
 See `org-ctrl-c-ctrl-c-hook' for more information.")
+(defvar org-shiftmetadown-final-hook nil
+  "Hook for functions attaching themselves to `M-S-down'.
+See `org-ctrl-c-ctrl-c-hook' for more information.")
 (defvar org-metareturn-hook nil
   "Hook for functions attaching themselves to `M-RET'.
 See `org-ctrl-c-ctrl-c-hook' for more information.")
@@ -16814,7 +16826,11 @@ When ARG is a numeric prefix, show contents of this level."
   "Promote subtree or delete table column.
 Calls `org-promote-subtree', `org-outdent-item-tree', or
 `org-table-delete-column', depending on context.  See the
-individual commands for more information."
+individual commands for more information.
+
+This function runs the hook `org-shiftmetaleft-hook' as a first
+step, `org-shiftmetaleft-final-hook' as the penultimate step, and
+returns at first non-nil value."
   (interactive)
   (cond
    ((and (eq system-type 'darwin)
@@ -16828,13 +16844,18 @@ individual commands for more information."
       (save-excursion (goto-char (region-beginning))
 		      (org-at-item-p)))
     (call-interactively 'org-outdent-item-tree))
+   ((run-hook-with-args-until-success 'org-shiftmetaleft-final-hook))
    (t (org-modifier-cursor-error))))
 
 (defun org-shiftmetaright ()
   "Demote subtree or insert table column.
 Calls `org-demote-subtree', `org-indent-item-tree', or
 `org-table-insert-column', depending on context.  See the
-individual commands for more information."
+individual commands for more information.
+
+This function runs the hook `org-shiftmetaright-hook' as a first
+step, `org-shiftmetaright-final-hook' as the penultimate step,
+and returns at first non-nil value."
   (interactive)
   (cond
    ((and (eq system-type 'darwin)
@@ -16848,6 +16869,7 @@ individual commands for more information."
       (save-excursion (goto-char (region-beginning))
 		      (org-at-item-p)))
     (call-interactively 'org-indent-item-tree))
+   ((run-hook-with-args-until-success 'org-shiftmetaright-final-hook))
    (t (org-modifier-cursor-error))))
 
 (defun org-shiftmetaup (&optional _arg)
@@ -16855,13 +16877,18 @@ individual commands for more information."
 In a table, kill the current row.
 On a clock timestamp, update the value of the timestamp like `S-<up>'
 but also adjust the previous clocked item in the clock history.
-Everywhere else, drag the line at point up."
+Everywhere else, drag the line at point up.
+
+This function runs the hook `org-shiftmetaup-hook' as a first
+step, `org-shiftmetaup-final-hook' as the penultimate step, and
+returns at first non-nil value."
   (interactive "P")
   (cond
    ((run-hook-with-args-until-success 'org-shiftmetaup-hook))
    ((org-at-table-p) (call-interactively 'org-table-kill-row))
    ((org-at-clock-log-p) (let ((org-clock-adjust-closest t))
 			   (call-interactively 'org-timestamp-up)))
+   ((run-hook-with-args-until-success 'org-shiftmetaup-final-hook))
    (t (call-interactively 'org-drag-line-backward))))
 
 (defun org-shiftmetadown (&optional _arg)
@@ -16869,13 +16896,18 @@ Everywhere else, drag the line at point up."
 In a table, insert an empty row at the current line.
 On a clock timestamp, update the value of the timestamp like `S-<down>'
 but also adjust the previous clocked item in the clock history.
-Everywhere else, drag the line at point down."
+Everywhere else, drag the line at point down.
+
+This function runs the hook `org-shiftmetadown-hook' as a first
+step, `org-shiftmetadown-final-hook' as the penultimate step, and
+returns at first non-nil value."
   (interactive "P")
   (cond
    ((run-hook-with-args-until-success 'org-shiftmetadown-hook))
    ((org-at-table-p) (call-interactively 'org-table-insert-row))
    ((org-at-clock-log-p) (let ((org-clock-adjust-closest t))
 			   (call-interactively 'org-timestamp-down)))
+   ((run-hook-with-args-until-success 'org-shiftmetadown-final-hook))
    (t (call-interactively 'org-drag-line-forward))))
 
 (defsubst org-hidden-tree-error ()
-- 
2.34.1

Re: Add final hooks to S-/M-/S-M-cursor commands

[Ihor Radchenko]

Evgenii Klimov <eugene.dev@lipklim.org> writes:

> `org-shiftup' and other S-cursor commands not only provide initial
> hooks but also final hooks, while M-cursor and S-M-cursor commands
> lack them. These patches add final hooks to all of these commands and
> document both hooks in the docstring if they are not already present.

Thanks for the patch!
May you please squash it into one, add TINYCHANGE cookie (unless you
have FSF copyright assignment; see
https://orgmode.org/worg/org-contribute.html#first-patch), and document
your changes in /etc/ORG-NEWS file?

-- 
Ihor Radchenko // yantar92,
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: Add final hooks to S-/M-/S-M-cursor commands

[Evgenii Klimov]

On July 1, 2023 11:40:07 AM GMT+01:00, Ihor Radchenko <yantar92@posteo.net> wrote:
>Thanks for the patch!
>May you please squash it into one
>

Don't you mind if I also add the final hook to `org-meta-return'? I
didn't do it right away because it requires a little bit of refactoring:
everything after the initial hook is currently run with
`call-interactively'.

Re: Add final hooks to S-/M-/S-M-cursor commands

[Ihor Radchenko]

Evgenii Klimov <eugene.dev@lipklim.org> writes:

> On July 1, 2023 11:40:07 AM GMT+01:00, Ihor Radchenko <yantar92@posteo.net> wrote:
>>Thanks for the patch!
>>May you please squash it into one
>>
>
> Don't you mind if I also add the final hook to `org-meta-return'? I
> didn't do it right away because it requires a little bit of refactoring:
> everything after the initial hook is currently run with
> `call-interactively'.

Should be fine, I think. Although I am not 100% sure if it is going to
be useful in practice.

-- 
Ihor Radchenko // yantar92,
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>

[PATCH v2] lisp/org.el: Add final hooks to S-/M-/S-M-cursor commands

[Evgenii Klimov]

* lisp/org.el (org-metaleft-final-hook, org-metaright-final-hook,
org-metaup-final-hook, org-metadown-final-hook): Define final hooks
for S-cursor commands.
(org-metaleft, org-metaright, org-metaup, org-metadown): Add final
hooks to M-commands and document them in the docstring.

* lisp/org.el (org-shiftup, org-shiftdown, org-shiftright,
org-shiftleft): Document hooks for S-cursor commands in the docstring.

* lisp/org.el (org-shiftmetaleft-final-hook,
org-shiftmetaright-final-hook, org-shiftmetaup-final-hook,
org-shiftmetadown-final-hook): Define final hooks for the S-M-cursor
commands.
(org-shiftmetaleft, org-shiftmetaright, org-shiftmetaup,
org-shiftmetadown): Add final hooks to the S-M-cursor commands and
document hooks in the docstring.

TINYCHANGE
---
Probably you are right and there's no need to add the final hook to
`org-meta-return'. Previously, I thought that the last condition fully
simulate C-RET, but the latter turned out to be
`org-insert-heading-respect-content'.

 etc/ORG-NEWS | 17 +++++++++
 lisp/org.el  | 98 +++++++++++++++++++++++++++++++++++++++++++++-------
 2 files changed, 103 insertions(+), 12 deletions(-)

diff --git a/etc/ORG-NEWS b/etc/ORG-NEWS
index cb4bc632b..f88e3df3d 100644
--- a/etc/ORG-NEWS
+++ b/etc/ORG-NEWS
@@ -249,6 +249,23 @@ Currently implemented options are:
   iCalendar programs support this usage.
 
 ** New features
+*** New final hooks for Modifier-Cursor keys
+
+Final hooks are added to the following commands:
+- ~org-metaleft-final-hook~ to ~org-metaleft~ (bound to =M-<left>=).
+- ~org-metaright-final-hook~ to ~org-metaright~ (bound to
+  =M-<right>=).
+- ~org-metaup-final-hook~ to ~org-metaup~ (bound to =M-<up>=).
+- ~org-metadown-final-hook~ to ~org-metadown~ (bound to =M-<down>=).
+- ~org-shiftmetaleft-final-hook~ to ~org-shiftmetaleft~ (bound to
+  =M-S-<left>=).
+- ~org-shiftmetaright-final-hook~ to ~org-shiftmetaright~ (bound to
+  =M-S-<right>=).
+- ~org-shiftmetaup-final-hook~ to ~org-shiftmetaup~ (bound to
+  =M-S-<up>=).
+- ~org-shiftmetadown-final-hook~ to ~org-shiftmetadown~ (bound to
+  =M-S-<down>=).
+
 *** ~org-insert-todo-heading-respect-content~ now accepts prefix arguments
 
 The prefix arguments are passed to ~org-insert-todo-heading~.
diff --git a/lisp/org.el b/lisp/org.el
index fdb920864..052c592ed 100644
--- a/lisp/org.el
+++ b/lisp/org.el
@@ -16831,27 +16831,51 @@ before indentation and \t insertion takes place.")
 (defvar org-metaleft-hook nil
   "Hook for functions attaching themselves to `M-left'.
 See `org-ctrl-c-ctrl-c-hook' for more information.")
+(defvar org-metaleft-final-hook nil
+  "Hook for functions attaching themselves to `M-left'.
+See `org-ctrl-c-ctrl-c-hook' for more information.")
 (defvar org-metaright-hook nil
   "Hook for functions attaching themselves to `M-right'.
 See `org-ctrl-c-ctrl-c-hook' for more information.")
+(defvar org-metaright-final-hook nil
+  "Hook for functions attaching themselves to `M-right'.
+See `org-ctrl-c-ctrl-c-hook' for more information.")
 (defvar org-metaup-hook nil
   "Hook for functions attaching themselves to `M-up'.
 See `org-ctrl-c-ctrl-c-hook' for more information.")
+(defvar org-metaup-final-hook nil
+  "Hook for functions attaching themselves to `M-up'.
+See `org-ctrl-c-ctrl-c-hook' for more information.")
 (defvar org-metadown-hook nil
   "Hook for functions attaching themselves to `M-down'.
 See `org-ctrl-c-ctrl-c-hook' for more information.")
+(defvar org-metadown-final-hook nil
+  "Hook for functions attaching themselves to `M-down'.
+See `org-ctrl-c-ctrl-c-hook' for more information.")
 (defvar org-shiftmetaleft-hook nil
   "Hook for functions attaching themselves to `M-S-left'.
 See `org-ctrl-c-ctrl-c-hook' for more information.")
+(defvar org-shiftmetaleft-final-hook nil
+  "Hook for functions attaching themselves to `M-S-left'.
+See `org-ctrl-c-ctrl-c-hook' for more information.")
 (defvar org-shiftmetaright-hook nil
   "Hook for functions attaching themselves to `M-S-right'.
 See `org-ctrl-c-ctrl-c-hook' for more information.")
+(defvar org-shiftmetaright-final-hook nil
+  "Hook for functions attaching themselves to `M-S-right'.
+See `org-ctrl-c-ctrl-c-hook' for more information.")
 (defvar org-shiftmetaup-hook nil
   "Hook for functions attaching themselves to `M-S-up'.
 See `org-ctrl-c-ctrl-c-hook' for more information.")
+(defvar org-shiftmetaup-final-hook nil
+  "Hook for functions attaching themselves to `M-S-up'.
+See `org-ctrl-c-ctrl-c-hook' for more information.")
 (defvar org-shiftmetadown-hook nil
   "Hook for functions attaching themselves to `M-S-down'.
 See `org-ctrl-c-ctrl-c-hook' for more information.")
+(defvar org-shiftmetadown-final-hook nil
+  "Hook for functions attaching themselves to `M-S-down'.
+See `org-ctrl-c-ctrl-c-hook' for more information.")
 (defvar org-metareturn-hook nil
   "Hook for functions attaching themselves to `M-RET'.
 See `org-ctrl-c-ctrl-c-hook' for more information.")
@@ -16919,7 +16943,11 @@ When ARG is a numeric prefix, show contents of this level."
   "Promote subtree or delete table column.
 Calls `org-promote-subtree', `org-outdent-item-tree', or
 `org-table-delete-column', depending on context.  See the
-individual commands for more information."
+individual commands for more information.
+
+This function runs the hook `org-shiftmetaleft-hook' as a first
+step, `org-shiftmetaleft-final-hook' as the penultimate step, and
+returns at first non-nil value."
   (interactive)
   (cond
    ((and (eq system-type 'darwin)
@@ -16933,13 +16961,18 @@ individual commands for more information."
       (save-excursion (goto-char (region-beginning))
 		      (org-at-item-p)))
     (call-interactively 'org-outdent-item-tree))
+   ((run-hook-with-args-until-success 'org-shiftmetaleft-final-hook))
    (t (org-modifier-cursor-error))))
 
 (defun org-shiftmetaright ()
   "Demote subtree or insert table column.
 Calls `org-demote-subtree', `org-indent-item-tree', or
 `org-table-insert-column', depending on context.  See the
-individual commands for more information."
+individual commands for more information.
+
+This function runs the hook `org-shiftmetaright-hook' as a first
+step, `org-shiftmetaright-final-hook' as the penultimate step,
+and returns at first non-nil value."
   (interactive)
   (cond
    ((and (eq system-type 'darwin)
@@ -16953,6 +16986,7 @@ individual commands for more information."
       (save-excursion (goto-char (region-beginning))
 		      (org-at-item-p)))
     (call-interactively 'org-indent-item-tree))
+   ((run-hook-with-args-until-success 'org-shiftmetaright-final-hook))
    (t (org-modifier-cursor-error))))
 
 (defun org-shiftmetaup (&optional _arg)
@@ -16960,13 +16994,18 @@ individual commands for more information."
 In a table, kill the current row.
 On a clock timestamp, update the value of the timestamp like `S-<up>'
 but also adjust the previous clocked item in the clock history.
-Everywhere else, drag the line at point up."
+Everywhere else, drag the line at point up.
+
+This function runs the hook `org-shiftmetaup-hook' as a first
+step, `org-shiftmetaup-final-hook' as the penultimate step, and
+returns at first non-nil value."
   (interactive "P")
   (cond
    ((run-hook-with-args-until-success 'org-shiftmetaup-hook))
    ((org-at-table-p) (call-interactively 'org-table-kill-row))
    ((org-at-clock-log-p) (let ((org-clock-adjust-closest t))
 			   (call-interactively 'org-timestamp-up)))
+   ((run-hook-with-args-until-success 'org-shiftmetaup-final-hook))
    (t (call-interactively 'org-drag-line-backward))))
 
 (defun org-shiftmetadown (&optional _arg)
@@ -16974,13 +17013,18 @@ Everywhere else, drag the line at point up."
 In a table, insert an empty row at the current line.
 On a clock timestamp, update the value of the timestamp like `S-<down>'
 but also adjust the previous clocked item in the clock history.
-Everywhere else, drag the line at point down."
+Everywhere else, drag the line at point down.
+
+This function runs the hook `org-shiftmetadown-hook' as a first
+step, `org-shiftmetadown-final-hook' as the penultimate step, and
+returns at first non-nil value."
   (interactive "P")
   (cond
    ((run-hook-with-args-until-success 'org-shiftmetadown-hook))
    ((org-at-table-p) (call-interactively 'org-table-insert-row))
    ((org-at-clock-log-p) (let ((org-clock-adjust-closest t))
 			   (call-interactively 'org-timestamp-down)))
+   ((run-hook-with-args-until-success 'org-shiftmetadown-final-hook))
    (t (call-interactively 'org-drag-line-forward))))
 
 (defsubst org-hidden-tree-error ()
@@ -16996,7 +17040,8 @@ default `backward-word'.  See the individual commands for more
 information.
 
 This function runs the hook `org-metaleft-hook' as a first step,
-and returns at first non-nil value."
+`org-metaleft-final-hook' as the penultimate step, and returns at
+first non-nil value."
   (interactive "P")
   (cond
    ((run-hook-with-args-until-success 'org-metaleft-hook))
@@ -17019,6 +17064,7 @@ and returns at first non-nil value."
 	       (org-at-item-p))))
     (when (org-check-for-hidden 'items) (org-hidden-tree-error))
     (call-interactively 'org-outdent-item))
+   ((run-hook-with-args-until-success 'org-metaleft-final-hook))
    (t (call-interactively 'backward-word))))
 
 (defun org-metaright (&optional _arg)
@@ -17032,7 +17078,8 @@ With no specific context, calls the Emacs default `forward-word'.
 See the individual commands for more information.
 
 This function runs the hook `org-metaright-hook' as a first step,
-and returns at first non-nil value."
+`org-metaright-final-hook' as the penultimate step, and returns
+at first non-nil value."
   (interactive "P")
   (cond
    ((run-hook-with-args-until-success 'org-metaright-hook))
@@ -17057,6 +17104,7 @@ and returns at first non-nil value."
 	       (org-at-item-p))))
     (when (org-check-for-hidden 'items) (org-hidden-tree-error))
     (call-interactively 'org-indent-item))
+   ((run-hook-with-args-until-success 'org-metaright-final-hook))
    (t (call-interactively 'forward-word))))
 
 (defun org-check-for-hidden (what)
@@ -17090,7 +17138,11 @@ this function returns t, nil otherwise."
   "Move subtree up or move table row up.
 Calls `org-move-subtree-up' or `org-table-move-row' or
 `org-move-item-up', depending on context.  See the individual commands
-for more information."
+for more information.
+
+This function runs the hook `org-metaup-hook' as a first step,
+`org-metaup-final-hook' as the penultimate step, and returns at
+first non-nil value."
   (interactive "P")
   (cond
    ((run-hook-with-args-until-success 'org-metaup-hook))
@@ -17147,13 +17199,18 @@ for more information."
     (org-drag-element-backward))
    ((org-at-heading-p) (call-interactively 'org-move-subtree-up))
    ((org-at-item-p) (call-interactively 'org-move-item-up))
+   ((run-hook-with-args-until-success 'org-metaup-final-hook))
    (t (org-drag-element-backward))))
 
 (defun org-metadown (&optional _arg)
   "Move subtree down or move table row down.
 Calls `org-move-subtree-down' or `org-table-move-row' or
 `org-move-item-down', depending on context.  See the individual
-commands for more information."
+commands for more information.
+
+This function runs the hook `org-metadown-hook' as a first step,
+`org-metadown-final-hook' as the penultimate step, and returns at
+first non-nil value."
   (interactive "P")
   (cond
    ((run-hook-with-args-until-success 'org-metadown-hook))
@@ -17206,13 +17263,18 @@ commands for more information."
     (org-drag-element-forward))
    ((org-at-heading-p) (call-interactively 'org-move-subtree-down))
    ((org-at-item-p) (call-interactively 'org-move-item-down))
+   ((run-hook-with-args-until-success 'org-metadown-final-hook))
    (t (org-drag-element-forward))))
 
 (defun org-shiftup (&optional arg)
   "Act on current element according to context.
 Call `org-timestamp-up' or `org-priority-up', or
 `org-previous-item', or `org-table-move-cell-up'.  See the
-individual commands for more information."
+individual commands for more information.
+
+This function runs the hook `org-shiftup-hook' as a first step,
+`org-shiftup-final-hook' as the penultimate step, and returns at
+first non-nil value."
   (interactive "P")
   (cond
    ((run-hook-with-args-until-success 'org-shiftup-hook))
@@ -17240,7 +17302,11 @@ individual commands for more information."
   "Act on current element according to context.
 Call `org-timestamp-down' or `org-priority-down', or
 `org-next-item', or `org-table-move-cell-down'.  See the
-individual commands for more information."
+individual commands for more information.
+
+This function runs the hook `org-shiftdown-hook' as a first step,
+`org-shiftdown-final-hook' as the penultimate step, and returns
+at first non-nil value."
   (interactive "P")
   (cond
    ((run-hook-with-args-until-success 'org-shiftdown-hook))
@@ -17273,7 +17339,11 @@ This does one of the following:
 - on an item, switch entire list to the next bullet type
 - on a property line, switch to the next allowed value
 - on a clocktable definition line, move time block into the future
-- in a table, move a single cell right"
+- in a table, move a single cell right
+
+This function runs the hook `org-shiftright-hook' as a first
+step, `org-shiftright-final-hook' as the penultimate step, and
+returns at first non-nil value."
   (interactive "P")
   (cond
    ((run-hook-with-args-until-success 'org-shiftright-hook))
@@ -17313,7 +17383,11 @@ This does one of the following:
 - on an item, switch entire list to the previous bullet type
 - on a property line, switch to the previous allowed value
 - on a clocktable definition line, move time block into the past
-- in a table, move a single cell left"
+- in a table, move a single cell left
+
+This function runs the hook `org-shiftleft-hook' as a first step,
+`org-shiftleft-final-hook' as the penultimate step, and returns
+at first non-nil value."
   (interactive "P")
   (cond
    ((run-hook-with-args-until-success 'org-shiftleft-hook))
-- 
2.34.1

Re: [PATCH v2] lisp/org.el: Add final hooks to S-/M-/S-M-cursor commands

[Ihor Radchenko]

Evgenii Klimov <eugene.dev@lipklim.org> writes:

> ...

Thanks for the update.

Few comments.

First, please add Changelog entry for etc/ORG-NEWS.

> +(defvar org-metaleft-final-hook nil
> +  "Hook for functions attaching themselves to `M-left'.
> +See `org-ctrl-c-ctrl-c-hook' for more information.")

Note that unlike the docstring your added, `org-shiftup-final-hook'
specifies when the hook is executed:

(defvar org-shiftup-final-hook nil
  "Hook for functions attaching themselves to `S-up'.
This one runs after all other options except shift-select have been excluded.
See `org-ctrl-c-ctrl-c-hook' for more information.")

It is better to follow the pattern and clarify the purpose of the hook
better instead of leaving docstrings for both the -final and other hook
same.

> +individual commands for more information.
> +
> +This function runs the hook `org-shiftmetaleft-hook' as a first
> +step, `org-shiftmetaleft-final-hook' as the penultimate step, and
> +returns at first non-nil value."

Upon looking closer, I realized that you also defined return value of
the function here.  Is there any particular reason for this? The return
value is currently not defined and supposed to be discarded.

-- 
Ihor Radchenko // yantar92,
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: [PATCH v2] lisp/org.el: Add final hooks to S-/M-/S-M-cursor commands

[Evgenii Klimov]

Ihor Radchenko <yantar92@posteo.net> writes:

[...]
>> +individual commands for more information.
>> +
>> +This function runs the hook `org-shiftmetaleft-hook' as a first
>> +step, `org-shiftmetaleft-final-hook' as the penultimate step, and
>> +returns at first non-nil value."
>
> Upon looking closer, I realized that you also defined return value of
> the function here.  Is there any particular reason for this? The return
> value is currently not defined and supposed to be discarded.

Maybe I got it wrong, but I tried to follow the docstring for
`org-metaleft'. And I don't see here the use of the return value either:

#+begin_example
  (defun org-metaleft (&optional _arg)
    "...
    This function runs the hook `org-metaleft-hook' as a first step,
    and returns at first non-nil value."
    ...)
#+end_example

Should I keep it like this?
  This function runs the hook `org-shiftmetaleft-hook' as a first
  step, and `org-shiftmetaleft-final-hook' as the penultimate step.

Re: [PATCH v2] lisp/org.el: Add final hooks to S-/M-/S-M-cursor commands

[Ihor Radchenko]

Evgenii Klimov <eugene.dev@lipklim.org> writes:

> Maybe I got it wrong, but I tried to follow the docstring for
> `org-metaleft'. And I don't see here the use of the return value either:
>
> #+begin_example
>   (defun org-metaleft (&optional _arg)
>     "...
>     This function runs the hook `org-metaleft-hook' as a first step,
>     and returns at first non-nil value."
>     ...)
> #+end_example

> Should I keep it like this?
>   This function runs the hook `org-shiftmetaleft-hook' as a first
>   step, and `org-shiftmetaleft-final-hook' as the penultimate step.

Apparently the original wording is quite confusing.
What it is supposed to say is:

    This function runs the functions in `org-metaleft-hook' one by one
    as a first step, and exits immediately if a function from the hook
    returns non-nil.

-- 
Ihor Radchenko // yantar92,
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>

[PATCH v3] lisp/org.el: Add final hooks to S-/M-/S-M-cursor commands

[Evgenii Klimov]

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


Ihor Radchenko <yantar92@posteo.net> writes:

> Evgenii Klimov <eugene.dev@lipklim.org> writes:
[...]
> Few comments.
>
> First, please add Changelog entry for etc/ORG-NEWS.

Done.

>> +(defvar org-metaleft-final-hook nil
>> +  "Hook for functions attaching themselves to `M-left'.
>> +See `org-ctrl-c-ctrl-c-hook' for more information.")
>
> Note that unlike the docstring your added, `org-shiftup-final-hook'
> specifies when the hook is executed:
>
> (defvar org-shiftup-final-hook nil
>   "Hook for functions attaching themselves to `S-up'.
> This one runs after all other options except shift-select have been excluded.
> See `org-ctrl-c-ctrl-c-hook' for more information.")
>
> It is better to follow the pattern and clarify the purpose of the hook
> better instead of leaving docstrings for both the -final and other hook
> same.

Done.

>> +individual commands for more information.
>> +
>> +This function runs the hook `org-shiftmetaleft-hook' as a first
>> +step, `org-shiftmetaleft-final-hook' as the penultimate step, and
>> +returns at first non-nil value."
>
> Upon looking closer, I realized that you also defined return value of
> the function here.  Is there any particular reason for this? The return
> value is currently not defined and supposed to be discarded.

> Apparently the original wording is quite confusing.
> What it is supposed to say is:
> 
>     This function runs the functions in `org-metaleft-hook' one by one
>     as a first step, and exits immediately if a function from the hook
>     returns non-nil.

Reworded as we discussed. Also for commands that support
`shift-select-mode' (i.e. org-shift{up,down,right,left}) mentioned it
and `org-support-shift-select'.


[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #2: v3-0001-lisp-org.el-Add-final-hooks-to-S-M-S-M-cursor-com.patch --]
[-- Type: text/x-diff, Size: 17248 bytes --]

From b27b95efbad7645d7bd4870becd112abc25c9840 Mon Sep 17 00:00:00 2001
From: Evgenii Klimov <eugene.dev@lipklim.org>
Date: Thu, 29 Jun 2023 20:06:33 +0100
Subject: [PATCH v3] lisp/org.el: Add final hooks to S-/M-/S-M-cursor commands

* lisp/org.el (org-metaleft-final-hook, org-metaright-final-hook,
org-metaup-final-hook, org-metadown-final-hook): Define final hooks
for S-cursor commands.
(org-metaleft, org-metaright, org-metaup, org-metadown): Add final
hooks to M-commands and document them in the docstring.

* lisp/org.el (org-shiftup, org-shiftdown, org-shiftright,
org-shiftleft): Document hooks for S-cursor commands in the docstring.

* lisp/org.el (org-shiftmetaleft-final-hook,
org-shiftmetaright-final-hook, org-shiftmetaup-final-hook,
org-shiftmetadown-final-hook): Define final hooks for the S-M-cursor
commands.
(org-shiftmetaleft, org-shiftmetaright, org-shiftmetaup,
org-shiftmetadown): Add final hooks to the S-M-cursor commands and
document hooks in the docstring.

* etc/ORG-NEWS (New final hooks for Modifier-Cursor keys): Document
new hooks.

TINYCHANGE
---
 etc/ORG-NEWS |  17 ++++++
 lisp/org.el  | 155 +++++++++++++++++++++++++++++++++++++++++++++------
 2 files changed, 156 insertions(+), 16 deletions(-)

diff --git a/etc/ORG-NEWS b/etc/ORG-NEWS
index d04e92275..973a97a2f 100644
--- a/etc/ORG-NEWS
+++ b/etc/ORG-NEWS
@@ -437,6 +437,23 @@ Currently implemented options are:
   iCalendar programs support this usage.
 
 ** New features
+*** New final hooks for Modifier-Cursor keys
+
+Final hooks are added to the following commands:
+- ~org-metaleft-final-hook~ to ~org-metaleft~ (bound to =M-<left>=).
+- ~org-metaright-final-hook~ to ~org-metaright~ (bound to
+  =M-<right>=).
+- ~org-metaup-final-hook~ to ~org-metaup~ (bound to =M-<up>=).
+- ~org-metadown-final-hook~ to ~org-metadown~ (bound to =M-<down>=).
+- ~org-shiftmetaleft-final-hook~ to ~org-shiftmetaleft~ (bound to
+  =M-S-<left>=).
+- ~org-shiftmetaright-final-hook~ to ~org-shiftmetaright~ (bound to
+  =M-S-<right>=).
+- ~org-shiftmetaup-final-hook~ to ~org-shiftmetaup~ (bound to
+  =M-S-<up>=).
+- ~org-shiftmetadown-final-hook~ to ~org-shiftmetadown~ (bound to
+  =M-S-<down>=).
+
 *** ~org-insert-todo-heading-respect-content~ now accepts prefix arguments
 
 The prefix arguments are passed to ~org-insert-todo-heading~.
diff --git a/lisp/org.el b/lisp/org.el
index 36235322d..57d8082e5 100644
--- a/lisp/org.el
+++ b/lisp/org.el
@@ -16658,27 +16658,63 @@ before indentation and \t insertion takes place.")
 (defvar org-metaleft-hook nil
   "Hook for functions attaching themselves to `M-left'.
 See `org-ctrl-c-ctrl-c-hook' for more information.")
+(defvar org-metaleft-final-hook nil
+  "Hook for functions attaching themselves to `M-left'.
+This one runs after all options have been excluded.
+See `org-ctrl-c-ctrl-c-hook' for more information.")
 (defvar org-metaright-hook nil
   "Hook for functions attaching themselves to `M-right'.
 See `org-ctrl-c-ctrl-c-hook' for more information.")
+(defvar org-metaright-final-hook nil
+  "Hook for functions attaching themselves to `M-right'.
+This one runs after all options have been excluded.
+See `org-ctrl-c-ctrl-c-hook' for more information.")
 (defvar org-metaup-hook nil
   "Hook for functions attaching themselves to `M-up'.
 See `org-ctrl-c-ctrl-c-hook' for more information.")
+(defvar org-metaup-final-hook nil
+  "Hook for functions attaching themselves to `M-up'.
+This one runs after all other options except
+`org-drag-element-backward' have been excluded.  See
+`org-ctrl-c-ctrl-c-hook' for more information.")
 (defvar org-metadown-hook nil
   "Hook for functions attaching themselves to `M-down'.
 See `org-ctrl-c-ctrl-c-hook' for more information.")
+(defvar org-metadown-final-hook nil
+  "Hook for functions attaching themselves to `M-down'.
+This one runs after all other options except
+`org-drag-element-forward' have been excluded.  See
+`org-ctrl-c-ctrl-c-hook' for more information.")
 (defvar org-shiftmetaleft-hook nil
   "Hook for functions attaching themselves to `M-S-left'.
 See `org-ctrl-c-ctrl-c-hook' for more information.")
+(defvar org-shiftmetaleft-final-hook nil
+  "Hook for functions attaching themselves to `M-S-left'.
+This one runs after all other options have been excluded.  See
+`org-ctrl-c-ctrl-c-hook' for more information.")
 (defvar org-shiftmetaright-hook nil
   "Hook for functions attaching themselves to `M-S-right'.
 See `org-ctrl-c-ctrl-c-hook' for more information.")
+(defvar org-shiftmetaright-final-hook nil
+  "Hook for functions attaching themselves to `M-S-right'.
+This one runs after all other options have been excluded.  See
+`org-ctrl-c-ctrl-c-hook' for more information.")
 (defvar org-shiftmetaup-hook nil
   "Hook for functions attaching themselves to `M-S-up'.
 See `org-ctrl-c-ctrl-c-hook' for more information.")
+(defvar org-shiftmetaup-final-hook nil
+  "Hook for functions attaching themselves to `M-S-up'.
+This one runs after all other options except
+`org-drag-line-backward' have been excluded.  See
+`org-ctrl-c-ctrl-c-hook' for more information.")
 (defvar org-shiftmetadown-hook nil
   "Hook for functions attaching themselves to `M-S-down'.
 See `org-ctrl-c-ctrl-c-hook' for more information.")
+(defvar org-shiftmetadown-final-hook nil
+  "Hook for functions attaching themselves to `M-S-down'.
+This one runs after all other options except
+`org-drag-line-forward' have been excluded.  See
+`org-ctrl-c-ctrl-c-hook' for more information.")
 (defvar org-metareturn-hook nil
   "Hook for functions attaching themselves to `M-RET'.
 See `org-ctrl-c-ctrl-c-hook' for more information.")
@@ -16746,7 +16782,13 @@ When ARG is a numeric prefix, show contents of this level."
   "Promote subtree or delete table column.
 Calls `org-promote-subtree', `org-outdent-item-tree', or
 `org-table-delete-column', depending on context.  See the
-individual commands for more information."
+individual commands for more information.
+
+This function runs the functions in `org-shiftmetaleft-hook' one
+by one as a first step, and exits immediately if a function from
+the hook returns non-nil.  In the absence of a specific context,
+the function also runs `org-shiftmetaleft-final-hook' using the
+same logic."
   (interactive)
   (cond
    ((and (eq system-type 'darwin)
@@ -16760,13 +16802,20 @@ individual commands for more information."
       (save-excursion (goto-char (region-beginning))
 		      (org-at-item-p)))
     (call-interactively 'org-outdent-item-tree))
+   ((run-hook-with-args-until-success 'org-shiftmetaleft-final-hook))
    (t (org-modifier-cursor-error))))
 
 (defun org-shiftmetaright ()
   "Demote subtree or insert table column.
 Calls `org-demote-subtree', `org-indent-item-tree', or
 `org-table-insert-column', depending on context.  See the
-individual commands for more information."
+individual commands for more information.
+
+This function runs the functions in `org-shiftmetaright-hook' one
+by one as a first step, and exits immediately if a function from
+the hook returns non-nil.  In the absence of a specific context,
+the function also runs `org-shiftmetaright-final-hook' using the
+same logic."
   (interactive)
   (cond
    ((and (eq system-type 'darwin)
@@ -16780,6 +16829,7 @@ individual commands for more information."
       (save-excursion (goto-char (region-beginning))
 		      (org-at-item-p)))
     (call-interactively 'org-indent-item-tree))
+   ((run-hook-with-args-until-success 'org-shiftmetaright-final-hook))
    (t (org-modifier-cursor-error))))
 
 (defun org-shiftmetaup (&optional _arg)
@@ -16787,13 +16837,20 @@ individual commands for more information."
 In a table, kill the current row.
 On a clock timestamp, update the value of the timestamp like `S-<up>'
 but also adjust the previous clocked item in the clock history.
-Everywhere else, drag the line at point up."
+Everywhere else, drag the line at point up.
+
+This function runs the functions in `org-shiftmetaup-hook' one by
+one as a first step, and exits immediately if a function from the
+hook returns non-nil.  In the absence of a specific context, the
+function also runs `org-shiftmetaup-final-hook' using the same
+logic."
   (interactive "P")
   (cond
    ((run-hook-with-args-until-success 'org-shiftmetaup-hook))
    ((org-at-table-p) (call-interactively 'org-table-kill-row))
    ((org-at-clock-log-p) (let ((org-clock-adjust-closest t))
 			   (call-interactively 'org-timestamp-up)))
+   ((run-hook-with-args-until-success 'org-shiftmetaup-final-hook))
    (t (call-interactively 'org-drag-line-backward))))
 
 (defun org-shiftmetadown (&optional _arg)
@@ -16801,13 +16858,20 @@ Everywhere else, drag the line at point up."
 In a table, insert an empty row at the current line.
 On a clock timestamp, update the value of the timestamp like `S-<down>'
 but also adjust the previous clocked item in the clock history.
-Everywhere else, drag the line at point down."
+Everywhere else, drag the line at point down.
+
+This function runs the functions in `org-shiftmetadown-hook' one
+by one as a first step, and exits immediately if a function from
+the hook returns non-nil.  In the absence of a specific context,
+the function also runs `org-shiftmetadown-final-hook' using the
+same logic."
   (interactive "P")
   (cond
    ((run-hook-with-args-until-success 'org-shiftmetadown-hook))
    ((org-at-table-p) (call-interactively 'org-table-insert-row))
    ((org-at-clock-log-p) (let ((org-clock-adjust-closest t))
 			   (call-interactively 'org-timestamp-down)))
+   ((run-hook-with-args-until-success 'org-shiftmetadown-final-hook))
    (t (call-interactively 'org-drag-line-forward))))
 
 (defsubst org-hidden-tree-error ()
@@ -16822,8 +16886,10 @@ depending on context.  With no specific context, calls the Emacs
 default `backward-word'.  See the individual commands for more
 information.
 
-This function runs the hook `org-metaleft-hook' as a first step,
-and returns at first non-nil value."
+This function runs the functions in `org-metaleft-hook' one by
+one as a first step, and exits immediately if a function from the
+hook returns non-nil.  In the absence of a specific context, the
+function runs `org-metaleft-final-hook' using the same logic."
   (interactive "P")
   (cond
    ((run-hook-with-args-until-success 'org-metaleft-hook))
@@ -16846,6 +16912,7 @@ and returns at first non-nil value."
 	       (org-at-item-p))))
     (when (org-check-for-hidden 'items) (org-hidden-tree-error))
     (call-interactively 'org-outdent-item))
+   ((run-hook-with-args-until-success 'org-metaleft-final-hook))
    (t (call-interactively 'backward-word))))
 
 (defun org-metaright (&optional _arg)
@@ -16858,8 +16925,10 @@ Calls `org-do-demote', `org-indent-item', `org-table-move-column',
 With no specific context, calls the Emacs default `forward-word'.
 See the individual commands for more information.
 
-This function runs the hook `org-metaright-hook' as a first step,
-and returns at first non-nil value."
+This function runs the functions in `org-metaright-hook' one by
+one as a first step, and exits immediately if a function from the
+hook returns non-nil.  In the absence of a specific context, the
+function runs `org-metaright-final-hook' using the same logic."
   (interactive "P")
   (cond
    ((run-hook-with-args-until-success 'org-metaright-hook))
@@ -16884,6 +16953,7 @@ and returns at first non-nil value."
 	       (org-at-item-p))))
     (when (org-check-for-hidden 'items) (org-hidden-tree-error))
     (call-interactively 'org-indent-item))
+   ((run-hook-with-args-until-success 'org-metaright-final-hook))
    (t (call-interactively 'forward-word))))
 
 (defun org-check-for-hidden (what)
@@ -16916,8 +16986,14 @@ this function returns t, nil otherwise."
 (defun org-metaup (&optional _arg)
   "Move subtree up or move table row up.
 Calls `org-move-subtree-up' or `org-table-move-row' or
-`org-move-item-up', depending on context.  See the individual commands
-for more information."
+`org-move-item-up', depending on context.  Everywhere else, move
+backward the element at point.  See the individual commands for
+more information.
+
+This function runs the functions in `org-metaup-hook' one by one
+as a first step, and exits immediately if a function from the
+hook returns non-nil.  In the absence of a specific context, the
+function runs `org-metaup-final-hook' using the same logic."
   (interactive "P")
   (cond
    ((run-hook-with-args-until-success 'org-metaup-hook))
@@ -16974,13 +17050,20 @@ for more information."
     (org-drag-element-backward))
    ((org-at-heading-p) (call-interactively 'org-move-subtree-up))
    ((org-at-item-p) (call-interactively 'org-move-item-up))
+   ((run-hook-with-args-until-success 'org-metaup-final-hook))
    (t (org-drag-element-backward))))
 
 (defun org-metadown (&optional _arg)
   "Move subtree down or move table row down.
 Calls `org-move-subtree-down' or `org-table-move-row' or
-`org-move-item-down', depending on context.  See the individual
-commands for more information."
+`org-move-item-down', depending on context.  Everywhere else,
+move forward the element at point.  See the individual commands
+for more information.
+
+This function runs the functions in `org-metadown-hook' one by
+one as a first step, and exits immediately if a function from the
+hook returns non-nil.  In the absence of a specific context, the
+function runs `org-metadown-final-hook' using the same logic."
   (interactive "P")
   (cond
    ((run-hook-with-args-until-success 'org-metadown-hook))
@@ -17033,13 +17116,24 @@ commands for more information."
     (org-drag-element-forward))
    ((org-at-heading-p) (call-interactively 'org-move-subtree-down))
    ((org-at-item-p) (call-interactively 'org-move-item-down))
+   ((run-hook-with-args-until-success 'org-metadown-final-hook))
    (t (org-drag-element-forward))))
 
 (defun org-shiftup (&optional arg)
   "Act on current element according to context.
 Call `org-timestamp-up' or `org-priority-up', or
 `org-previous-item', or `org-table-move-cell-up'.  See the
-individual commands for more information."
+individual commands for more information.
+
+This function runs the functions in `org-shiftup-hook' one by one
+as a first step, and exits immediately if a function from the
+hook returns non-nil.  In the absence of a specific context, the
+function also runs `org-shiftup-final-hook' using the same logic.
+
+If none of the previous steps succeed and
+`org-support-shift-select' is non-nil, the function runs
+`shift-select-mode' associated command.  See that variable for
+more information."
   (interactive "P")
   (cond
    ((run-hook-with-args-until-success 'org-shiftup-hook))
@@ -17067,7 +17161,18 @@ individual commands for more information."
   "Act on current element according to context.
 Call `org-timestamp-down' or `org-priority-down', or
 `org-next-item', or `org-table-move-cell-down'.  See the
-individual commands for more information."
+individual commands for more information.
+
+This function runs the functions in `org-shiftdown-hook' one by
+one as a first step, and exits immediately if a function from the
+hook returns non-nil.  In the absence of a specific context, the
+function also runs `org-shiftdown-final-hook' using the same
+logic.
+
+If none of the previous steps succeed and
+`org-support-shift-select' is non-nil, the function runs
+`shift-select-mode' associated command.  See that variable for
+more information."
   (interactive "P")
   (cond
    ((run-hook-with-args-until-success 'org-shiftdown-hook))
@@ -17100,7 +17205,16 @@ This does one of the following:
 - on an item, switch entire list to the next bullet type
 - on a property line, switch to the next allowed value
 - on a clocktable definition line, move time block into the future
-- in a table, move a single cell right"
+- in a table, move a single cell right
+
+This function runs the functions in `org-shiftright-hook' one by
+one as a first step, and exits immediately if a function from the
+hook returns non-nil.  In the absence of a specific context, the
+function runs `org-shiftright-final-hook' using the same logic.
+
+If none of the above succeeds and `org-support-shift-select' is
+non-nil, runs `shift-select-mode' specific command.  See that
+variable for more information."
   (interactive "P")
   (cond
    ((run-hook-with-args-until-success 'org-shiftright-hook))
@@ -17140,7 +17254,16 @@ This does one of the following:
 - on an item, switch entire list to the previous bullet type
 - on a property line, switch to the previous allowed value
 - on a clocktable definition line, move time block into the past
-- in a table, move a single cell left"
+- in a table, move a single cell left
+
+This function runs the functions in `org-shiftleft-hook' one by
+one as a first step, and exits immediately if a function from the
+hook returns non-nil.  In the absence of a specific context, the
+function runs `org-shiftleft-final-hook' using the same logic.
+
+If none of the above succeeds and `org-support-shift-select' is
+non-nil, runs `shift-select-mode' specific command.  See that
+variable for more information."
   (interactive "P")
   (cond
    ((run-hook-with-args-until-success 'org-shiftleft-hook))
-- 
2.34.1

Re: [PATCH v3] lisp/org.el: Add final hooks to S-/M-/S-M-cursor commands

[Ihor Radchenko]

Evgenii Klimov <eugene.dev@lipklim.org> writes:

> Reworded as we discussed. Also for commands that support
> `shift-select-mode' (i.e. org-shift{up,down,right,left}) mentioned it
> and `org-support-shift-select'.
>
> From b27b95efbad7645d7bd4870becd112abc25c9840 Mon Sep 17 00:00:00 2001
> From: Evgenii Klimov <eugene.dev@lipklim.org>
> Date: Thu, 29 Jun 2023 20:06:33 +0100
> Subject: [PATCH v3] lisp/org.el: Add final hooks to S-/M-/S-M-cursor commands

Thanks!
Applied, onto main.

Note that you have reached the contribution limit allowed without FSF
copyright assignment. If you want to contribute further, please consider
signing copyright paperwork. See
https://orgmode.org/worg/org-contribute.html#copyright

-- 
Ihor Radchenko // yantar92,
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: [PATCH v3] lisp/org.el: Add final hooks to S-/M-/S-M-cursor commands

[Evgenii Klimov]

Ihor Radchenko <yantar92@posteo.net> writes:

[...]
>
> Thanks!
> Applied, onto main.

Thanks, it's a great pleasure!

> Note that you have reached the contribution limit allowed without FSF
> copyright assignment. If you want to contribute further, please consider
> signing copyright paperwork. See
> https://orgmode.org/worg/org-contribute.html#copyright

Paperwork in process.

Re: [PATCH v3] lisp/org.el: Add final hooks to S-/M-/S-M-cursor commands

[Ihor Radchenko]

Evgenii Klimov <eugene.dev@lipklim.org> writes:

>> https://orgmode.org/worg/org-contribute.html#copyright
>
> Paperwork in process.

Great!
Note that FSF should reply within 5 working days.
If not, you can follow up with them, and also with us.

-- 
Ihor Radchenko // yantar92,
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>