Re: [PATCH] Add repeat-map for navigation commands

[Visuwesh <visuweshm@gmail.com>]

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

[ஞாயிறு செப்டம்பர் 22, 2024] Ihor Radchenko wrote:

> Visuwesh <visuweshm@gmail.com> writes:
>
>> Please find attached.  I tried my best to write the manual entry but it
>> still reads awkward.
>
> Thanks!
>
>> * lisp/org-keys.el (org-up-heading): Add new alias for
>> outline-up-heading.
>
> Please quote Elisp symbols as `outline-up-heading'.
>
>> +** Repeating commands
>> +:PROPERTIES:
>> +:DESCRIPTION: Repeating navigation commands
>> +:END:
>> +
>> +#+cindex: repeat-mode, org-mode
>> +#+cindex: repeating navigation commands
>> +When ~repeat-mode~ is turned on, headline motion commands, link and
>> +block navigation commands by only pressing a single key.  For example,
>> +when navigation to the next headline using {{{kbd(C-c C-n)}}}, a
>> +repeat map is activated that lets you quickly execute headline motion
>> +commands.  When a key not in the map is pressed, it exits ~repeat-mode~
>> +and the command corresponding to the key is executed.
>
> 1. You can link to "9.11 Repeating a Command" section of Emacs manual
> 2. I think that it is a good idea to provide a more clear example.
>    Something like: "Instead of pressing C-c C-n repeatedly, you can
>    omit C-c and just use C-c C-n n n p u... to move around."
> 3. We need to clarify which bindings are default (n, p, u, f,
>    b). Probably as a table.
>
>> +*** Some navigation commands can now be repeated
>> +
>> +When ~repeat-mode~ is turned on, certain navigation can be repeated.
>> +These include the headline navigation commands, ~org-next-link~ and
>> +~org-previous-link~, and ~org-next-block~ and ~org-previous-block~.
>
> Example and a link to Emacs manual would also be good here.
> And we probably need to mention `org-navigation-repeat-map' to let users
> know what to customize if they prefer alternative bindings.

Thank you for the review, and sorry for the delay.  Can you review the
attached please?


