[DISCUSSION] "quick-help" popup for org-columns (column view)

[DISCUSSION] "quick-help" popup for org-columns (column view)

[Sławomir Grochowski]

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

Dear All,

Inspired by "Re: Adding a "quick-help" menu"
https://lists.gnu.org/archive/html/emacs-devel/2022-10/msg01138.html

I've created a "quick-help" for functionality in org-mode - column view
(https://orgmode.org/worg/org-tutorials/org-column-view-tutorial.html)

This is a popup with keybindings available in the 'column view'.
In attachment: screenshot and animated gif to see this in motion.

Function 'help-quick' could be easily modified to take some parameters.
This would allow to create a "help-quick" popups for other packages.
I think it's pretty helpful in column view. 

Please let me know what you think.


[-- Attachment #2: colview-quick-help.png --]
[-- Type: image/png, Size: 104768 bytes --]

[-- Attachment #3: 2024-02-08 16-37-17-colview-quick-help.gif --]
[-- Type: image/gif, Size: 266424 bytes --]

[-- Attachment #4: Type: text/plain, Size: 28 bytes --]


--
Sławomir Grochowski

Re: [DISCUSSION] "quick-help" popup for org-columns (column view)

[Adam Porter]

Since transient.el is part of Emacs now, these kinds of menus should 
probably be implemented with it.

Re: [DISCUSSION] "quick-help" popup for org-columns (column view)

[Stefan Kangas]

Adam Porter <adam@alphapapa.net> writes:

> Since transient.el is part of Emacs now, these kinds of menus should
> probably be implemented with it.

IIUC, this is not a menu, but a reminder of key bindings that are usable
in that context.  Other keybindings here are self-inserting keys, which
are equally useful, and they wouldn't be available in a transient.

Re: [DISCUSSION] "quick-help" popup for org-columns (column view)

[Ihor Radchenko]

Stefan Kangas <stefankangas@gmail.com> writes:

> Adam Porter <adam@alphapapa.net> writes:
>
>> Since transient.el is part of Emacs now, these kinds of menus should
>> probably be implemented with it.
>
> IIUC, this is not a menu, but a reminder of key bindings that are usable
> in that context.  Other keybindings here are self-inserting keys, which
> are equally useful, and they wouldn't be available in a transient.

I am wondering how quick-help, transient, and which-key (AFAIU, it is to
be included into the core soon-ish) play together.

transient provides a specific way to define the displayed layout, among
other things. At the same time, quick-help provides an alternative
(undocumented) way to define the layout. And which-key uses pre-defined
layout.

I am wondering if transient style to define how various options in the
menu/help buffer/which-key buffer can be unified.

-- 
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: [DISCUSSION] "quick-help" popup for org-columns (column view)

[Philip Kaludercic]

Ihor Radchenko <yantar92@posteo.net> writes:

> Stefan Kangas <stefankangas@gmail.com> writes:
>
>> Adam Porter <adam@alphapapa.net> writes:
>>
>>> Since transient.el is part of Emacs now, these kinds of menus should
>>> probably be implemented with it.
>>
>> IIUC, this is not a menu, but a reminder of key bindings that are usable
>> in that context.  Other keybindings here are self-inserting keys, which
>> are equally useful, and they wouldn't be available in a transient.

The point of quick-help is to provide a persistent buffer with useful
bindings, comparable to what Nano does OOTB.

> I am wondering how quick-help, transient, and which-key (AFAIU, it is to
> be included into the core soon-ish) play together.
>
> transient provides a specific way to define the displayed layout, among
> other things. At the same time, quick-help provides an alternative
> (undocumented) way to define the layout. And which-key uses pre-defined
> layout.

One critical difference between which-key and transient compared to
quick-help, is that the latter has nothing to do with prefix maps, but
(by default) just presents global bindings, and is as such closer to a
curated version of `describe-bindings' (sort of like how `shortdocs' is
a curated version of `apropos-functions').

> I am wondering if transient style to define how various options in the
> menu/help buffer/which-key buffer can be unified.

-- 
Philip Kaludercic

RE: [External] : Re: [DISCUSSION] "quick-help" popup for org-columns (column view)

[Drew Adams]

> The point of quick-help is to provide a persistent buffer
> with useful bindings, comparable to what Nano does OOTB.

> One critical difference between which-key and transient
> compared to quick-help, is that the latter has nothing
> to do with prefix maps, but (by default) just presents
> global bindings, and is as such closer to a curated
> version of `describe-bindings' (sort of like how
> `shortdocs' is a curated version of `apropos-functions').

1. Doesn't which-key also provide the
possibility (e.g., on-demand instead of
by timer) to show all currently available
bindings at top level, i.e., not on a
prefix key)?  I thought it had added that
feature at some point.

If it doesn't, then that's another big
difference ("critical", you say) from
KeySee.
___

2. As for getting the completions in a
buffer that you can access "persistently"
(and, e.g., to search or edit):

There should be a separate, more general
feature for that: be able to "save" the
current contents of `*Completions* (or
another buffer displaying completions) to
another buffer, regardless of what that
completions buffer is showing.

IOW, this shouldn't be only about _key_
completions and descriptions as help.

Icicles provides such a feature (as does
Embark, IIUC).  Emacs should have it.  Hit
a key, enter a destination buffer name (or
just hit RET for a default name).
___

3. Icicles can also show you complete help
for key completions shown in *Completions*,
in *Help*.  And likewise for any other
kind of completions for which there's a
help description.

Showing help for completions is another
general feature that Emacs should have.
___

https://www.emacswiki.org/emacs/download/keysee.el

Re: [DISCUSSION] "quick-help" popup for org-columns (column view)

[JD Smith]

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



> On Feb 8, 2024, at 6:01 PM, Stefan Kangas <stefankangas@gmail.com> wrote:
> 
> Adam Porter <adam@alphapapa.net> writes:
> 
>> Since transient.el is part of Emacs now, these kinds of menus should
>> probably be implemented with it.
> 
> IIUC, this is not a menu, but a reminder of key bindings that are usable
> in that context.  Other keybindings here are self-inserting keys, which
> are equally useful, and they wouldn't be available in a transient.

Also recall we had a discussion in bug#68236 <https://lists.gnu.org/archive/html/bug-gnu-emacs/2024-01/msg00124.html> about expanding quick-help to include mode-local personalized binding shortcuts (with org as a particular target of interest).  


[-- Attachment #2: Type: text/html, Size: 1263 bytes --]

Re: [DISCUSSION] "quick-help" popup for org-columns (column view)

[Ihor Radchenko]

Sławomir Grochowski <slawomir.grochowski@gmail.com> writes:

> Inspired by "Re: Adding a "quick-help" menu"
> https://lists.gnu.org/archive/html/emacs-devel/2022-10/msg01138.html
>
> I've created a "quick-help" for functionality in org-mode - column view
> (https://orgmode.org/worg/org-tutorials/org-column-view-tutorial.html)
>
> This is a popup with keybindings available in the 'column view'.
> In attachment: screenshot and animated gif to see this in motion.
>
> Function 'help-quick' could be easily modified to take some parameters.
> This would allow to create a "help-quick" popups for other packages.
> I think it's pretty helpful in column view. 
>
> Please let me know what you think.

I see no downside supporting `help-quick' command in Org mode's column
view. Generally, better integration with Emacs built-in functionality is
welcome.

We may even bind `help-quick' to something easier than <f1> C-q in
`org-columns-map'. For example, it can be "?".

-- 
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: [DISCUSSION] "quick-help" popup for org-columns (column view)

[Sławomir Grochowski]

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

Ihor Radchenko <yantar92@posteo.net> writes:

> I see no downside supporting `help-quick' command in Org mode's column
> view. Generally, better integration with Emacs built-in functionality is
> welcome.

Great. I'll be happy to take care of it.

But first, we need to modify `help-quick' to be more reusable.
I tried to do it, but I'm not experienced in elisp.
I wanted to remove references to global variables, so I did a wrapper
function to pass arguments to `help-quick'. I understand it's not a lispy way.
I would be grateful for your comment. 

Patch in attachment.

[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #2: 0001-lisp-help-make-help-quick-toggle-reusable-for-other-.patch --]
[-- Type: text/x-diff, Size: 3327 bytes --]

From 5f343fd15c53f5bc5e7515ef0cd3049b4e0ec388 Mon Sep 17 00:00:00 2001
From: Slawomir Grochowski <slawomir.grochowski@gmail.com>
Date: Sat, 6 Apr 2024 22:11:01 +0200
Subject: [PATCH] lisp/help: make `help-quick-toggle' reusable for other
 keymaps

---
 lisp/help.el | 22 +++++++++++++---------
 1 file changed, 13 insertions(+), 9 deletions(-)

diff --git a/lisp/help.el b/lisp/help.el
index 1ef46e394f3..c32d1a2e943 100644
--- a/lisp/help.el
+++ b/lisp/help.el
@@ -76,7 +76,7 @@ help-map
   "C-n"  #'view-emacs-news
   "C-o"  #'describe-distribution
   "C-p"  #'view-emacs-problems
-  "C-q"  #'help-quick-toggle
+  "C-q"  #'help-quick-toggle-wrapper
   "C-s"  #'search-forward-help-for-help
   "C-t"  #'view-emacs-todo
   "C-w"  #'describe-no-warranty
@@ -178,22 +178,22 @@ help-quick-sections
 (declare-function prop-match-value "text-property-search" (match))
 
 ;; Inspired by a mg fork (https://github.com/troglobit/mg)
-(defun help-quick ()
+(defun help-quick (name-for-buffer sections &optional keymap)
   "Display a quick-help buffer showing popular commands and their bindings.
 The window showing quick-help can be toggled using \\[help-quick-toggle].
 You can click on a key binding shown in the quick-help buffer to display
 the documentation of the command bound to that key sequence."
   (interactive)
-  (with-current-buffer (get-buffer-create "*Quick Help*")
+  (with-current-buffer (get-buffer-create name-for-buffer)
     (let ((inhibit-read-only t) (padding 2) blocks)
 
       ;; Go through every section and prepare a text-rectangle to be
       ;; inserted later.
-      (dolist (section help-quick-sections)
+      (dolist (section sections)
         (let ((max-key-len 0) (max-cmd-len 0) keys)
           (dolist (ent (reverse (cdr section)))
             (catch 'skip
-              (let* ((bind (where-is-internal (car ent) nil t))
+              (let* ((bind (where-is-internal (car ent) keymap t))
                      (key (if bind
                               (propertize
                                (key-description bind)
@@ -259,21 +259,25 @@ help-quick
     (message
      (substitute-command-keys "Toggle display of quick-help buffer using \\[help-quick-toggle]."))))
 
-(defun help-quick-toggle ()
+(defun help-quick-toggle-wrapper ()
+  (interactive)
+  (help-quick-toggle "*Quick Help*" help-quick-sections))
+
+(defun help-quick-toggle (name-for-buffer sections &optional keymap)
   "Toggle display of a window showing popular commands and their bindings.
 This toggles on and off the display of the quick-help buffer, which shows
 popular commands and their bindings as produced by `help-quick'.
 You can click on a key binding shown in the quick-help buffer to display
 the documentation of the command bound to that key sequence."
   (interactive)
-  (if (and-let* ((window (get-buffer-window "*Quick Help*")))
+  (if (and-let* ((window (get-buffer-window name-for-buffer)))
         (quit-window t window))
       ;; Clear the message we may have gotten from `C-h' and then
       ;; waiting before hitting `q'.
       (message "")
-    (help-quick)))
+    (help-quick name-for-buffer sections keymap)))
 
-(defalias 'cheat-sheet #'help-quick)
+(defalias 'cheat-sheet #'help-quick-wrapper)
 
 (defun help-quit ()
   "Just exit from the Help command's command loop."
-- 
2.30.2


[-- Attachment #3: Type: text/plain, Size: 376 bytes --]


JD Smith <jdtsmith@gmail.com> writes: 

> Also recall we had a discussion in bug#68236 <https://lists.gnu.org/archive/html/bug-gnu-emacs/2024-01/msg00124.html> about expanding quick-help to include mode-local
> personalized binding shortcuts (with org as a particular target of interest).

Thank you for the link I haven't seen that topic.
 
Regards,
-- 
Slawomir Grochowski

Re: [DISCUSSION] "quick-help" popup for org-columns (column view)

[chad]

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

On Sat, Apr 6, 2024 at 5:42 PM Sławomir Grochowski <
slawomir.grochowski@gmail.com> wrote:

> But first, we need to modify `help-quick' to be more reusable.
> I tried to do it, but I'm not experienced in elisp.
> I wanted to remove references to global variables, so I did a wrapper
> function to pass arguments to `help-quick'. I understand it's not a lispy
> way.
> I would be grateful for your comment.
>

If you don't mind me asking:

What are your high-level goals and immediate needs for changing
help-quick? It looks like you may be trying to have multiple
simultaneous quick-help buffers active at once? History with
emacs suggests that that avenue tends to be confusing and
cumbersome, and _generally_ not fruitful. (As one big concrete
example, I spent years working with "computer help" at my
university where Emacs was the default editor (in the 90s), and
some form of "My window is cut in half; how do I get it all
back?" was frequently the most common editor question.)

Thanks,
~Chad

[-- Attachment #2: Type: text/html, Size: 1571 bytes --]

Re: [DISCUSSION] "quick-help" popup for org-columns (column view)

[Philip Kaludercic]

Sławomir Grochowski <slawomir.grochowski@gmail.com> writes:

> Ihor Radchenko <yantar92@posteo.net> writes:
>
>> I see no downside supporting `help-quick' command in Org mode's column
>> view. Generally, better integration with Emacs built-in functionality is
>> welcome.
>
> Great. I'll be happy to take care of it.
>
> But first, we need to modify `help-quick' to be more reusable.
> I tried to do it, but I'm not experienced in elisp.
> I wanted to remove references to global variables, so I did a wrapper
> function to pass arguments to `help-quick'. I understand it's not a lispy way.
> I would be grateful for your comment. 
>
> Patch in attachment.

I have to admit that I am not entirely certain what the plan is, but I
have a few concrete comments/questions on this patch

> From 5f343fd15c53f5bc5e7515ef0cd3049b4e0ec388 Mon Sep 17 00:00:00 2001
> From: Slawomir Grochowski <slawomir.grochowski@gmail.com>
> Date: Sat, 6 Apr 2024 22:11:01 +0200
> Subject: [PATCH] lisp/help: make `help-quick-toggle' reusable for other
>  keymaps
>
> ---
>  lisp/help.el | 22 +++++++++++++---------
>  1 file changed, 13 insertions(+), 9 deletions(-)
>
> diff --git a/lisp/help.el b/lisp/help.el
> index 1ef46e394f3..c32d1a2e943 100644
> --- a/lisp/help.el
> +++ b/lisp/help.el
> @@ -76,7 +76,7 @@ help-map
>    "C-n"  #'view-emacs-news
>    "C-o"  #'describe-distribution
>    "C-p"  #'view-emacs-problems
> -  "C-q"  #'help-quick-toggle
> +  "C-q"  #'help-quick-toggle-wrapper
>    "C-s"  #'search-forward-help-for-help
>    "C-t"  #'view-emacs-todo
>    "C-w"  #'describe-no-warranty
> @@ -178,22 +178,22 @@ help-quick-sections
>  (declare-function prop-match-value "text-property-search" (match))
>  
>  ;; Inspired by a mg fork (https://github.com/troglobit/mg)
> -(defun help-quick ()
> +(defun help-quick (name-for-buffer sections &optional keymap)
>    "Display a quick-help buffer showing popular commands and their bindings.
>  The window showing quick-help can be toggled using \\[help-quick-toggle].
>  You can click on a key binding shown in the quick-help buffer to display
>  the documentation of the command bound to that key sequence."
>    (interactive)
> -  (with-current-buffer (get-buffer-create "*Quick Help*")
> +  (with-current-buffer (get-buffer-create name-for-buffer)

Is there a reason not to re-use the same buffer?  I am not sure if we
need multiple quick-help buffer to co-exist at the same time.

>      (let ((inhibit-read-only t) (padding 2) blocks)
>  
>        ;; Go through every section and prepare a text-rectangle to be
>        ;; inserted later.
> -      (dolist (section help-quick-sections)
> +      (dolist (section sections)

The idea here was that some other function could rebind
`help-quick-sections' dynamically.  That way you avoid the redundant
arguments (which would all have to be documented).

>          (let ((max-key-len 0) (max-cmd-len 0) keys)
>            (dolist (ent (reverse (cdr section)))
>              (catch 'skip
> -              (let* ((bind (where-is-internal (car ent) nil t))
> +              (let* ((bind (where-is-internal (car ent) keymap t))
>                       (key (if bind
>                                (propertize
>                                 (key-description bind)
> @@ -259,21 +259,25 @@ help-quick
>      (message
>       (substitute-command-keys "Toggle display of quick-help buffer using \\[help-quick-toggle]."))))
>  
> -(defun help-quick-toggle ()
> +(defun help-quick-toggle-wrapper ()

The naming here is weird IMO, usually the other function should be
called something like `help-quick-toggle-internal' and this would be
`help-quick-toggle'.

> +  (interactive)
> +  (help-quick-toggle "*Quick Help*" help-quick-sections))
> +
> +(defun help-quick-toggle (name-for-buffer sections &optional keymap)
>    "Toggle display of a window showing popular commands and their bindings.
>  This toggles on and off the display of the quick-help buffer, which shows
>  popular commands and their bindings as produced by `help-quick'.
>  You can click on a key binding shown in the quick-help buffer to display
>  the documentation of the command bound to that key sequence."
>    (interactive)
> -  (if (and-let* ((window (get-buffer-window "*Quick Help*")))
> +  (if (and-let* ((window (get-buffer-window name-for-buffer)))
>          (quit-window t window))
>        ;; Clear the message we may have gotten from `C-h' and then
>        ;; waiting before hitting `q'.
>        (message "")
> -    (help-quick)))
> +    (help-quick name-for-buffer sections keymap)))
>  
> -(defalias 'cheat-sheet #'help-quick)
> +(defalias 'cheat-sheet #'help-quick-wrapper)
>  
>  (defun help-quit ()
>    "Just exit from the Help command's command loop."
> -- 
> 2.30.2
>
>
>
> JD Smith <jdtsmith@gmail.com> writes: 
>
>> Also recall we had a discussion in bug#68236
>> <https://lists.gnu.org/archive/html/bug-gnu-emacs/2024-01/msg00124.html>
>> about expanding quick-help to include mode-local
>> personalized binding shortcuts (with org as a particular target of interest).
>
> Thank you for the link I haven't seen that topic.
>  
> Regards,

-- 
	Philip Kaludercic on icterid

Re: [DISCUSSION] "quick-help" popup for org-columns (column view)

[Eli Zaretskii]

> From: Sławomir Grochowski <slawomir.grochowski@gmail.com>
> Cc: emacs-orgmode@gnu.org, emacs-devel@gnu.org, philipk@posteo.net,
>  stefankangas@gmail.com, larsi@gnus.org, hmelman@gmail.com, eliz@gnu.org,
>  info@protesilaos.com
> Date: Sat, 06 Apr 2024 22:41:32 +0200
> 
> But first, we need to modify `help-quick' to be more reusable.
> I tried to do it, but I'm not experienced in elisp.
> I wanted to remove references to global variables, so I did a wrapper
> function to pass arguments to `help-quick'. I understand it's not a lispy way.
> I would be grateful for your comment. 

I don't understand why you needed a wrapper.  help-quick is already
customizable by modes, via the help-quick-sections variable.  In any
case, we cannot change the signature of help-quick, since it's a
public function.

Re: [DISCUSSION] "quick-help" popup for org-columns (column view)

[Sławomir Grochowski]

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

chad <yandros@gmail.com> writes:

> If you don't mind me asking:

Thank you for sharing your views. 

> What are your high-level goals and immediate needs for changing
> help-quick?

I want to reuse quick-help for functionality in org-mode - column view
package. See first email in this thread - there is even a screenshot.

> It looks like you may be trying to have multiple
> simultaneous quick-help buffers active at once?

Philip Kaludercic <philipk@posteo.net> writes:

> Is there a reason not to re-use the same buffer?  I am not sure if we
> need multiple quick-help buffer to co-exist at the same time.

Yes you are right. There is no need to create multiple quick-help
buffers. 

> The idea here was that some other function could rebind
> `help-quick-sections' dynamically.  That way you avoid the redundant
> arguments (which would all have to be documented).

Is this really a good practice?
Relying on global variables instead of passing variables as a parameters?

I tried like this:

+(defun org-columns-help-quick-toggle ()
+  (interactive)
+  (let ((help-quick-sections org-columns-help-quick-sections))
+    (help-quick-toggle)))

So passing a 'sections' data works.
But it doesn't read keymaps from `org-columns-map'.
Because as I understand it read keymaps available only in the created buffer
"*Quick Help*" not from the buffer with org-colview.

This is the line from function: `help-quick' where it happens:
+ (let* ((bind (where-is-internal (car ent) nil t))
Signature:
(where-is-internal DEFINITION &optional KEYMAP FIRSTONLY NOINDIRECT NO-REMAP)

So previously I was passing a keymap `org-columns-map' to function 'where-is-internal'.

Eli Zaretskii <eliz@gnu.org> writes:
> In any case, we cannot change the signature of help-quick, since it's a
> public function.

If I can't modify the function `help-quick' how can I make it work?

I'm attaching the whole patch:

[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #2: 0001-lisp-org-colview.el-add-help-quick-sections-for-org-.patch --]
[-- Type: text/x-diff, Size: 2704 bytes --]

From dcc5172c87f9f7acfc9ab3a72f7de8b363a05447 Mon Sep 17 00:00:00 2001
From: Slawomir Grochowski <slawomir.grochowski@gmail.com>
Date: Sun, 7 Apr 2024 01:13:27 +0200
Subject: [PATCH] lisp/org-colview.el: add help-quick sections for org-colview

---
 lisp/org-colview.el | 41 +++++++++++++++++++++++++++++++++++++++++
 1 file changed, 41 insertions(+)

diff --git a/lisp/org-colview.el b/lisp/org-colview.el
index d71c84a76..547f50df8 100644
--- a/lisp/org-colview.el
+++ b/lisp/org-colview.el
@@ -169,6 +169,7 @@ See `org-columns-summary-types' for details.")
   (org-cycle-overview)
   (org-cycle-content))
 
+(org-defkey org-columns-map "?"        #'org-columns-help-quick-toggle)
 (org-defkey org-columns-map "c"        #'org-columns-content)
 (org-defkey org-columns-map "o"        #'org-overview)
 (org-defkey org-columns-map "e"        #'org-columns-edit-value)
@@ -231,6 +232,46 @@ See `org-columns-summary-types' for details.")
     "--"
     ["Quit" org-columns-quit t]))
 
+(defvar org-columns-help-quick-sections
+  '(("Move"
+     (org-columns-move-up . "up")
+     (org-columns-move-down . "down")
+     (org-columns-move-cursor-left . "left")
+     (org-columns-move-cursor-right . "right"))
+    ("Move column & row"
+     (org-columns-move-row-up . "move row up")
+     (org-columns-move-row-down . "move row down")
+     (org-columns-move-left . "move column left")
+     (org-columns-move-right . "move column right"))
+    ("Add & delete column"
+     (org-columns-new . "add column")
+     (org-columns-delete . "delete column"))
+    ("Edit column"
+     (org-columns-narrow . "narrow")
+     (org-columns-widen . "widen")
+     (org-columns-edit-attributes . "attributes"))
+    ("Edit values"
+     (org-columns-edit-value . "edit value")
+     (org-columns-edit-allowed . "edit allowed value")
+     (org-columns-next-allowed-value . "next allowed value")
+     (org-columns-previous-allowed-value . "previous allowed value")
+     (org-columns-toggle-or-columns-quit . "toggle checkbox or quit")
+     (org-columns-todo . "change TODO state"))
+    ("View"
+     (org-columns-content . "show content")
+     (org-overview . "show overview")
+     (org-columns-show-value . "show value"))
+    ("Misc."
+     (org-columns-open-link . "open link")
+     (org-columns-redo . "redo")
+     (org-columns-help-quick-toggle . "toggle this help")
+     (org-columns-quit . "quit"))))
+
+(defun org-columns-help-quick-toggle ()
+  (interactive)
+  (let ((help-quick-sections org-columns-help-quick-sections))
+    (help-quick-toggle)))
+
 (defun org-columns--displayed-value (spec value &optional no-star)
   "Return displayed value for specification SPEC in current entry.
 
-- 
2.30.2


[-- Attachment #3: Type: text/plain, Size: 35 bytes --]


Regards,

-- 
Slawomir Grochowski

Re: [DISCUSSION] "quick-help" popup for org-columns (column view)

[Philip Kaludercic]

Sławomir Grochowski <slawomir.grochowski@gmail.com> writes:

> chad <yandros@gmail.com> writes:
>
>> If you don't mind me asking:
>
> Thank you for sharing your views. 
>
>> What are your high-level goals and immediate needs for changing
>> help-quick?
>
> I want to reuse quick-help for functionality in org-mode - column view
> package. See first email in this thread - there is even a screenshot.
>
>> It looks like you may be trying to have multiple
>> simultaneous quick-help buffers active at once?
>
> Philip Kaludercic <philipk@posteo.net> writes:
>
>> Is there a reason not to re-use the same buffer?  I am not sure if we
>> need multiple quick-help buffer to co-exist at the same time.
>
> Yes you are right. There is no need to create multiple quick-help
> buffers. 
>
>> The idea here was that some other function could rebind
>> `help-quick-sections' dynamically.  That way you avoid the redundant
>> arguments (which would all have to be documented).
>
> Is this really a good practice?

It certainly is practice.

> Relying on global variables instead of passing variables as a parameters?

A lot of Emacs Lisp code uses dynamic scope.  Examples include
`default-directory' or a lot of search functionality.

> I tried like this:
>
> +(defun org-columns-help-quick-toggle ()
> +  (interactive)
> +  (let ((help-quick-sections org-columns-help-quick-sections))
> +    (help-quick-toggle)))
>
> So passing a 'sections' data works.
> But it doesn't read keymaps from `org-columns-map'.
> Because as I understand it read keymaps available only in the created buffer
> "*Quick Help*" not from the buffer with org-colview.
>
> This is the line from function: `help-quick' where it happens:
> + (let* ((bind (where-is-internal (car ent) nil t))
> Signature:
> (where-is-internal DEFINITION &optional KEYMAP FIRSTONLY NOINDIRECT NO-REMAP)
>
> So previously I was passing a keymap `org-columns-map' to function 'where-is-internal'.
>
> Eli Zaretskii <eliz@gnu.org> writes:
>> In any case, we cannot change the signature of help-quick, since it's a
>> public function.
>
> If I can't modify the function `help-quick' how can I make it work?

We could add a `help-quick-use-map' variable and bind it to `global-map'
by default.  You can then re-bind it in your command.

> I'm attaching the whole patch:
>
> From dcc5172c87f9f7acfc9ab3a72f7de8b363a05447 Mon Sep 17 00:00:00 2001
> From: Slawomir Grochowski <slawomir.grochowski@gmail.com>
> Date: Sun, 7 Apr 2024 01:13:27 +0200
> Subject: [PATCH] lisp/org-colview.el: add help-quick sections for org-colview
>
> ---
>  lisp/org-colview.el | 41 +++++++++++++++++++++++++++++++++++++++++
>  1 file changed, 41 insertions(+)
>
> diff --git a/lisp/org-colview.el b/lisp/org-colview.el
> index d71c84a76..547f50df8 100644
> --- a/lisp/org-colview.el
> +++ b/lisp/org-colview.el
> @@ -169,6 +169,7 @@ See `org-columns-summary-types' for details.")
>    (org-cycle-overview)
>    (org-cycle-content))
>  
> +(org-defkey org-columns-map "?"        #'org-columns-help-quick-toggle)
>  (org-defkey org-columns-map "c"        #'org-columns-content)
>  (org-defkey org-columns-map "o"        #'org-overview)
>  (org-defkey org-columns-map "e"        #'org-columns-edit-value)
> @@ -231,6 +232,46 @@ See `org-columns-summary-types' for details.")
>      "--"
>      ["Quit" org-columns-quit t]))
>  
> +(defvar org-columns-help-quick-sections
> +  '(("Move"
> +     (org-columns-move-up . "up")
> +     (org-columns-move-down . "down")
> +     (org-columns-move-cursor-left . "left")
> +     (org-columns-move-cursor-right . "right"))
> +    ("Move column & row"
> +     (org-columns-move-row-up . "move row up")
> +     (org-columns-move-row-down . "move row down")
> +     (org-columns-move-left . "move column left")
> +     (org-columns-move-right . "move column right"))
> +    ("Add & delete column"
> +     (org-columns-new . "add column")
> +     (org-columns-delete . "delete column"))
> +    ("Edit column"
> +     (org-columns-narrow . "narrow")
> +     (org-columns-widen . "widen")
> +     (org-columns-edit-attributes . "attributes"))
> +    ("Edit values"
> +     (org-columns-edit-value . "edit value")
> +     (org-columns-edit-allowed . "edit allowed value")
> +     (org-columns-next-allowed-value . "next allowed value")
> +     (org-columns-previous-allowed-value . "previous allowed value")
> +     (org-columns-toggle-or-columns-quit . "toggle checkbox or quit")
> +     (org-columns-todo . "change TODO state"))
> +    ("View"
> +     (org-columns-content . "show content")
> +     (org-overview . "show overview")
> +     (org-columns-show-value . "show value"))
> +    ("Misc."
> +     (org-columns-open-link . "open link")
> +     (org-columns-redo . "redo")
> +     (org-columns-help-quick-toggle . "toggle this help")
> +     (org-columns-quit . "quit"))))
> +
> +(defun org-columns-help-quick-toggle ()
> +  (interactive)
> +  (let ((help-quick-sections org-columns-help-quick-sections))
> +    (help-quick-toggle)))
> +
>  (defun org-columns--displayed-value (spec value &optional no-star)
>    "Return displayed value for specification SPEC in current entry.
>  
> -- 
> 2.30.2
>
>
> Regards,

-- 
	Philip Kaludercic on peregrine

Re: [DISCUSSION] "quick-help" popup for org-columns (column view)

[Sławomir Grochowski]

Philip Kaludercic <philipk@posteo.net> writes:

> We could add a `help-quick-use-map' variable and bind it to `global-map'
> by default.  You can then re-bind it in your command.

I'm sorry, but I don't quite understand it. 

It seems to me that the simplest way is to add a parameter to the
function, like this:

(defun help-quick (&optional keymap)

Because it will not change the behavior for previous calls to this
function.  And it will allow to pass specific keymap, not need to pass
and search in whole global-map. 

What do you think?

-- 
Slawomir Grochowski

Re: [DISCUSSION] "quick-help" popup for org-columns (column view)

[Philip Kaludercic]

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

Sławomir Grochowski <slawomir.grochowski@gmail.com> writes:

> Philip Kaludercic <philipk@posteo.net> writes:
>
>> We could add a `help-quick-use-map' variable and bind it to `global-map'
>> by default.  You can then re-bind it in your command.
>
> I'm sorry, but I don't quite understand it. 

Just this here:


[-- Attachment #2: Type: text/plain, Size: 941 bytes --]

diff --git a/lisp/help.el b/lisp/help.el
index 1ef46e394f3..5700f10fdc8 100644
--- a/lisp/help.el
+++ b/lisp/help.el
@@ -175,6 +175,9 @@ help-quick-sections
 COMMAND is the symbol of a command and DESCRIPTION is its short
 description, 10 to 15 char5acters at most.")
 
+(defvar help-quick-use-map global-map
+  "Keymap that `help-quick' should use to lookup bindings.")
+
 (declare-function prop-match-value "text-property-search" (match))
 
 ;; Inspired by a mg fork (https://github.com/troglobit/mg)
@@ -193,7 +196,7 @@ help-quick
         (let ((max-key-len 0) (max-cmd-len 0) keys)
           (dolist (ent (reverse (cdr section)))
             (catch 'skip
-              (let* ((bind (where-is-internal (car ent) nil t))
+              (let* ((bind (where-is-internal (car ent) help-quick-use-map t))
                      (key (if bind
                               (propertize
                                (key-description bind)

[-- Attachment #3: Type: text/plain, Size: 565 bytes --]


You would then only have to rebind `help-quick-use-map' in your custom
command.

> It seems to me that the simplest way is to add a parameter to the
> function, like this:
>
> (defun help-quick (&optional keymap)
>
> Because it will not change the behavior for previous calls to this
> function.  And it will allow to pass specific keymap, not need to pass
> and search in whole global-map. 
>
> What do you think?

Eli said that we shouldn't change the signature of public functions, so
I don't think that this is an option.


-- 
	Philip Kaludercic on peregrine

Re: [DISCUSSION] "quick-help" popup for org-columns (column view)

[Sławomir Grochowski]

Thank you Philip for the explanation and preparing the code snippet. 

So what are the next steps?
Can you merge your patch?

-- 
Slawomir Grochowski

Re: [DISCUSSION] "quick-help" popup for org-columns (column view)

[Philip Kaludercic]

Sławomir Grochowski <slawomir.grochowski@gmail.com> writes:

> Thank you Philip for the explanation and preparing the code snippet. 
>
> So what are the next steps?
> Can you merge your patch?

If this is everything, I can push the change.  But I'll test it first.

-- 
	Philip Kaludercic on peregrine

Re: [DISCUSSION] "quick-help" popup for org-columns (column view)

[Philip Kaludercic]

Philip Kaludercic <philipk@posteo.net> writes:

> Sławomir Grochowski <slawomir.grochowski@gmail.com> writes:
>
>> Thank you Philip for the explanation and preparing the code snippet. 
>>
>> So what are the next steps?
>> Can you merge your patch?
>
> If this is everything, I can push the change.  But I'll test it first.

I tried out using your `org-columns-help-quick-sections' variable, but
it seems that `where-is' didn't find all the commands you wanted:

--8<---------------cut here---------------start------------->8---
Move column & row            Add & delete column        Edit column   Edit values                      View             Misc.
M-<left>  move column left   M-S-<right> add column     < narrow      e       edit value               c show content   C-c C-o open link
M-<right> move column right  M-S-<left>  delete column  > widen       a       edit allowed value       o show overview  g       redo
							s attributes  n       next allowed value       v show value     q       quit
								      p       previous allowed value
								      C-c C-c toggle checkbox or quit
								      C-c C-t change TODO state
--8<---------------cut here---------------end--------------->8---

(some of the descriptions are pretty long, are they not?)

Are commands like `org-columns-move-up' part of the next release of Org?
I am using whatever is currently on master.

-- 
	Philip Kaludercic on peregrine

Re: [DISCUSSION] "quick-help" popup for org-columns (column view)

[Sławomir Grochowski]

Philip Kaludercic <philipk@posteo.net> writes:

> I tried out using your `org-columns-help-quick-sections' variable, but
> it seems that `where-is' didn't find all the commands you wanted:

> Are commands like `org-columns-move-up' part of the next release of Org?
> I am using whatever is currently on master.

Yes this function was added recently. It's on Org master 
https://git.savannah.gnu.org/cgit/emacs/org-mode.git/tree/lisp/org-colview.el#n997
But not on Emacs repo. 

-- 
Slawomir Grochowski

Re: [DISCUSSION] "quick-help" popup for org-columns (column view)

[Philip Kaludercic]

Philip Kaludercic <philipk@posteo.net> writes:

> Sławomir Grochowski <slawomir.grochowski@gmail.com> writes:
>
>> Thank you Philip for the explanation and preparing the code snippet. 
>>
>> So what are the next steps?
>> Can you merge your patch?
>
> If this is everything, I can push the change.  But I'll test it first.

I have pushed the changes to master.

-- 
	Philip Kaludercic on peregrine

Re: [DISCUSSION] "quick-help" popup for org-columns (column view)

[Sławomir Grochowski]

Philip Kaludercic <philipk@posteo.net> writes:
> I have pushed the changes to master.

Thank you Philip for your help.  It works.

But there is one more small thing. 
A message that is displayed in the minibuffer. 
It contains two pieces of information:

(1)     command name
        Right now it's hardcoded. 
        We need to change the it from `help-quick-toggle' to
        `org-columns-help-quick-toggle'.
        How to do it? 
        Add another variable like `help-quick-use-map'?
        Maybe 'help-quick-command-name'?

(2)     keybinding to the command name
        Just to modify message string. Add '\\<help-quick-use-map>'.
        To use other keymap.
        Change is in the diff below. 
              
diff --git a/lisp/help.el b/lisp/help.el
index d4e39f04e53..35412b9d2fe 100644
--- a/lisp/help.el
+++ b/lisp/help.el
@@ -263,7 +263,9 @@ help-quick
       ;; ... and shrink it immediately.
       (fit-window-to-buffer))
     (message
-     (substitute-command-keys "Toggle display of quick-help buffer using \\[help-quick-toggle]."))))
+     (substitute-command-keys "Toggle display of quick-help buffer using\\<help-quick-use-map> \\[org-columns-help-quick-toggle]."))))
+
+
 
 (defun help-quick-toggle ()
   "Toggle display of a window showing popular commands and their bindings.
-- 
2.30.2


Regards,
-- 
Slawomir Grochowski

Re: [DISCUSSION] "quick-help" popup for org-columns (column view)

[Philip Kaludercic]

Sławomir Grochowski <slawomir.grochowski@gmail.com> writes:

> Philip Kaludercic <philipk@posteo.net> writes:
>> I have pushed the changes to master.
>
> Thank you Philip for your help.  It works.
>
> But there is one more small thing. 
> A message that is displayed in the minibuffer. 
> It contains two pieces of information:
>
> (1)     command name
>         Right now it's hardcoded. 
>         We need to change the it from `help-quick-toggle' to
>         `org-columns-help-quick-toggle'.
>         How to do it? 
>         Add another variable like `help-quick-use-map'?
>         Maybe 'help-quick-command-name'?

Instead of using substitute-command-keys, we could just use
this-command, but that assumes that help-quick can always be toggled by
the command that invokes it.

> (2)     keybinding to the command name
>         Just to modify message string. Add '\\<help-quick-use-map>'.
>         To use other keymap.
>         Change is in the diff below. 

I don't see how this would work in general, at the very least it breaks
the regular usage.

Furthermore, I am not convinced we have to change anything here, since
C-h C-q (the default binding for `help-quick-toggle') should also hide
the buffer if one uses your command, or am I mistaken?

>
> diff --git a/lisp/help.el b/lisp/help.el
> index d4e39f04e53..35412b9d2fe 100644
> --- a/lisp/help.el
> +++ b/lisp/help.el
> @@ -263,7 +263,9 @@ help-quick
>        ;; ... and shrink it immediately.
>        (fit-window-to-buffer))
>      (message
> -     (substitute-command-keys "Toggle display of quick-help buffer using \\[help-quick-toggle]."))))
> +     (substitute-command-keys "Toggle display of quick-help buffer using\\<help-quick-use-map> \\[org-columns-help-quick-toggle]."))))
> +
> +
>  
>  (defun help-quick-toggle ()
>    "Toggle display of a window showing popular commands and their bindings.
> -- 
>
> 2.30.2
>
>
> Regards,

-- 
	Philip Kaludercic on peregrine

Re: [DISCUSSION] "quick-help" popup for org-columns (column view)

[Sławomir Grochowski]

Philip Kaludercic <philipk@posteo.net> writes:

> Sławomir Grochowski <slawomir.grochowski@gmail.com> writes:
>
>> Philip Kaludercic <philipk@posteo.net> writes:
>>> I have pushed the changes to master.
>>
>> Thank you Philip for your help.  It works.
>>
>> But there is one more small thing. 
>> A message that is displayed in the minibuffer. 
>> It contains two pieces of information:
>>
>> (1)     command name
>>         Right now it's hardcoded. 
>>         We need to change the it from `help-quick-toggle' to
>>         `org-columns-help-quick-toggle'.
>>         How to do it? 
>>         Add another variable like `help-quick-use-map'?
>>         Maybe 'help-quick-command-name'?
>
> Instead of using substitute-command-keys, we could just use
> this-command, but that assumes that help-quick can always be toggled by
> the command that invokes it.

That's great idea. I tried with this code:

(message "Toggle display of quick-help buffer using %s."
         (propertize (key-description (this-command-keys)) 'face 'help-key-binding 'font-lock-face 'help-key-binding))

And it works perfectly. 

>> (2)     keybinding to the command name
>>         Just to modify message string. Add '\\<help-quick-use-map>'.
>>         To use other keymap.
>>         Change is in the diff below. 
>
> I don't see how this would work in general, at the very least it breaks
> the regular usage.
>
> Furthermore, I am not convinced we have to change anything here, since
> C-h C-q (the default binding for `help-quick-toggle') should also hide
> the buffer if one uses your command, or am I mistaken?

But I would like 'help-quick' for org-columns to be bind to other
keybinding: "?" not "C-h C-q".

Because now it's like this:

1. invoke the command using "?" keybinding:

(defun org-columns-help-quick-toggle ()
  (interactive)
  (let ((help-quick-sections org-columns-help-quick-sections)
        (help-quick-use-map org-columns-map))
    (help-quick-toggle)))

(org-defkey org-columns-map "?" #'org-columns-help-quick-toggle)

2. 'help-quick' for org-columns buffer will appear with the message:
"Toggle display of quick-help buffer using C-h C-q."

So this is misleading.
Because pressing 'C-h C-q' will close the buffer but pressing it again
will show 'help-quick' buffer and not 'help-quick' for org-columns buffer.

Therefore, I think that to use a different keybinding we need to modify
the code.
Or am I missing something?

-- 
Slawomir Grochowski

Re: [DISCUSSION] "quick-help" popup for org-columns (column view)

[Sławomir Grochowski]

Hi Philip, 

what's your opinion about this change?
I understand it's a low-level hack, but maybe you can advise on how to do it better? 

Sławomir Grochowski <slawomir.grochowski@gmail.com> writes:
> That's great idea. I tried with this code:
>
> (message "Toggle display of quick-help buffer using %s."
>          (propertize (key-description (this-command-keys)) 'face 'help-key-binding 'font-lock-face 'help-key-binding))
>
> And it works perfectly. 

> But I would like 'help-quick' for org-columns to be bind to other
> keybinding: "?" not "C-h C-q".
>
> Because now it's like this:
>
> 1. invoke the command using "?" keybinding:
>
> (defun org-columns-help-quick-toggle ()
>   (interactive)
>   (let ((help-quick-sections org-columns-help-quick-sections)
>         (help-quick-use-map org-columns-map))
>     (help-quick-toggle)))
>
> (org-defkey org-columns-map "?" #'org-columns-help-quick-toggle)
>
> 2. 'help-quick' for org-columns buffer will appear with the message:
> "Toggle display of quick-help buffer using C-h C-q."
>
> So this is misleading.
> Because pressing 'C-h C-q' will close the buffer but pressing it again
> will show 'help-quick' buffer and not 'help-quick' for org-columns buffer.
>
> Therefore, I think that to use a different keybinding we need to modify
> the code.
> Or am I missing something?

-- 
Slawomir Grochowski

Re: [DISCUSSION] "quick-help" popup for org-columns (column view)

[Eli Zaretskii]

> From: Sławomir Grochowski <slawomir.grochowski@gmail.com>
> Cc: yantar92@posteo.net, emacs-orgmode@gnu.org, emacs-devel@gnu.org,
>  philipk@posteo.net, stefankangas@gmail.com, larsi@gnus.org,
>  hmelman@gmail.com, info@protesilaos.com
> Date: Mon, 08 Apr 2024 09:38:40 +0200
> 
> > The idea here was that some other function could rebind
> > `help-quick-sections' dynamically.  That way you avoid the redundant
> > arguments (which would all have to be documented).
> 
> Is this really a good practice?
> Relying on global variables instead of passing variables as a parameters?

Emacs is full of such practices, so don't worry about that, it's quite
common (and considered good practice) in Emacs Lisp.

> Eli Zaretskii <eliz@gnu.org> writes:
> > In any case, we cannot change the signature of help-quick, since it's a
> > public function.
> 
> If I can't modify the function `help-quick' how can I make it work?

You write a new function with the signature you like and make
help-quick call it to do the actual job.  Where you want to use the
signature of the new function, you call it directly.

RE: [External] : Re: [DISCUSSION] "quick-help" popup for org-columns (column view)

[Sławomir Grochowski]

I have been using the https://github.com/justbur/emacs-which-key for a long time.
However, today I took a closer look at this package to see if it has
two features that I've found in 'quick-help' which I really like.

Those two features are:

1. option for popup to be persistent, sticky
It's a lifesaver for every new user to see permanently
available keybindings, as well as for every user who starts
use an unknown package.
'which-key' already has this feature implemented,
variable `which-key-persistent-popup'.

2. option to divide keybindings into groups
For example, with 'which-key' when I press 'C-h',
popup with 50 keybindings will appear on the screen.  
I'm completely overwhelmed by the amount of information.
Making any decision is very tiring and difficult.
Grouping will make it much easier to read and make a decision.
I don't see this functionality in 'which-key' but I found a topic on
Reddit https://www.reddit.com/r/emacs/comments/kxd9z4/grouped_bindings_in_whichkey
with repo link
https://github.com/loafofpiecrust/dotfiles/blob/main/emacs/.config/doom/custom/pretty-which-key.el
where this feature has been implemented.

Based on this information, I think it's worth waiting until 'which-key' is integrated.
And then implement the 'divide keybindings into groups' feature.

I'm not familiar with https://www.emacswiki.org/emacs/download/keysee.el
But I could try to answer some questions about 'which-key'.

Drew Adams <drew.adams@oracle.com> writes:

> 1. Doesn't which-key also provide the
> possibility (e.g., on-demand instead of
> by timer) to show all currently available
> bindings at top level, i.e., not on a
> prefix key)?  I thought it had added that
> feature at some point.
>
> If it doesn't, then that's another big
> difference ("critical", you say) from
> KeySee.

Yes, it's available with command `which-key-show-top-level'.

> 2. As for getting the completions in a
> buffer that you can access "persistently"
> (and, e.g., to search or edit):
>
> There should be a separate, more general
> feature for that: be able to "save" the
> current contents of `*Completions* (or
> another buffer displaying completions) to
> another buffer, regardless of what that
> completions buffer is showing.
>
> IOW, this shouldn't be only about _key_
> completions and descriptions as help.
>
> Icicles provides such a feature (as does
> Embark, IIUC).  Emacs should have it.  Hit
> a key, enter a destination buffer name (or
> just hit RET for a default name).

Yes, you can copy or even edit 'which-key' 'popup'.

> 3. Icicles can also show you complete help
> for key completions shown in *Completions*,
> in *Help*.  And likewise for any other
> kind of completions for which there's a
> help description.
>
> Showing help for completions is another
> general feature that Emacs should have.

I don't know if 'which-key' has this option.

-- 
Sławomir Grochowski