[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #2: 0001-Add-repeat-mode-keymap-for-navigation-commands.patch --]
[-- Type: text/x-diff, Size: 6685 bytes --]

From cffbbe543d466cbdd2b76bfe5be6a7d693bc30f9 Mon Sep 17 00:00:00 2001
From: Visuwesh <visuweshm@gmail.com>
Date: Mon, 9 Sep 2024 19:46:47 +0530
Subject: [PATCH] Add repeat-mode keymap for navigation commands

* lisp/org-keys.el (org-up-heading): Add new alias for
`outline-up-heading'.
(org-mode-map): Remap `outline-up-heading' to the new alias.
(org-navigation-repeat-map, org-link-navigation-repeat-map)
(org-block-navigation-repeat-map): Add new repeat-maps to make
navigation easier.
* doc/org-manual.org (Repeating commands): Document the new feature in the manual.
* etc/ORG-NEWS (Some navigation commands can now be repeated): Announce it.
---
 doc/org-manual.org | 43 +++++++++++++++++++++++++++++++++++++++++++
 etc/ORG-NEWS       | 10 ++++++++++
 lisp/org-keys.el   | 34 ++++++++++++++++++++++++++++++++++
 3 files changed, 87 insertions(+)

diff --git a/doc/org-manual.org b/doc/org-manual.org
index 9365c66b1..e533fe890 100644
--- a/doc/org-manual.org
+++ b/doc/org-manual.org
@@ -21657,6 +21657,49 @@ of ~org-yank-dnd-method~.  Image files pasted this way also respect
 the value of ~org-yank-image-save-method~ when the action to perform
 is =attach=.
 
+** Repeating commands
+:PROPERTIES:
+:DESCRIPTION: Repeating navigation commands
+:END:
+
+#+cindex: repeat-mode, org-mode
+#+cindex: repeating navigation commands
+When ~repeat-mode~ is turned on, headline motion commands, link and
+block navigation commands by only pressing a single key.  For example,
+instead of typing {{{kbd(C-c C-n)}}} repeatedly, you can omit C-c and
+just type {{{kbd(C-c C-n n n n p u ...)}}} to move to different
+headlines.  When a key not in the map is pressed, it exits
+~repeat-mode~ and the command corresponding to the key is executed
+(see the [[info:emacs#Repeating][Emacs user manual]]).
+
+By default, the following commands are made repeatable in separate
+repeat-maps.
+
+~org-navigation-repeat-map~:
+
+| Command                           | Key binding        | Repeat key   |
+|-----------------------------------+--------------------+--------------|
+| ~org-next-visible-heading~        | {{{kbd(C-c C-n)}}} | {{{kbd(n)}}} |
+| ~org-previous-visible-heading~    | {{{kbd(C-c C-p)}}} | {{{kbd(p)}}} |
+| ~org-forward-heading-same-level~  | {{{kbd(C-c C-f)}}} | {{{kbd(f)}}} |
+| ~org-backward-heading-same-level~ | {{{kbd(C-c C-b)}}} | {{{kbd(b)}}} |
+| ~org-up-heading~                  | {{{kbd(C-c C-u)}}} | {{{kbd(u)}}} |
+
+
+~org-block-navigation-repeat-map~:
+
+| Command              | Key binding        | Repeat key   |
+|----------------------+--------------------+--------------|
+| ~org-next-block~     | {{{kbd(C-c M-f)}}} | {{{kbd(f)}}} |
+| ~org-previous-block~ | {{{kbd(C-c M-b)}}} | {{{kbd(b)}}} |
+
+~org-link-navigation-repeat-map~:
+
+| Command             | Key binding            | Repeat key   |
+|---------------------+------------------------+--------------|
+| ~org-next-link~     | {{{kbd(C-c C-x C-n)}}} | {{{kbd(n)}}} |
+| ~org-previous-link~ | {{{kbd(C-c C-x C-p)}}} | {{{kbd(p)}}} |
+
 * Hacking
 :PROPERTIES:
 :DESCRIPTION: How to hack your way around.
diff --git a/etc/ORG-NEWS b/etc/ORG-NEWS
index 392788055..e4d31e6a6 100644
--- a/etc/ORG-NEWS
+++ b/etc/ORG-NEWS
@@ -77,6 +77,16 @@ You can now create links to =shortdoc= documentation groups for Emacs
 Lisp functions (see =M-x shortdoc-display-group=).  Requires Emacs 28
 or newer.
 
+*** Some navigation commands can now be repeated
+
+When ~repeat-mode~ is turned on, certain navigation can be repeated.
+These include the headline navigation commands, ~org-next-link~ and
+~org-previous-link~, and ~org-next-block~ and ~org-previous-block~.
+See the [[info:emacs#Repeating][Emacs user manual]] for more info on ~repeat-mode~.  The
+keybindings in the repeat-maps can be changed by customizing
+~org-navigation-repeat-map~, ~org-link-navigation-repeat-map~, and
+~org-block-navigation-repeat-map~.
+
 ** New and changed options
 
 # Chanes deadling with changing default values of customizations,
diff --git a/lisp/org-keys.el b/lisp/org-keys.el
index 1daedaae8..f6de753af 100644
--- a/lisp/org-keys.el
+++ b/lisp/org-keys.el
@@ -232,6 +232,7 @@ (declare-function org-up-element "org" ())
 (declare-function org-update-statistics-cookies "org" (all))
 (declare-function org-yank "org" (&optional arg))
 (declare-function orgtbl-ascii-plot "org-table" (&optional ask))
+(declare-function outline-up-heading "outline" (arg &optional invisible-ok))
 
 
 \f
@@ -409,6 +410,8 @@ (define-key org-mode-map [remap outline-next-visible-heading]
 (define-key org-mode-map [remap outline-previous-visible-heading]
   #'org-previous-visible-heading)
 (define-key org-mode-map [remap outline-show-children] #'org-fold-show-children)
+(defalias 'org-up-heading #'outline-up-heading)
+(define-key org-mode-map [remap outline-up-heading] #'org-up-heading)
 
 ;;;; Make `C-c C-x' a prefix key
 (org-defkey org-mode-map (kbd "C-c C-x") (make-sparse-keymap))
@@ -462,6 +465,37 @@ (org-defkey org-mode-map (kbd "C-S-<left>") #'org-shiftcontrolleft)
 (org-defkey org-mode-map (kbd "C-S-<up>") #'org-shiftcontrolup)
 (org-defkey org-mode-map (kbd "C-S-<down>") #'org-shiftcontroldown)
 
+;;; Repeat-mode map.
+(defvar org-navigation-repeat-map (make-sparse-keymap)
+  "Repeat keymap for navigation commands.")
+(org-defkey org-navigation-repeat-map (kbd "b") #'org-backward-heading-same-level)
+(org-defkey org-navigation-repeat-map (kbd "f") #'org-forward-heading-same-level)
+(org-defkey org-navigation-repeat-map (kbd "n") #'org-next-visible-heading)
+(org-defkey org-navigation-repeat-map (kbd "p") #'org-previous-visible-heading)
+(org-defkey org-navigation-repeat-map (kbd "u") #'org-up-heading)
+(map-keymap
+ (lambda (_key cmd)
+   (put cmd 'repeat-map 'org-navigation-repeat-map))
+ org-navigation-repeat-map)
+
+(defvar org-link-navigation-repeat-map (make-sparse-keymap)
+  "Repeat keymap for link navigation commands.")
+(org-defkey org-link-navigation-repeat-map (kbd "n") #'org-next-link)
+(org-defkey org-link-navigation-repeat-map (kbd "p") #'org-previous-link)
+(map-keymap
+ (lambda (_ cmd)
+   (put cmd 'repeat-map 'org-link-navigation-repeat-map))
+ org-link-navigation-repeat-map)
+
+(defvar org-block-navigation-repeat-map (make-sparse-keymap)
+  "Repeat keymap for block navigation commands.")
+(org-defkey org-block-navigation-repeat-map (kbd "f") #'org-next-block)
+(org-defkey org-block-navigation-repeat-map (kbd "b") #'org-previous-block)
+(map-keymap
+ (lambda (_ cmd)
+   (put cmd 'repeat-map 'org-block-navigation-repeat-map))
+ org-block-navigation-repeat-map)
+
 ;;;; Extra keys for TTY access.
 
 ;;  We only set them when really needed because otherwise the
-- 
2.45.2