Adding a "quick-help" menu

Adding a "quick-help" menu

[Philip Kaludercic]

There is a fork of mg (MicroEmacs)[0] that binds C-h q to a command that
pops up a buffer with these contents:

--8<---------------cut here---------------start------------->8---
FILE             BUFFER          WINDOW           MARK/KILL       MISC
C-x C-c  exit    C-x C-k close   C-0   only other C-space  mark   C-_ undo
C-x C-f  find    C-x k   other   C-1   only this  C-w      wipe   C-s search
C-x C-s  save    C-x C-b list    C-2   split two  C-k      close  C-r r-search
C-x s    all     C-x b   switch  C-x ^ enlarge    C-y      yank   M-% replace
C-x i    insert  C-x g   goto ln C-x o other win  C-x C-x  swap   M-q reformat
______________________________________________________________________________
C-h q  toggle quick help  |  C-h t  show tutorial  |  C-h b  show key bindings
--8<---------------cut here---------------end--------------->8---

I notice that in GNU Emacs C-h q is bound to `help-quit', which does
nothing if you are not in the help command loop.  Would having a
"quick-help" menu along these lines for common operations make sense for
GNU Emacs as well?

[0] https://github.com/troglobit/mg

Re: Adding a "quick-help" menu

[Sean Whitton]

Hello,

On Fri 16 Sep 2022 at 03:43PM GMT, Philip Kaludercic wrote:

> There is a fork of mg (MicroEmacs)[0] that binds C-h q to a command that
> pops up a buffer with these contents:
>
> FILE             BUFFER          WINDOW           MARK/KILL       MISC
> C-x C-c  exit    C-x C-k close   C-0   only other C-space  mark   C-_ undo
> C-x C-f  find    C-x k   other   C-1   only this  C-w      wipe   C-s search
> C-x C-s  save    C-x C-b list    C-2   split two  C-k      close  C-r r-search
> C-x s    all     C-x b   switch  C-x ^ enlarge    C-y      yank   M-% replace
> C-x i    insert  C-x g   goto ln C-x o other win  C-x C-x  swap   M-q reformat
> ______________________________________________________________________________
> C-h q  toggle quick help  |  C-h t  show tutorial  |  C-h b  show key bindings
>
> I notice that in GNU Emacs C-h q is bound to `help-quit', which does
> nothing if you are not in the help command loop.  Would having a
> "quick-help" menu along these lines for common operations make sense for
> GNU Emacs as well?

I guess we should ask some newbies.

-- 
Sean Whitton

Re: Adding a "quick-help" menu

[Stefan Kangas]

Philip Kaludercic <philipk@posteo.net> writes:

> Would having a "quick-help" menu along these lines for common
> operations make sense for GNU Emacs as well?

See also `which-keys', a package that I think is useful enough that we
should distribute and enable it by default.

Re: Adding a "quick-help" menu

[Philip Kaludercic]

Stefan Kangas <stefankangas@gmail.com> writes:

> Philip Kaludercic <philipk@posteo.net> writes:
>
>> Would having a "quick-help" menu along these lines for common
>> operations make sense for GNU Emacs as well?
>
> See also `which-keys', a package that I think is useful enough that we
> should distribute and enable it by default.

I hear this a lot, but it seems to me that the "feel" (for lack of a
better word) for which-keys is different from everything else in Emacs
by default.  Window management can be fragile enough to begin with, but
having a mode enabled by default that disturbs the current window layout
and visible parts of the buffer whenever a user isn't quick enough -- in
other words does nothing -- is something I don't think should be the
case by default.

Re: Adding a "quick-help" menu

[Sławomir Grochowski]

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

https://github.com/justbur/emacs-which-key features helps a lot in user
interface.
Help users to feel better, more comfortable and prevent from being lost.
And it's kind of similar behavior to -> pressing the <tab> key for
completion in 'minibuffer commands' like M-x, find-file, apropos etc.
To make it simple it should be limited to only a minibuffer similar to the
<tab> completion system.
Because which-key package allows you to display it in another buffer or
frame. But that would be too much complexity.

On Fri, 16 Sept 2022 at 18:50, Philip Kaludercic <philipk@posteo.net> wrote:

> Stefan Kangas <stefankangas@gmail.com> writes:
>
> > Philip Kaludercic <philipk@posteo.net> writes:
> >
> >> Would having a "quick-help" menu along these lines for common
> >> operations make sense for GNU Emacs as well?
> >
> > See also `which-keys', a package that I think is useful enough that we
> > should distribute and enable it by default.
>
> I hear this a lot, but it seems to me that the "feel" (for lack of a
> better word) for which-keys is different from everything else in Emacs
> by default.  Window management can be fragile enough to begin with, but
> having a mode enabled by default that disturbs the current window layout
> and visible parts of the buffer whenever a user isn't quick enough -- in
> other words does nothing -- is something I don't think should be the
> case by default.
>
>

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

Re: Adding a "quick-help" menu

[Stefan Kangas]

Philip Kaludercic <philipk@posteo.net> writes:

> I hear this a lot, but it seems to me that the "feel" (for lack of a
> better word) for which-keys is different from everything else in Emacs
> by default.

I disagree, obviously.  But it would be useful if others here could give
it a spin to see what they think.

To try it out, it should be enough to evaluate this (untested):

    (progn
      (package-install 'which-key)
      (which-key-mode 1))

Then type something like `C-x' and wait.

> Window management can be fragile enough to begin with, but
> having a mode enabled by default that disturbs the current window layout
> and visible parts of the buffer whenever a user isn't quick enough -- in
> other words does nothing -- is something I don't think should be the
> case by default.

I'm not sure if you are referring to any real issues (a.k.a. bugs), or
if this just a general concern.  If the popup is too jarring, we could
experiment with a longer delay before it pops up.

FWIW, in my many years of using it, I've never seen any issues with it.
It always leaves my windows just as they were when it goes away.  Then
again, I don't use the highly advanced customizations that some other
people do.

Re: Adding a "quick-help" menu

[Philip Kaludercic]

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

> https://github.com/justbur/emacs-which-key features helps a lot in user
> interface.
> Help users to feel better, more comfortable and prevent from being lost.
> And it's kind of similar behavior to -> pressing the <tab> key for
> completion in 'minibuffer commands' like M-x, find-file, apropos etc.

Yes, but just like there is a difference between auto-completion and
tab-completion, there is a difference to be considered here.

Again, I don't think there is anything in Emacs by default that relies
on non-input the way which-key does.  One reason I dislike this is
because I've seen how some people use `which-key-mode' in person, just
waiting for the menu to (fragile) pop up, to skim through the columns to
find what they are looking for.  By comparison, I think that C-h and
isearch/occur/etc. is more idiomatic.

That being said, my proposal is much more modest, and has more to do
with Nano's default help bar at the bottom of the screen.

> To make it simple it should be limited to only a minibuffer similar to the
> <tab> completion system.
> Because which-key package allows you to display it in another buffer or
> frame. But that would be too much complexity.

Why would it be?

Re: Adding a "quick-help" menu

[Philip Kaludercic]

Stefan Kangas <stefankangas@gmail.com> writes:

> Philip Kaludercic <philipk@posteo.net> writes:
>
>> I hear this a lot, but it seems to me that the "feel" (for lack of a
>> better word) for which-keys is different from everything else in Emacs
>> by default.
>
> I disagree, obviously.  But it would be useful if others here could give
> it a spin to see what they think.
>
> To try it out, it should be enough to evaluate this (untested):
>
>     (progn
>       (package-install 'which-key)
>       (which-key-mode 1))
>
> Then type something like `C-x' and wait.

IMO it is too much information for the minibuffer.

>> Window management can be fragile enough to begin with, but
>> having a mode enabled by default that disturbs the current window layout
>> and visible parts of the buffer whenever a user isn't quick enough -- in
>> other words does nothing -- is something I don't think should be the
>> case by default.
>
> I'm not sure if you are referring to any real issues (a.k.a. bugs), or
> if this just a general concern.  If the popup is too jarring, we could
> experiment with a longer delay before it pops up.
>
> FWIW, in my many years of using it, I've never seen any issues with it.
> It always leaves my windows just as they were when it goes away.  Then
> again, I don't use the highly advanced customizations that some other
> people do.

No, I don't think it is a bug.  I went into more detail what I think the
issues are in my sibling response (<87mtaz44ka.fsf@posteo.net>).

RE: [External] : Re: Adding a "quick-help" menu

[Drew Adams]

> > I hear this a lot, but it seems to me that the "feel" (for lack of a
> > better word) for which-keys is different from everything else in Emacs
> > by default.
> 
> I disagree, obviously.  But it would be useful if others here could give
> it a spin to see what they think.  To try it out...
>  (package-install 'which-key)
>  (which-key-mode 1)
> Then type something like `C-x' and wait.
> 
> > Window management can be fragile enough to begin with, but
> > having a mode enabled by default that disturbs the current window
> > layout and visible parts of the buffer whenever a user isn't
> > quick enough -- in other words does nothing -- is something I
> > don't think should be the case by default.
> 
> I'm not sure if you are referring to any real issues (a.k.a. bugs), or
> if this just a general concern.  If the popup is too jarring, we could
> experiment with a longer delay before it pops up.
> 
> FWIW, in my many years of using it, I've never seen any issues with it.
> It always leaves my windows just as they were when it goes away.  Then
> again, I don't use the highly advanced customizations that some other
> people do.

FWIW, here's an alternative:

https://www.emacswiki.org/emacs/KeySee

Works also at top level, on demand (i.e., not
just after a prefix key).

Can show the help anytime, on demand, or
automatically after a prefix-key with delay.

Go back up, down, all around - navigate the
whole hierarchy: all currently possible keys.

Can also navigate the menu-bar tree (menus).

Can sort completion candidates on the fly:
prefix-keys first, local keys first, by
command name alphabetically.

Can complete against keys, command names,
or both.

Can choose (option) which keymaps to enable
top-level completion for.
___

Requires also `sortie.el', for the sorting:

https://www.emacswiki.org/emacs/Sortie

RE: [External] : Re: Adding a "quick-help" menu

[Drew Adams]

> > Then type something like `C-x' and wait.
> 
> IMO it is too much information for the minibuffer.

`keysee.el' uses buffer *Completions*.

Re: Adding a "quick-help" menu

[Stefan Monnier]

> I'm not sure if you are referring to any real issues (a.k.a. bugs), or
> if this just a general concern.  If the popup is too jarring, we could
> experiment with a longer delay before it pops up.
>
> FWIW, in my many years of using it, I've never seen any issues with it.
> It always leaves my windows just as they were when it goes away.  Then
> again, I don't use the highly advanced customizations that some other
> people do.

I have no clear opinion on whether we should enable it or not, but FWIW

I just tried it in my config and when after I press `C-x` in my
minibuffer-only frame, Emacs gets into a busy-loop eating 99% of the CPU
(and growing its heap) until I finally hit another key.
Probably easy to fix (and I didn't notice anything fishy going on with
my setup even though it tends to trip up many window-creating packages).


        Stefan

Re: Adding a "quick-help" menu

[Philip Kaludercic]

Philip Kaludercic <philipk@posteo.net> writes:

> There is a fork of mg (MicroEmacs)[0] that binds C-h q to a command that
> pops up a buffer with these contents:
>
> FILE             BUFFER          WINDOW           MARK/KILL       MISC
> C-x C-c  exit    C-x C-k close   C-0   only other C-space  mark   C-_ undo
> C-x C-f  find    C-x k   other   C-1   only this  C-w      wipe   C-s search
> C-x C-s  save    C-x C-b list    C-2   split two  C-k      close  C-r r-search
> C-x s    all     C-x b   switch  C-x ^ enlarge    C-y      yank   M-% replace
> C-x i    insert  C-x g   goto ln C-x o other win  C-x C-x  swap   M-q reformat
> ______________________________________________________________________________
> C-h q  toggle quick help  |  C-h t  show tutorial  |  C-h b  show key bindings
>
> I notice that in GNU Emacs C-h q is bound to `help-quit', which does
> nothing if you are not in the help command loop.  Would having a
> "quick-help" menu along these lines for common operations make sense for
> GNU Emacs as well?
>
> [0] https://github.com/troglobit/mg

Here is a quick sketch of how this could look like:

--8<---------------cut here---------------start------------->8---
(defvar help-quick-sections
  '(("... FILE"
     (save-buffers-kill-terminal . "exit")
     (find-file . "find")
     (save-buffer . "save")
     (save-some-buffers . "all")
     (insert-file . "insert"))
    ("... BUFFER"
     (kill-buffer . "kill")
     (other-window . "other")
     (list-buffers . "list")
     (switch-to-buffer . "switch")
     (goto-line . "goto line"))
    ("... WINDOW"
     (delete-window . "only other")
     (delete-other-windows . "only this")
     (split-window-below . "split vert.")
     (split-window-right . "split horiz.")
     (enlarge-window . "enlarge")
     (other-window . "other"))
    ("MARK/KILL"
     (set-mark-command . "mark")
     (kill-region . "wipe")
     (kill-line . "kill")
     (yank . "yank")
     (exchange-point-and-mark . "swap"))
    ("MISC"
     (undo . "undo")
     (isearch-forward . "search")
     (isearch-backward . "rev-search")
     (query-replace . "replace")
     (fill-paragraph . "reformat"))))z

;; Inspired by a mg fork (https://github.com/troglobit/mg)
(defun help-quick ()
  "Display a quick-help buffer."
  (interactive)
  (with-current-buffer (get-buffer-create "*Quick Help*")
    (let ((inhibit-read-only t) blocks)
      (dolist (section help-quick-sections)
        (let ((max-key-len 0) (max-cmd-len 0) keys)
          (dolist (ent (reverse (cdr section)))
            (let* ((bind (where-is-internal (car ent) nil t))
                   (key (if bind
                            (propertize (key-description bind)
                                        'face 'help-key-binding)
                          " -/-")))
              (setq max-cmd-len (max (length (cdr ent))
                                     max-cmd-len)
                    max-key-len (max (length key)
                                     max-key-len))
              (push (cons key (cdr ent)) keys)))
          (let ((fmt (format "%%-%ds %%-%ds   " max-key-len max-cmd-len)))
            (push `(,(propertize
                      (concat
                       (car section)
                       (make-string (- (+ max-key-len 1 max-cmd-len 3)
                                       (length (car section)))
                                    ?\s))
                      'face 'shortdoc-heading)
                    ,@(mapcar
                       (lambda (ent)
                         (format fmt (car ent) (cdr ent)))
                       keys))
                  blocks))))

      (erase-buffer)
      (dolist (block (nreverse blocks))
        (when (> (+ (length (car block))
                    (current-column))
                 (window-width))
          (goto-char (point-max))
          (newline 2))
        (save-excursion
          (insert-rectangle block))
        (end-of-line))
      (delete-trailing-whitespace))

    ;; Display the buffer at the bottom of the page and shrink it
    ;; immediately.
    (help-mode)
    (read-only-mode t)
    (let ((win (display-buffer-at-bottom (current-buffer) '())))
      (fit-window-to-buffer win)
      (select-window win)
      (goto-char (point-min)))))
--8<---------------cut here---------------end--------------->8---

Re: Adding a "quick-help" menu

[Po Lu]

Philip Kaludercic <philipk@posteo.net> writes:

> There is a fork of mg (MicroEmacs)[0] that binds C-h q to a command that
> pops up a buffer with these contents:
>
> FILE             BUFFER          WINDOW           MARK/KILL       MISC
> C-x C-c  exit    C-x C-k close   C-0   only other C-space  mark   C-_ undo
> C-x C-f  find    C-x k   other   C-1   only this  C-w      wipe   C-s search
> C-x C-s  save    C-x C-b list    C-2   split two  C-k      close  C-r r-search
> C-x s    all     C-x b   switch  C-x ^ enlarge    C-y      yank   M-% replace
> C-x i    insert  C-x g   goto ln C-x o other win  C-x C-x  swap   M-q reformat
> ______________________________________________________________________________
> C-h q  toggle quick help  |  C-h t  show tutorial  |  C-h b  show key bindings
>
> I notice that in GNU Emacs C-h q is bound to `help-quit', which does
> nothing if you are not in the help command loop.  Would having a
> "quick-help" menu along these lines for common operations make sense for
> GNU Emacs as well?

Why not make it part of the menu bar?

Re: Adding a "quick-help" menu

[Po Lu]

Stefan Kangas <stefankangas@gmail.com> writes:

> I disagree, obviously.  But it would be useful if others here could give
> it a spin to see what they think.
>
> To try it out, it should be enough to evaluate this (untested):
>
>     (progn
>       (package-install 'which-key)
>       (which-key-mode 1))
>
> Then type something like `C-x' and wait.

The pop up temporarily interferes with the window configuration, which
is annoying when you are reading something, type "C-x", and wait while
thinking.

Re: Adding a "quick-help" menu

[Stefan Kangas]

Po Lu <luangruo@yahoo.com> writes:

> Why not make it part of the menu bar?

FWIW, I don't see how the menu bar could be a replacement.

Note also that the menu bar is not very popular among users: 74.3 % of
the 7300 users that replied to the Emacs Survey in 2020 disabled it.[1]
It'd be interesting to know how many of those that didn't disable it use
it more than occasionally, but I don't think that data was collected.

Footnotes:
[1]  https://emacssurvey.org/2020/if-you-use-emacs-gui-do-you-disable-any-of-the-graphical-elements.svg

Re: Adding a "quick-help" menu

[Stefan Monnier]

> Note also that the menu bar is not very popular among users: 74.3 % of
> the 7300 users that replied to the Emacs Survey in 2020 disabled it.[1]
> It'd be interesting to know how many of those that didn't disable it use
> it more than occasionally, but I don't think that data was collected.

FWIW, I disable it (to save valuable vertical screen real estate), but
I do use it on a fairly regular basis (at least once a week).


        Stefan

Re: Adding a "quick-help" menu

[Visuwesh]

[வெள்ளி செப்டம்பர் 16, 2022] Stefan Monnier wrote:

>> Note also that the menu bar is not very popular among users: 74.3 % of
>> the 7300 users that replied to the Emacs Survey in 2020 disabled it.[1]
>> It'd be interesting to know how many of those that didn't disable it use
>> it more than occasionally, but I don't think that data was collected.
>
> FWIW, I disable it (to save valuable vertical screen real estate), but
> I do use it on a fairly regular basis (at least once a week).

+1.  I disable the menubar but I do use it either via LaCarte or by
activating the mode-line mode button.

Re: Adding a "quick-help" menu

[Po Lu]

Stefan Kangas <stefankangas@gmail.com> writes:

> FWIW, I don't see how the menu bar could be a replacement.

Why not?

Most computer users immediately look in the menu labeled "Help" for
help.

> Note also that the menu bar is not very popular among users: 74.3 % of
> the 7300 users that replied to the Emacs Survey in 2020 disabled it.[1]
> It'd be interesting to know how many of those that didn't disable it use
> it more than occasionally, but I don't think that data was collected.

If they turn off the features that are supposed to help them, what do
you think a "quick help" menu will do?  And why won't it be turned off
as well?

Besides, if they turn off the menu bar and splash screen at startup, how
will we impart the existence of the "quick help" menu to them?

Re: Adding a "quick-help" menu

[Po Lu]

Stefan Monnier <monnier@iro.umontreal.ca> writes:

> FWIW, I disable it (to save valuable vertical screen real estate), but
> I do use it on a fairly regular basis (at least once a week).

Also, FTR, I keep the menu bar enabled and do use it regularly.  Such as
in message-mode, where I can never remember the keys to send a message
at a specific time.

Re: Adding a "quick-help" menu

[Stefan Kangas]

Po Lu <luangruo@yahoo.com> writes:

> Stefan Kangas <stefankangas@gmail.com> writes:
>
>> FWIW, I don't see how the menu bar could be a replacement.
>
> Why not?

From my point of view, you might as well ask why we can't replace
`C-h C-h' with the menu bar.  These are just very different features,
and I don't think they should be conflated.

> If they turn off the features that are supposed to help them, what do
> you think a "quick help" menu will do?  And why won't it be turned off
> as well?

Do you mean to unbind the key `C-h q'?  I guess that some users might do
that, sure.  But we don't have much data on how common something like
that would be.  On the other hand, we do know a bit about how often
users turn off the menu bar.

Re: Adding a "quick-help" menu

[Po Lu]

Stefan Kangas <stefankangas@gmail.com> writes:

> From my point of view, you might as well ask why we can't replace
> `C-h C-h' with the menu bar.  These are just very different features,
> and I don't think they should be conflated.

Both provide a "Help" menu, so they are very similar.

> Do you mean to unbind the key `C-h q'?

No, to disable whatever informs them of the existence of "C-h q".

Re: Adding a "quick-help" menu

[Philip Kaludercic]

Po Lu <luangruo@yahoo.com> writes:

> Philip Kaludercic <philipk@posteo.net> writes:
>
>> There is a fork of mg (MicroEmacs)[0] that binds C-h q to a command that
>> pops up a buffer with these contents:
>>
>> FILE             BUFFER          WINDOW           MARK/KILL       MISC
>> C-x C-c  exit    C-x C-k close   C-0   only other C-space  mark   C-_ undo
>> C-x C-f  find    C-x k   other   C-1   only this  C-w      wipe   C-s search
>> C-x C-s  save    C-x C-b list    C-2   split two  C-k      close  C-r r-search
>> C-x s    all     C-x b   switch  C-x ^ enlarge    C-y      yank   M-% replace
>> C-x i    insert  C-x g   goto ln C-x o other win  C-x C-x  swap   M-q reformat
>> ______________________________________________________________________________
>> C-h q  toggle quick help  |  C-h t  show tutorial  |  C-h b  show key bindings
>>
>> I notice that in GNU Emacs C-h q is bound to `help-quit', which does
>> nothing if you are not in the help command loop.  Would having a
>> "quick-help" menu along these lines for common operations make sense for
>> GNU Emacs as well?
>
> Why not make it part of the menu bar?

I remember when I started using Emacs, I had difficulties orienting
myself around the menu bar, considering how many menus and submenus
there were.  Sure, you can find those items you expect to be in a
familiar place coming from other CUA software (File -> Save, Edit ->
Undo) -- though how commonplace this is nowadays is also a question.

But inherently there is no reason not to do both.  I was just suggestion
C-h q because it is a prominent and easy-to-use key that has to usage
outside of the *Metahelp* buffer.

Re: Adding a "quick-help" menu

[Gregor Zattler]

Hi Philip, emacs developers,
* Philip Kaludercic <philipk@posteo.net> [2022-09-16; 17:22 GMT]:
> Yes, but just like there is a difference between auto-completion and
> tab-completion, there is a difference to be considered here.

for me the main difference to all other help facilities is,
that there is zero cognitive burden: It only pops up when I
hit a prefix key and then don't know what to do.

It specifically shows help to this prefix key, I do not have
to move the mouse, I do not have to look for a symbol to
click or a menu entry which might be related.

I do not have to know how to bury or kill it, it does not
litter my buffer list with jet another buried buffer, it
does not permanently change my window configuration.

I think these are great features especially for newbies.

> Again, I don't think there is anything in Emacs by default that relies
> on non-input the way which-key does.  One reason I dislike this is
> because I've seen how some people use `which-key-mode' in person, just
> waiting for the menu to (fragile) pop up, to skim through the columns to
> find what they are looking for.  By comparison, I think that C-h and
> isearch/occur/etc. is more idiomatic.

But much more involved to use and they leave traces as
which-key does not.

> That being said, my proposal is much more modest, and has more to do
> with Nano's default help bar at the bottom of the screen.

My praise of which-key is in no way directed against your
proposal of a screen full of essential functions.


Ciao; Gregor
--
 -... --- .-. . -.. ..--.. ...-.-

Re: Adding a "quick-help" menu

[Philip Kaludercic]

Gregor Zattler <telegraph@gmx.net> writes:

> Hi Philip, emacs developers,
> * Philip Kaludercic <philipk@posteo.net> [2022-09-16; 17:22 GMT]:
>> Yes, but just like there is a difference between auto-completion and
>> tab-completion, there is a difference to be considered here.
>
> for me the main difference to all other help facilities is,
> that there is zero cognitive burden: It only pops up when I
> hit a prefix key and then don't know what to do.

What kind of prefix keys are we talking about?  Could you give me a
recent example for where which-key was useful to you (or anyone else)?

> It specifically shows help to this prefix key, I do not have
> to move the mouse, I do not have to look for a symbol to
> click or a menu entry which might be related.

But none of this is necessary when you press C-h.  The only disadvantage
is that you would have to repeat the prefix, but I think that could be
changed.

> I do not have to know how to bury or kill it, it does not
> litter my buffer list with jet another buried buffer, it
> does not permanently change my window configuration.

Do you meant the *Help* buffer?

> I think these are great features especially for newbies.
>
>> Again, I don't think there is anything in Emacs by default that relies
>> on non-input the way which-key does.  One reason I dislike this is
>> because I've seen how some people use `which-key-mode' in person, just
>> waiting for the menu to (fragile) pop up, to skim through the columns to
>> find what they are looking for.  By comparison, I think that C-h and
>> isearch/occur/etc. is more idiomatic.
>
> But much more involved to use and they leave traces as
> which-key does not.

I personally think this is an advantage (though I wouldn't put it the
way you did).  To me `which-key' -- the way it is configured by default
-- seems fragile and unreliable.  A help buffer is just-another-buffer
and doesn't appear to be an exception to the rest of how Emacs works.

>> That being said, my proposal is much more modest, and has more to do
>> with Nano's default help bar at the bottom of the screen.
>
> My praise of which-key is in no way directed against your
> proposal of a screen full of essential functions.

Don't worry, I didn't take it that way, I just wanted to return to the
initial topic of the thread.

which-key (was: Adding a "quick-help" menu)

[Stefan Monnier]

>> Yes, but just like there is a difference between auto-completion and
>> tab-completion, there is a difference to be considered here.
> for me the main difference to all other help facilities is,
> that there is zero cognitive burden: It only pops up when I
> hit a prefix key and then don't know what to do.

BTW, AFAICT there are fundamentally two differences between the `C-h`
trick and `which-key-mode`:

A) `C-h` needs an explicit user action, rather than just waiting
   a shot time.  Both options have their advantages.
B) `C-h` displays the result in a less sophisticated way than
   `which-key`.

Regarding (A), in order to avoid the potential occasional annoyance of
the which-key popup, which also solving the discoverability problem of
`C-h`, I guess we should simply change the "echo keystrokes"
functionality so instead of just displaying "C-x-" it could display
something like "C-x-  [Hit C-h for help]".

And regarding (B), it seems to be a small matter of merging the two
codebases so that `C-h` and `which-key` get the same display.


        Stefan

Re: Adding a "quick-help" menu

[Philip Kaludercic]

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

Philip Kaludercic <philipk@posteo.net> writes:

> Philip Kaludercic <philipk@posteo.net> writes:
>
>> There is a fork of mg (MicroEmacs)[0] that binds C-h q to a command that
>> pops up a buffer with these contents:
>>
>> FILE             BUFFER          WINDOW           MARK/KILL       MISC
>> C-x C-c  exit    C-x C-k close   C-0   only other C-space  mark   C-_ undo
>> C-x C-f  find    C-x k   other   C-1   only this  C-w      wipe   C-s search
>> C-x C-s  save    C-x C-b list    C-2   split two  C-k      close  C-r r-search
>> C-x s    all     C-x b   switch  C-x ^ enlarge    C-y      yank   M-% replace
>> C-x i    insert  C-x g   goto ln C-x o other win  C-x C-x  swap   M-q reformat
>> ______________________________________________________________________________
>> C-h q  toggle quick help  |  C-h t  show tutorial  |  C-h b  show key bindings
>>
>> I notice that in GNU Emacs C-h q is bound to `help-quit', which does
>> nothing if you are not in the help command loop.  Would having a
>> "quick-help" menu along these lines for common operations make sense for
>> GNU Emacs as well?
>>
>> [0] https://github.com/troglobit/mg
>
> Here is a quick sketch of how this could look like:

I've further refined the sketch and how have a patch:


[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #2: 0001-Add-a-quick-help-menu.patch --]
[-- Type: text/x-patch, Size: 5194 bytes --]

From d0899b748b0047e1d1c773b06076faeba2535fee Mon Sep 17 00:00:00 2001
From: Philip Kaludercic <philipk@posteo.net>
Date: Sat, 17 Sep 2022 16:52:01 +0200
Subject: [PATCH] Add a quick-help menu

* lisp/help.el (help-map): Bind 'help-quit-or-quick' instead of 'help-quit'
(help-quick-sections): Add variable.
(help-quick): Add main command.
(help-quit-or-quick): Add auxiliary command.
---
 lisp/help.el | 109 ++++++++++++++++++++++++++++++++++++++++++++++++++-
 1 file changed, 108 insertions(+), 1 deletion(-)

diff --git a/lisp/help.el b/lisp/help.el
index 92b87cf799..089db8c2dd 100644
--- a/lisp/help.el
+++ b/lisp/help.el
@@ -112,7 +112,7 @@ help-map
     (define-key map "v" 'describe-variable)
     (define-key map "w" 'where-is)
     (define-key map "x" 'describe-command)
-    (define-key map "q" 'help-quit)
+    (define-key map "q" 'help-quit-or-quick)
     map)
   "Keymap for characters following the Help key.")
 
@@ -125,11 +125,118 @@ global-map
 (defvar help-button-cache nil)
 
 \f
+
+(defvar help-quick-sections
+  '(("FILE"
+     (save-buffers-kill-terminal . "exit")
+     (find-file . "find")
+     (write-file . "write")
+     (save-buffer . "save")
+     (save-some-buffers . "all"))
+    ("BUFFER"
+     (kill-buffer . "kill")
+     (list-buffers . "list")
+     (switch-to-buffer . "switch")
+     (goto-line . "goto line")
+     (read-only-mode . "read only"))
+    ("WINDOW"
+     (delete-window . "only other")
+     (delete-other-windows . "only this")
+     (split-window-below . "split vert.")
+     (split-window-right . "split horiz.")
+     (other-window . "other"))
+    ("MARK/KILL"
+     (set-mark-command . "mark")
+     (kill-region . "wipe")
+     (kill-line . "kill")
+     (yank . "yank")
+     (exchange-point-and-mark . "swap"))
+    ("PROJECT"
+     (project-switch-project . "switch")
+     (project-find-file . "find file")
+     (project-find-regexp . "search")
+     (project-query-replace-regexp . "replace")
+     (project-compile . "compile"))
+    ("MISC"
+     (undo . "undo")
+     (isearch-forward . "search")
+     (isearch-backward . "rev-search")
+     (query-replace . "replace")
+     (fill-paragraph . "reformat"))))
+
+;; Inspired by a mg fork (https://github.com/troglobit/mg)
+(defun help-quick ()
+  "Display a quick-help buffer."
+  (interactive)
+  (with-current-buffer (get-buffer-create "*Quick Help*")
+    (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)
+        (let ((max-key-len 0) (max-cmd-len 0) keys)
+          (dolist (ent (reverse (cdr section)))
+            (let* ((bind (where-is-internal (car ent) nil t))
+                   (key (if bind
+                            (propertize
+                             (key-description bind)
+                             'face 'help-key-binding)
+                          (propertize "N.B." 'face 'error))))
+              (setq max-cmd-len (max (length (cdr ent)) max-cmd-len)
+                    max-key-len (max (length key) max-key-len))
+              (push (cons key (cdr ent)) keys)))
+          (let ((fmt (format "%%-%ds %%-%ds%s" max-key-len max-cmd-len
+                             (make-string padding ?\s)))
+                (width (+ max-key-len 1 max-cmd-len padding)))
+            (push `(,width
+                    ,(propertize
+                      (concat
+                       (car section)
+                       (make-string (- width (length (car section))) ?\s))
+                      'face 'bold)
+                    ,@(mapcar (lambda (ent)
+                                (format fmt (car ent) (cdr ent)))
+                              keys))
+                  blocks))))
+
+      ;; Insert each rectangle in order until they don't fit into the
+      ;; frame any more, in which case the next sections are inserted
+      ;; in a new "line".
+      (erase-buffer)
+      (dolist (block (nreverse blocks))
+        (when (> (+ (car block) (current-column)) (frame-width))
+          (goto-char (point-max))
+          (newline 2))
+        (save-excursion
+          (insert-rectangle (cdr block)))
+        (end-of-line))
+      (delete-trailing-whitespace))
+
+    ;; Display the buffer at the bottom of the page and shrink it
+    ;; immediately.
+    (help-mode)
+    (with-selected-window (display-buffer-at-bottom (current-buffer) '())
+      (fit-window-to-buffer))
+    (message
+     (substitute-command-keys "Toggle the quick help buffer using \\[help-quit-or-quick]."))))
+
 (defun help-quit ()
   "Just exit from the Help command's command loop."
   (interactive)
   nil)
 
+(defun help-quit-or-quick ()
+  "Call `help-quit' or  `help-quick' depending on the context."
+  (interactive)
+  (cond
+   (help-buffer-under-preparation
+    ;; FIXME: There should be a better way to detect if we are in the
+    ;;        help command loop.
+    (help-quit))
+   ((and-let* ((window (get-buffer-window "*Quick Help*")))
+      (quit-window t window)))
+   ((help-quick))))
+
 (defvar help-return-method nil
   "What to do to \"exit\" the help buffer.
 This is a list
-- 
2.37.3


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


Next to the above sections this patch also includes a few commands for
project management.  Perhaps there are a few more ideas on what could be
added?

RE: [External] : Re: Adding a "quick-help" menu

[Drew Adams]

> I remember when I started using Emacs, I had
> difficulties orienting myself around the menu bar,
> considering how many menus and submenus there were.

Is this specific to Emacs or in the nature of menus?

Particularly mouse driven access, which gives
you only a local view of the menu hierarchy.
It's not easy to find something inside some menu
somewhere (which menu? which submenu(s)? what
might the menus be called?).

With keyboard access to the same menu hierarchy
things can change.  La Carte demonstrates this.

It gives you both a local view and a global view.
You can match multiple menu levels the same way
you can match multiple directory levels, with a
level-separator string (">" by default).

And especially if you also have progressive
completion, which lets you show any given level 
immediately, then show another given level
immediately, go back, up, down, sideways.
Icicles demonstrates this.

Maybe other completion frameworks offer something
similar now; dunno.  But vanilla Emacs doesn't,
to my knowledge.  `completion-styles' don't help
here.

`C-h f':

lacarte-execute-menu-command is an interactive
 compiled Lisp function in 'lacarte.el'.

(lacarte-execute-menu-command MAPS)

Execute a menu-bar menu command.
Type a menu item.  Completion is available.

A prefix argument controls which menus are available:

* None: current major mode, global, and minor-mode keymaps.
* Positive (including plain `C-u'): current major mode keymap.
* Zero (e.g., `C-0'): current global keymap.
* Negative (e.g., `C--'): current minor mode keymaps.

> Sure, you can find those items you expect to be in a
> familiar place coming from other CUA software
> (File -> Save, Edit -> Undo)

Being able to match alternative names using
progressive completion or regexp completion
helps.  Emacs has generally tried to use more
common terminology (e.g. "Paste") in menus, but
it still helps to match synonyms.

https://www.emacswiki.org/emacs/LaCarte

https://www.emacswiki.org/emacs/Icicles_-_Nutshell_View#ProgressiveCompletion

RE: [External] : Re: Adding a "quick-help" menu

[Drew Adams]

> It only pops up when I hit a prefix key and then
> don't know what to do.

Yes, +1 for this possibility.  Though `C-h' after
a prefix key is similar.

But the same "What keys can I use in the current
context, and what do they do?" question can arise
at top level.  It's not just about prefix keys.

And it's good to have the choice of whether to
have such stuff pop up automatically (after a
delay) or to just hit a key anytime to pop it up
_on demand_.  Especially important for top-level.

`keysee.el' lets you do these things (top-level,
on-demand or automatic).  Maybe `which-key' lets
you do them now also; dunno (it didn't used to,
at least).

[Icicles invented key completion, years before
`which-key'.  `keysee.el' is a reduced version
of Icicles key completion.  Same thing, but
without progressive completion and other
completion enhancements.]

> It specifically shows help to this prefix key, I do not have
> to move the mouse, I do not have to look for a symbol to
> click or a menu entry which might be related.

`C-h' after a prefix key does that also.  E.g.,
`C-x C-h'.  Not enough Emacs users are familiar
with this feature, I expect.

(But after seeing the help you then need to hit
the prefix key(s) again, to use them.  E.g,
`C-x 4 C-h', then `C-x 4 f' or whatever.  IOW,
help is separated from use.  Pros & cons...)

Stefan's suggestion is good: "instead of just
displaying "C-x-" it could display something
like "C-x- [Hit C-h for help]".

A guess is that we might have done that long
ago, but `C-h' after some prefix keys didn't
work.

> I do not have to know how to bury or kill it, it does not
> litter my buffer list with jet another buried buffer, it
> does not permanently change my window configuration.

Seriously?  `C-x 1' and `C-x 0' are among the
first things every Emacs user learns, no?  And
if the help is provided in a standard buffer,
such as `*Help*' or `*Completions*', then Emacs
already pretty much caters to user expectations
of removing the window easily.

> I think these are great features especially for newbies.

Agreed.

https://www.emacswiki.org/emacs/EmacsNewbieWithIcicles#PossibleKeyBindings

> > Again, I don't think there is anything in Emacs by
> > default that relies on non-input the way which-key
> > does.  One reason I dislike this is because I've
> > seen how some people use `which-key-mode' in person,
> > just waiting for the menu to (fragile) pop up, to
> > skim through the columns to find what they are
> > looking for.  By comparison, I think that C-h and
> > isearch/occur/etc. is more idiomatic.

I agree.  It's important to have the choice of
using key completion - or getting help on what
keys are currently available - on demand, and
not just after a delay.

> But much more involved to use and they leave traces as
> which-key does not.

Traces?  Is this again about removing a help
window such as `*Help*' or `*Completions*'?

As others have said, this kind of thing is a
user preference.  IOW, it's good to be able
to get either kind of UI behavior.  (I think
you agree about this.)

Re: [External] : Re: Adding a "quick-help" menu

[Philip Kaludercic]

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

>> I remember when I started using Emacs, I had
>> difficulties orienting myself around the menu bar,
>> considering how many menus and submenus there were.
>
> Is this specific to Emacs or in the nature of menus?

Menus might all have the risk, but I don't think it is necessary.  A lot
of GNOME 2 applications had well structured and regular menu hierarchy
that you could almost navigate just using the intuition gathered through
time.  The knowledge was transferable, because the software was designed
along similar guidelines.  The issue is that Emacs doesn't fit into this
mold.  This doesn't mean the menu is ineffectual, just that one has to
keep this in mind when talking about using the menu.

Re: Adding a "quick-help" menu

[Stefan Kangas]

Philip Kaludercic <philipk@posteo.net> writes:

> What kind of prefix keys are we talking about?  Could you give me a
> recent example for where which-key was useful to you (or anyone else)?

For me, it's all of them.  But how about `C-x r' or `C-x C-k'?

> But none of this is necessary when you press C-h.  The only disadvantage
> is that you would have to repeat the prefix, but I think that could be
> changed.

(BTW, if we are talking about messing up window layouts, `C-h' does too.
Even more so than `which-key', IME.)

> I personally think this is an advantage (though I wouldn't put it the
> way you did).  To me `which-key' -- the way it is configured by default
> -- seems fragile and unreliable.  A help buffer is just-another-buffer
> and doesn't appear to be an exception to the rest of how Emacs works.

I don't see anything exceptional.  Emacs already shows the key in the
echo area by default, it just doesn't give you all the useful help that
`which-key' does.

Re: Adding a "quick-help" menu

[Philip Kaludercic]

Stefan Kangas <stefankangas@gmail.com> writes:

> Philip Kaludercic <philipk@posteo.net> writes:
>
>> What kind of prefix keys are we talking about?  Could you give me a
>> recent example for where which-key was useful to you (or anyone else)?
>
> For me, it's all of them.  But how about `C-x r' or `C-x C-k'?

Hmm, those are good examples, but I honestly don't see the advantage
over C-h and the "issue" of a false-positive popup after something like
C-c (I know that I often hesitate on that prefix).

>> But none of this is necessary when you press C-h.  The only disadvantage
>> is that you would have to repeat the prefix, but I think that could be
>> changed.
>
> (BTW, if we are talking about messing up window layouts, `C-h' does too.
> Even more so than `which-key', IME.)

True, but the "messing up" is done in two different ways.  C-h pops up a
new buffer and might hide some other information, while which-key pushes
up from below which might narrow the buffer contents.  If the active
point is moved by this change in the window layout, this will change the
visible portion of the buffer even after the key chord completed.

I've tried this by having a single window with any buffer and moving the
point to the bottom of the window.  If I now provoke `which-key', my
scroll-settings (which I believe are the default ones) will have the
point moved to the centre of the window, which could hide some content
at the top of the window I was interested in.

>> I personally think this is an advantage (though I wouldn't put it the
>> way you did).  To me `which-key' -- the way it is configured by default
>> -- seems fragile and unreliable.  A help buffer is just-another-buffer
>> and doesn't appear to be an exception to the rest of how Emacs works.
>
> I don't see anything exceptional.  Emacs already shows the key in the
> echo area by default, it just doesn't give you all the useful help that
> `which-key' does.

But that is a single line, which is already the space allocated for the
echo area.  What I am taking issue with is the resizing of the echo area
(real or apparent), *especially* when it is done in reaction to a
non-action like waiting.

Re: Adding a "quick-help" menu

[Stefan Kangas]

Philip Kaludercic <philipk@posteo.net> writes:

> I've tried this by having a single window with any buffer and moving
> the point to the bottom of the window.  If I now provoke `which-key',
> my scroll-settings (which I believe are the default ones) will have
> the point moved to the centre of the window, which could hide some
> content at the top of the window I was interested in.

That's true.  But it doesn't sound like a fundamental limitation, so
maybe it could be fixed.

(It doesn't bother me with `scroll-conservatively' set to 500, FWIW.)

> What I am taking issue with is the resizing of the echo area (real or
> apparent), *especially* when it is done in reaction to a non-action
> like waiting.

The action is pressing a key.  That's not a "non-action", IMHO.

It's not that different from, e.g., `company-idle-delay'.

Re: Adding a "quick-help" menu

[Visuwesh]

[சனி செப்டம்பர் 17, 2022] Philip Kaludercic wrote:

>> It specifically shows help to this prefix key, I do not have
>> to move the mouse, I do not have to look for a symbol to
>> click or a menu entry which might be related.
>
> But none of this is necessary when you press C-h.  The only disadvantage
> is that you would have to repeat the prefix, but I think that could be
> changed.

Not that I have tried but from what I hear, embark's C-h thingy is the
best of both worlds: you still get a nice overview of _all_ the possible
keybindings under the prefix, and you don't have to repeat the prefix
since embark's thingy completes against the keybinding and the command
name i.e., it uses completing-read.  It has the added bonus of not
showing up uninvited just like Emacs does right now.

Re: which-key

[Visuwesh]

[சனி செப்டம்பர் 17, 2022] Stefan Monnier wrote:

> I guess we should simply change the "echo keystrokes" functionality so
> instead of just displaying "C-x-" it could display something like
> "C-x- [Hit C-h for help]".

Which reminds me: do people never intentionally wait out to see what
prefix they typed?  I do this quite a lot since I am fairly forgetful
wrt numeric prefixes, and having which-key show up uninvited would be
very annoying.

Re: Adding a "quick-help" menu

[Eli Zaretskii]

> From: Stefan Kangas <stefankangas@gmail.com>
> Date: Sat, 17 Sep 2022 20:05:24 -0400
> Cc: emacs-devel@gnu.org
> 
> (It doesn't bother me with `scroll-conservatively' set to 500, FWIW.)

All the values between 101 and 500 (or infinity, as a matter of fact)
buy you nothing at all.

Re: Adding a "quick-help" menu

[Gregor Zattler]

Hi Philip, emacs developers,
* Philip Kaludercic <philipk@posteo.net> [2022-09-17;14:44 GMT]:
> Gregor Zattler <telegraph@gmx.net> writes:
>> * Philip Kaludercic <philipk@posteo.net> [2022-09-16; 17:22 GMT]:
>>> Yes, but just like there is a difference between auto-completion and
>>> tab-completion, there is a difference to be considered here.
>>
>> for me the main difference to all other help facilities is,
>> that there is zero cognitive burden: It only pops up when I
>> hit a prefix key and then don't know what to do.
>
> What kind of prefix keys are we talking about?  Could you give me a
> recent example for where which-key was useful to you (or anyone else)?

a) when I do not remember which key adds files from dired to
the buffer in message-mode with unsent email; b) when I
search for the key binding for
mml-secure-message-sign-encrypt; actually not that often,
since I installed which-key seven years ago in favour of
describe-key (or some such, because it stole a key binding I
was relying of, back then).  Then it was C-x r, for instance.

I do not need it often, but for instance when I explore a
new package and it's key bindings.

>> It specifically shows help to this prefix key, I do not have
>> to move the mouse, I do not have to look for a symbol to
>> click or a menu entry which might be related.
>
> But none of this is necessary when you press C-h.

I do not know any more if I knew then that I could hit C-h
after a prefix key.

> The only disadvantage is that you would have to repeat the
> prefix, but I think that could be changed.
>
>> I do not have to know how to bury or kill it, it does not
>> litter my buffer list with jet another buried buffer, it
>> does not permanently change my window configuration.
>
> Do you meant the *Help* buffer?

Yes.  Here I was speaking remembering my first experiences
with Emacs.  Then I was overwhelmed for instance from the
number of buffers in my buffer list.  I'm still irritated by
the number and placement of windows Emacs opens especially
on my 4K monitor -- where this is a much smaller problem at
the same time.  I still do not feel comfortable with the
*help* buffers popping up but being not the active window...
[I just now used which-key to look up C-x 4 and learned that
there is C-x 4 q].

All this does not happen with which-key.

[...]
> I personally think this is an advantage (though I wouldn't put it the
> way you did).  To me `which-key' -- the way it is configured by default
> -- seems fragile and unreliable.  A help buffer is just-another-buffer
> and doesn't appear to be an exception to the rest of how Emacs works.

Sure, but that doesn't help in case one is not comfortable
with "how Emacs works", especially because one is a
newcomer.  In especially this case a help facility which
shows up when one is hesitating and goes away without
further action is of great help.

Later one may have adapted to Emacs or adapted Emacs or
abandoned Emacs.

Ciao; Gregor
--
 -... --- .-. . -.. ..--.. ...-.-

Re: which-key

[Gregory Heytings]

>
> Which reminds me: do people never intentionally wait out to see what 
> prefix they typed?
>

I never do that, because I have (setq echo-keystrokes 0.1).

Re: which-key (was: Adding a "quick-help" menu)

[Gregory Heytings]

>
> I guess we should simply change the "echo keystrokes" functionality so 
> instead of just displaying "C-x-" it could display something like "C-x- 
> [Hit C-h for help]".
>

Like this?

diff --git a/src/keyboard.c b/src/keyboard.c
index ca51c80da0..a9eb840c76 100644
--- a/src/keyboard.c
+++ b/src/keyboard.c
@@ -500,7 +500,8 @@ echo_add_key (Lisp_Object c)
      }

    if ((NILP (echo_string) || SCHARS (echo_string) == 0)
-      && help_char_p (c))
+      && help_char_p (c)
+      && NILP (Vecho_keystrokes_mention_help))
      {
        static const char text[] = " (Type ? for further options)";
        int len = sizeof text - 1;
@@ -559,11 +560,20 @@ echo_dash (void)
  	return;
      }

-  /* Put a dash at the end of the buffer temporarily,
+  /* Put a dash, and maybe the help key, at the end of the buffer temporarily,
       but make it go away when the next character is added.  */
-  AUTO_STRING (dash, "-");
-  kset_echo_string (current_kboard,
-		    concat2 (KVAR (current_kboard, echo_string), dash));
+  if (NILP (Vecho_keystrokes_mention_help))
+    {
+      AUTO_STRING (dash, "- ");
+      kset_echo_string (current_kboard,
+			concat2 (KVAR (current_kboard, echo_string), dash));
+    }
+  else
+    {
+      AUTO_STRING (dash, "- [Type C-h for help]");
+      kset_echo_string (current_kboard,
+			concat2 (KVAR (current_kboard, echo_string), dash));
+    }
    echo_now ();
  }

@@ -13107,6 +13117,10 @@ syms_of_keyboard (void)
  is called with one argument, the string that was selected.  */);;
    Vpost_select_region_hook = Qnil;

+  DEFVAR_LISP ("echo-keystrokes-mention-help", Vecho_keystrokes_mention_help,
+	       doc: /* Non-nil means display help key after echoing keystrokes. */);
+  Vecho_keystrokes_mention_help = Qt;
+
    pdumper_do_now_and_after_load (syms_of_keyboard_for_pdumper);
  }

Re: Adding a "quick-help" menu

[Philip Kaludercic]

Stefan Kangas <stefankangas@gmail.com> writes:

> Philip Kaludercic <philipk@posteo.net> writes:
>
>> What I am taking issue with is the resizing of the echo area (real or
>> apparent), *especially* when it is done in reaction to a non-action
>> like waiting.
>
> The action is pressing a key.  That's not a "non-action", IMHO.

OK, It is the sequence of an action (that may or may not be intended to
invoke `which-key') and a "non-action", namely waiting.n

> It's not that different from, e.g., `company-idle-delay'.

True, but company-mode is neither bundled by default let alone enabled.
All I am trying to argue is that `which-key' doesn't fit the style and
behaviour of default Emacs, *because* it uses idle times to change the
UI.

Re: which-key

[Po Lu]

Gregory Heytings <gregory@heytings.org> writes:

> +  DEFVAR_LISP ("echo-keystrokes-mention-help", Vecho_keystrokes_mention_help,
> +	       doc: /* Non-nil means display help key after echoing keystrokes. */);
> +  Vecho_keystrokes_mention_help = Qt;

That will be too annoying to be enabled by default.

Re: which-key

[Gregory Heytings]

>> +  DEFVAR_LISP ("echo-keystrokes-mention-help", Vecho_keystrokes_mention_help,
>> +	       doc: /* Non-nil means display help key after echoing keystrokes. */);
>> +  Vecho_keystrokes_mention_help = Qt;
>
> That will be too annoying to be enabled by default.
>

The point of this thread is to help newcomers to find help, right?  How 
would it help them if they had to add (setq echo-keystrokes-mention-help 
t) in their init file?  For experts like you on the contrary, it is easy 
to turn it off, isn't it?

Re: which-key

[Lars Ingebrigtsen]

Gregory Heytings <gregory@heytings.org> writes:

> The point of this thread is to help newcomers to find help, right?
> How would it help them if they had to add (setq
> echo-keystrokes-mention-help t) in their init file?  For experts like
> you on the contrary, it is easy to turn it off, isn't it?

Indeed.

But I think it'd probably be too annoying for everybody, even if it's
pretty helpful -- it's something you need to be told once or twice, and
then you know it.

So I'd rather not add this at all.

Re: Adding a "quick-help" menu

[Lars Ingebrigtsen]

Philip Kaludercic <philipk@posteo.net> writes:

> There is a fork of mg (MicroEmacs)[0] that binds C-h q to a command that
> pops up a buffer with these contents:

I think having a "cheat sheet" like this would be useful.

Re: Adding a "quick-help" menu

[Philip Kaludercic]

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

Lars Ingebrigtsen <larsi@gnus.org> writes:

> Philip Kaludercic <philipk@posteo.net> writes:
>
>> There is a fork of mg (MicroEmacs)[0] that binds C-h q to a command that
>> pops up a buffer with these contents:
>
> I think having a "cheat sheet" like this would be useful.

Calling it a "cheat sheet" sounds like a good idea.  I've added
`cheat-sheet' as an alias:


[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #2: 0001-Add-a-quick-help-menu.patch --]
[-- Type: text/x-patch, Size: 5357 bytes --]

From ddd1a02d3bc23c448b8d5869c8b9fe38a2b322ef Mon Sep 17 00:00:00 2001
From: Philip Kaludercic <philipk@posteo.net>
Date: Sat, 17 Sep 2022 16:52:01 +0200
Subject: [PATCH] Add a quick-help menu

* lisp/help.el (help-map): Bind 'help-quit-or-quick' instead of 'help-quit'.
(help-quick-sections): Add variable.
(help-quick): Add main command.
(cheat-sheet): Add alias for 'help-quick'.
(help-quit-or-quick): Add auxiliary command.
---
 lisp/help.el | 113 ++++++++++++++++++++++++++++++++++++++++++++++++++-
 1 file changed, 112 insertions(+), 1 deletion(-)

diff --git a/lisp/help.el b/lisp/help.el
index 92b87cf799..126eddef30 100644
--- a/lisp/help.el
+++ b/lisp/help.el
@@ -112,7 +112,7 @@ help-map
     (define-key map "v" 'describe-variable)
     (define-key map "w" 'where-is)
     (define-key map "x" 'describe-command)
-    (define-key map "q" 'help-quit)
+    (define-key map "q" 'help-quit-or-quick)
     map)
   "Keymap for characters following the Help key.")
 
@@ -125,11 +125,122 @@ global-map
 (defvar help-button-cache nil)
 
 \f
+
+(defvar help-quick-sections
+  '(("FILE"
+     (save-buffers-kill-terminal . "exit")
+     (find-file . "find")
+     (write-file . "write")
+     (save-buffer . "save")
+     (save-some-buffers . "all"))
+    ("BUFFER"
+     (kill-buffer . "kill")
+     (list-buffers . "list")
+     (switch-to-buffer . "switch")
+     (goto-line . "goto line")
+     (read-only-mode . "read only"))
+    ("WINDOW"
+     (delete-window . "only other")
+     (delete-other-windows . "only this")
+     (split-window-below . "split vert.")
+     (split-window-right . "split horiz.")
+     (other-window . "other"))
+    ("MARK/KILL"
+     (set-mark-command . "mark")
+     (kill-region . "wipe")
+     (kill-line . "kill")
+     (yank . "yank")
+     (exchange-point-and-mark . "swap"))
+    ("PROJECT"
+     (project-switch-project . "switch")
+     (project-find-file . "find file")
+     (project-find-regexp . "search")
+     (project-query-replace-regexp . "replace")
+     (project-compile . "compile"))
+    ("MISC"
+     (undo . "undo")
+     (isearch-forward . "search")
+     (isearch-backward . "rev-search")
+     (query-replace . "replace")
+     (fill-paragraph . "reformat"))))
+
+;; Inspired by a mg fork (https://github.com/troglobit/mg)
+(defun help-quick ()
+  "Display a quick-help buffer."
+  (interactive)
+  (with-current-buffer (get-buffer-create "*Quick Help*")
+    (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)
+        (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))
+                     (key (if bind
+                              (propertize
+                               (key-description bind)
+                               'face 'help-key-binding)
+                            (throw 'skip nil))))
+                (setq max-cmd-len (max (length (cdr ent)) max-cmd-len)
+                      max-key-len (max (length key) max-key-len))
+                (push (cons key (cdr ent)) keys))))
+          (when keys
+            (let ((fmt (format "%%-%ds %%-%ds%s" max-key-len max-cmd-len
+                               (make-string padding ?\s)))
+                  (width (+ max-key-len 1 max-cmd-len padding)))
+              (push `(,width
+                      ,(propertize
+                        (concat
+                         (car section)
+                         (make-string (- width (length (car section))) ?\s))
+                        'face 'bold)
+                      ,@(mapcar (lambda (ent)
+                                  (format fmt (car ent) (cdr ent)))
+                                keys))
+                    blocks)))))
+
+      ;; Insert each rectangle in order until they don't fit into the
+      ;; frame any more, in which case the next sections are inserted
+      ;; in a new "line".
+      (erase-buffer)
+      (dolist (block (nreverse blocks))
+        (when (> (+ (car block) (current-column)) (frame-width))
+          (goto-char (point-max))
+          (newline 2))
+        (save-excursion
+          (insert-rectangle (cdr block)))
+        (end-of-line))
+      (delete-trailing-whitespace))
+
+    ;; Display the buffer at the bottom of the page and shrink it
+    ;; immediately.
+    (help-mode)
+    (with-selected-window (display-buffer-at-bottom (current-buffer) '())
+      (fit-window-to-buffer))
+    (message
+     (substitute-command-keys "Toggle the quick help buffer using \\[help-quit-or-quick]."))))
+
+(defalias 'cheat-sheet #'help-quick)
+
 (defun help-quit ()
   "Just exit from the Help command's command loop."
   (interactive)
   nil)
 
+(defun help-quit-or-quick ()
+  "Call `help-quit' or  `help-quick' depending on the context."
+  (interactive)
+  (cond
+   (help-buffer-under-preparation
+    ;; FIXME: There should be a better way to detect if we are in the
+    ;;        help command loop.
+    (help-quit))
+   ((and-let* ((window (get-buffer-window "*Quick Help*")))
+      (quit-window t window)))
+   ((help-quick))))
+
 (defvar help-return-method nil
   "What to do to \"exit\" the help buffer.
 This is a list
-- 
2.37.3

Re: which-key

[Po Lu]

Gregory Heytings <gregory@heytings.org> writes:

> The point of this thread is to help newcomers to find help, right?
> How would it help them if they had to add (setq
> echo-keystrokes-mention-help t) in their init file?

They can read the tutorial, where C-h is mentioned under "Getting More
Help."

> For experts like you on the contrary, it is easy to turn it off, isn't
> it?

I'm afraid that by going down that road, the number of new "features" to
turn off upon each new release will become too overwhelming, even for
experienced Emacs users.

Re: which-key

[Stefan Monnier]

Lars Ingebrigtsen [2022-09-18 12:10:35] wrote:
> Gregory Heytings <gregory@heytings.org> writes:
>> The point of this thread is to help newcomers to find help, right?
>> How would it help them if they had to add (setq
>> echo-keystrokes-mention-help t) in their init file?  For experts like
>> you on the contrary, it is easy to turn it off, isn't it?
>
> Indeed.
>
> But I think it'd probably be too annoying for everybody, even if it's
> pretty helpful -- it's something you need to be told once or twice, and
> then you know it.

We could easily limit it to once per session, which would make it rather
non-intrusive.


        Stefan

Re: which-key

[Stefan Kangas]

Stefan Monnier <monnier@iro.umontreal.ca> writes:

> We could easily limit it to once per session, which would make it rather
> non-intrusive.

...and/or give it a different, less intrusive face than the default.

Re: which-key

[Gregor Zattler]

Hi Stefan, emacs developers,
* Stefan Kangas <stefankangas@gmail.com> [2022-09-18; 11:39 -04]:
> Stefan Monnier <monnier@iro.umontreal.ca> writes:
>
>> We could easily limit it to once per session, which would make it rather
>> non-intrusive.

or add a button to disable this, like in the *Warnings* buffer?

> ...and/or give it a different, less intrusive face than the default.

That wouldn't help discoverability, especially for people
with limited sight.


Ciao; Gregor
--
 -... --- .-. . -.. ..--.. ...-.-

Re: which-key

[Gregory Heytings]

>> But I think it'd probably be too annoying for everybody, even if it's 
>> pretty helpful -- it's something you need to be told once or twice, and 
>> then you know it.

Hmm... C-h displays "(Type ? for further options)" and has been doing that 
for years, I don't think anyone complained?  And it's something that by 
default becomes visible only after a one second delay, so when you know 
what you're doing it's not displayed at all.

>
> We could easily limit it to once per session, which would make it rather 
> non-intrusive.
>

Indeed.

Re: Adding a "quick-help" menu

[Bob Rogers]

   From: Philip Kaludercic <philipk@posteo.net>
   Date: Sun, 18 Sep 2022 10:53:58 +0000

   Lars Ingebrigtsen <larsi@gnus.org> writes:

   > Philip Kaludercic <philipk@posteo.net> writes:
   >
   >> There is a fork of mg (MicroEmacs)[0] that binds C-h q to a command that
   >> pops up a buffer with these contents:
   >
   > I think having a "cheat sheet" like this would be useful.

   Calling it a "cheat sheet" sounds like a good idea.  I've added
   `cheat-sheet' as an alias:

A quick Web search for "emacs cheat sheet" turns up the "GNU Emacs
Reference Card" as the first hit -- followed by a bunch of others.  And
it occurs to me that, for a real newbie, a cheat sheet in a browser
window might be easier to work with than one within emacs itself.

					-- Bob Rogers
					   http://www.rgrjr.com/

[1]  https://www.gnu.org/software/emacs/refcards/pdf/refcard.pdf

Re: Adding a "quick-help" menu

[Philip Kaludercic]

Bob Rogers <rogers@rgrjr.com> writes:

>    From: Philip Kaludercic <philipk@posteo.net>
>    Date: Sun, 18 Sep 2022 10:53:58 +0000
>
>    Lars Ingebrigtsen <larsi@gnus.org> writes:
>
>    > Philip Kaludercic <philipk@posteo.net> writes:
>    >
>    >> There is a fork of mg (MicroEmacs)[0] that binds C-h q to a command that
>    >> pops up a buffer with these contents:
>    >
>    > I think having a "cheat sheet" like this would be useful.
>
>    Calling it a "cheat sheet" sounds like a good idea.  I've added
>    `cheat-sheet' as an alias:
>
> A quick Web search for "emacs cheat sheet" turns up the "GNU Emacs
> Reference Card" as the first hit -- followed by a bunch of others.  And
> it occurs to me that, for a real newbie, a cheat sheet in a browser
> window might be easier to work with than one within emacs itself.

I might just be too young and lack the concentration that pre-gen-z
people had that reference card always appeared too overwhelming for me.

I guess my suggestion isn't much better, it is the same thing just less
of it...

> 					-- Bob Rogers
> 					   http://www.rgrjr.com/
>
> [1]  https://www.gnu.org/software/emacs/refcards/pdf/refcard.pdf

Re: Adding a "quick-help" menu

[Bob Rogers]

   From: Philip Kaludercic <philipk@posteo.net>
   Date: Sun, 18 Sep 2022 17:53:07 +0000

   Bob Rogers <rogers@rgrjr.com> writes:

   > A quick Web search for "emacs cheat sheet" turns up the "GNU Emacs
   > Reference Card" as the first hit -- followed by a bunch of others.  And
   > it occurs to me that, for a real newbie, a cheat sheet in a browser
   > window might be easier to work with than one within emacs itself.

   I might just be too young and lack the concentration that pre-gen-z
   people had that reference card always appeared too overwhelming for me.

Honestly, I think it was less a matter of concentration and more a
matter of memory for us oldsters.  In the days of terminals with crappy
bandwidth, a paper sheet beside you would save you from having to use
that precious bandwidth on emacs help commands, which were necessarily
just as slow as everything else.  If you had good memory, you were
golden; if not, you checked the cheat sheet; if you couldn't find it
there, you tried the help commands.

   I guess my suggestion isn't much better, it is the same thing just less
   of it...

FWIW, a friend and I put together a cheat sheet [1] for some total newbs
forced to use emacs for a three-week class.  We tried to make it less
intimidating by making it more focused and organizing it carefully.

					-- Bob

[1]  http://www.rgrjr.com/emacs/emacs_cheat.html (may be dated)

Re: Adding a "quick-help" menu

[wilnerthomas--- via Emacs development discussions.]

Sep 18, 2022, 17:53 by philipk@posteo.net:

> Bob Rogers <rogers@rgrjr.com> writes:
>
>> From: Philip Kaludercic <philipk@posteo.net>
>>  Date: Sun, 18 Sep 2022 10:53:58 +0000
>>
>>  Lars Ingebrigtsen <larsi@gnus.org> writes:
>>
>>  > Philip Kaludercic <philipk@posteo.net> writes:
>>  >
>>  >> There is a fork of mg (MicroEmacs)[0] that binds C-h q to a command that
>>  >> pops up a buffer with these contents:
>>  >
>>  > I think having a "cheat sheet" like this would be useful.
>>
>>  Calling it a "cheat sheet" sounds like a good idea.  I've added
>>  `cheat-sheet' as an alias:
>>
>> A quick Web search for "emacs cheat sheet" turns up the "GNU Emacs
>> Reference Card" as the first hit -- followed by a bunch of others.  And
>> it occurs to me that, for a real newbie, a cheat sheet in a browser
>> window might be easier to work with than one within emacs itself.
>>

A reference card is there to guide you, but most schools have banged in people's
minds that things that help you constitute cheating.  Total nonsense.


> I might just be too young and lack the concentration that pre-gen-z
> people had that reference card always appeared too overwhelming for me.
>

You rather read the whole Emacs Manual instead?


> I guess my suggestion isn't much better, it is the same thing just less
> of it...
>
>> -- Bob Rogers
>>  http://www.rgrjr.com/
>>
>> [1]  https://www.gnu.org/software/emacs/refcards/pdf/refcard.pdf
>>
Having categorisations does help you focus on the parts you need at a particular moment. 

Re: Adding a "quick-help" menu

[Philip Kaludercic]

wilnerthomas--- via "Emacs development discussions."
<emacs-devel@gnu.org> writes:

>> I might just be too young and lack the concentration that pre-gen-z
>> people had that reference card always appeared too overwhelming for me.
>>
>
> You rather read the whole Emacs Manual instead?

I am afraid I don't understand how you infer that from this thread.  All
I am saying is that the cheat sheet is a bit crowded, at least compared
to the menu I am proposing.

Re: Adding a "quick-help" menu

[Christopher Dimech]

> Sent: Monday, September 19, 2022 at 9:21 AM
> From: "Philip Kaludercic" <philipk@posteo.net>
> To: "wilnerthomas--- via Emacs development discussions." <emacs-devel@gnu.org>
> Cc: wilnerthomas@tutanota.com, "Bob Rogers" <rogers@rgrjr.com>, "Lars Ingebrigtsen" <larsi@gnus.org>
> Subject: Re: Adding a "quick-help" menu
>
> wilnerthomas--- via "Emacs development discussions."
> <emacs-devel@gnu.org> writes:
>
> >> I might just be too young and lack the concentration that pre-gen-z
> >> people had that reference card always appeared too overwhelming for me.
> >>
> >
> > You rather read the whole Emacs Manual instead?
>
> I am afraid I don't understand how you infer that from this thread.  All
> I am saying is that the cheat sheet is a bit crowded, at least compared
> to the menu I am proposing.

Perhaps the menu could have categories so you won't have to see the whole thing.

Re: Adding a "quick-help" menu

[Philip Kaludercic]

Christopher Dimech <dimech@gmx.com> writes:

>> Sent: Monday, September 19, 2022 at 9:21 AM
>> From: "Philip Kaludercic" <philipk@posteo.net>
>> To: "wilnerthomas--- via Emacs development discussions." <emacs-devel@gnu.org>
>> Cc: wilnerthomas@tutanota.com, "Bob Rogers" <rogers@rgrjr.com>, "Lars Ingebrigtsen" <larsi@gnus.org>
>> Subject: Re: Adding a "quick-help" menu
>>
>> wilnerthomas--- via "Emacs development discussions."
>> <emacs-devel@gnu.org> writes:
>>
>> >> I might just be too young and lack the concentration that pre-gen-z
>> >> people had that reference card always appeared too overwhelming for me.
>> >>
>> >
>> > You rather read the whole Emacs Manual instead?
>>
>> I am afraid I don't understand how you infer that from this thread.  All
>> I am saying is that the cheat sheet is a bit crowded, at least compared
>> to the menu I am proposing.
>
> Perhaps the menu could have categories so you won't have to see the whole thing.

So you mean something like a query like "what do you want help with"?
You say file management and then it prints out the 5 or 6 commands
related to basic file management?

Re: Adding a "quick-help" menu

[Christopher Dimech]

> Sent: Monday, September 19, 2022 at 11:00 AM
> From: "Philip Kaludercic" <philipk@posteo.net>
> To: "Christopher Dimech" <dimech@gmx.com>
> Cc: "wilnerthomas--- via Emacs development discussions." <emacs-devel@gnu.org>, wilnerthomas@tutanota.com, "Bob Rogers" <rogers@rgrjr.com>, "Lars Ingebrigtsen" <larsi@gnus.org>
> Subject: Re: Adding a "quick-help" menu
>
> Christopher Dimech <dimech@gmx.com> writes:
>
> >> Sent: Monday, September 19, 2022 at 9:21 AM
> >> From: "Philip Kaludercic" <philipk@posteo.net>
> >> To: "wilnerthomas--- via Emacs development discussions." <emacs-devel@gnu.org>
> >> Cc: wilnerthomas@tutanota.com, "Bob Rogers" <rogers@rgrjr.com>, "Lars Ingebrigtsen" <larsi@gnus.org>
> >> Subject: Re: Adding a "quick-help" menu
> >>
> >> wilnerthomas--- via "Emacs development discussions."
> >> <emacs-devel@gnu.org> writes:
> >>
> >> >> I might just be too young and lack the concentration that pre-gen-z
> >> >> people had that reference card always appeared too overwhelming for me.
> >> >>
> >> >
> >> > You rather read the whole Emacs Manual instead?
> >>
> >> I am afraid I don't understand how you infer that from this thread.  All
> >> I am saying is that the cheat sheet is a bit crowded, at least compared
> >> to the menu I am proposing.
> >
> > Perhaps the menu could have categories so you won't have to see the whole thing.
>
> So you mean something like a query like "what do you want help with"?
> You say file management and then it prints out the 5 or 6 commands
> related to basic file management?

Right.  Examples

Window and Buffer Commands
Cursor Movement Commands
Copy and Delete Commands
Search Commands

There could navigate through a completion list, then select which one you like.

Re: Adding a "quick-help" menu

[Lars Ingebrigtsen]

Philip Kaludercic <philipk@posteo.net> writes:

> Calling it a "cheat sheet" sounds like a good idea.  I've added
> `cheat-sheet' as an alias:

Thanks; I think this looks useful, and easy to extend if we want to.

Philip Kaludercic <philipk@posteo.net> writes:

>> Perhaps the menu could have categories so you won't have to see the
>> whole thing.
>
> So you mean something like a query like "what do you want help with"?
> You say file management and then it prints out the 5 or 6 commands
> related to basic file management?

I don't think that would be as useful.  You need this when you don't
really know what Emacs offers -- and Emacs has oddball terminology here,
so just showing the entire cheat sheet is best.

That is, if you know that you want to change the "window size" (what
other editors would call "a pane" or "the file", perhaps), you don't
need the cheat sheet that much.

Re: which-key

[Lars Ingebrigtsen]

Stefan Monnier <monnier@iro.umontreal.ca> writes:

> We could easily limit it to once per session, which would make it rather
> non-intrusive.

Or once, forever, I guess (via multisession variables).

Re: which-key

[Lars Ingebrigtsen]

Gregory Heytings <gregory@heytings.org> writes:

> Hmm... C-h displays "(Type ? for further options)" and has been doing
> that for years, I don't think anyone complained?

But that's an entry into the help system -- not something that pops up
in the middle of what you're typing.

I just think it would be distracting.

Re: which-key

[Gregory Heytings]

>
> I just think it would be distracting.
>

Okay, a status quo is fine with me, too.

Re: Adding a "quick-help" menu

[Po Lu]

Lars Ingebrigtsen <larsi@gnus.org> writes:

> Thanks; I think this looks useful, and easy to extend if we want to.

BTW, don't we already have Emacs flash cards?
Maybe most of the content there could be reused.

Re: Adding a "quick-help" menu

[Stefan Kangas]

Philip Kaludercic <philipk@posteo.net> writes:

> Lars Ingebrigtsen <larsi@gnus.org> writes:
>
>> Philip Kaludercic <philipk@posteo.net> writes:
>>
>>> There is a fork of mg (MicroEmacs)[0] that binds C-h q to a command that
>>> pops up a buffer with these contents:
>>
>> I think having a "cheat sheet" like this would be useful.
>
> Calling it a "cheat sheet" sounds like a good idea.  I've added
> `cheat-sheet' as an alias:

Thanks, this looks great.  Some comments after testing it:

- I think we should use `help-for-help-header' for the headlines, not
  capitalize them, and align them with :align-to.

- Should it be modal, like `C-h C-h'?

- If not, I think it would be nice if you could remove it by typing "q"
  again.

  Perhaps point should be moved to the new buffer by default?  (But then
  again, it doesn't do that with "*Help*" by default, sadly.)  So maybe
  a repeat-map is appropriate?  Just some ideas.

- The keys should be linked to the corresponding command docstrings.

- Wishlist: It would be great if it had an optional vertical view,
  perhaps that you could toggle with both a command and defcustom.
  Perhaps the vertical view could even be the default if the window
  width is too narrow to fit it all?

Also, some nits:

- "other" should be "other win." or "other window".

- "rev. search" should be "search backwards".

- "replace" could be "search & replace" or "search&replace"

Re: Adding a "quick-help" menu

[Stefan Kangas]

Po Lu <luangruo@yahoo.com> writes:

> Lars Ingebrigtsen <larsi@gnus.org> writes:
>
>> Thanks; I think this looks useful, and easy to extend if we want to.
>
> BTW, don't we already have Emacs flash cards?
> Maybe most of the content there could be reused.

I think it has too much stuff on them to fit, unfortunately.  It's not
as focused and covers a much broader range of features.

Having reviewed the reference card and Philip's cheat sheet, maybe "C-g"
should be added to the cheat sheet.

One idea: Without adding any new lines, it could replace "C-x u", which
could in turn be moved under "File" to replace "C-x s" (which would be
removed).

Re: which-key

[Stefan Kangas]

Lars Ingebrigtsen <larsi@gnus.org> writes:

> Or once, forever, I guess (via multisession variables).

It would be very easy to miss, to put it mildly.

Re: Adding a "quick-help" menu

[Philip Kaludercic]

Stefan Kangas <stefankangas@gmail.com> writes:

> Philip Kaludercic <philipk@posteo.net> writes:
>
>> Lars Ingebrigtsen <larsi@gnus.org> writes:
>>
>>> Philip Kaludercic <philipk@posteo.net> writes:
>>>
>>>> There is a fork of mg (MicroEmacs)[0] that binds C-h q to a command that
>>>> pops up a buffer with these contents:
>>>
>>> I think having a "cheat sheet" like this would be useful.
>>
>> Calling it a "cheat sheet" sounds like a good idea.  I've added
>> `cheat-sheet' as an alias:
>
> Thanks, this looks great.  Some comments after testing it:
>
> - I think we should use `help-for-help-header' for the headlines, not
>   capitalize them, and align them with :align-to.

That can be done.

> - Should it be modal, like `C-h C-h'?
>
> - If not, I think it would be nice if you could remove it by typing "q"
>   again.
>
>   Perhaps point should be moved to the new buffer by default?  (But then
>   again, it doesn't do that with "*Help*" by default, sadly.)  So maybe
>   a repeat-map is appropriate?  Just some ideas.

That depends on how this is to be used.  Is this something a new user
would use to quickly peek if they don't know how to do something, or
should it serve as a permanent "cheat sheet" at the bottom of the screen
(sort of like Nano).

> - The keys should be linked to the corresponding command docstrings.

This can also be done.

> - Wishlist: It would be great if it had an optional vertical view,
>   perhaps that you could toggle with both a command and defcustom.
>   Perhaps the vertical view could even be the default if the window
>   width is too narrow to fit it all?

I was just thinking about this too.  I implemented this vertically,
which is more complicated, because that is what the mg fork did too, but
mg has no horizontal splits, so it had no choice.

> Also, some nits:
>
> - "other" should be "other win." or "other window".
>
> - "rev. search" should be "search backwards".
>
> - "replace" could be "search & replace" or "search&replace"

We can try this, my only concern is that this might use too much
horizontal space.

Re: which-key

[Corwin Brust]

On Mon, Sep 19, 2022 at 3:19 AM Gregory Heytings <gregory@heytings.org> wrote:
> >
> > I just think it would be distracting.
> >
>
> Okay, a status quo is fine with me, too.

FWIW, I would expect any change that materially helps new users by
adding "clues" of how to find things will require some express action
(e.g. by veteran users) to disable.   Finding ways to help newer users
that more experienced users won't notice (or won't mind) seems like a
very tall order.

Re: Adding a "quick-help" menu

[Howard Melman]

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


>> I think having a "cheat sheet" like this would be useful.
>
> Calling it a "cheat sheet" sounds like a good idea.  I've added
> `cheat-sheet' as an alias:

I do think this could be useful.  I tried running it on 28.2
and the last two rows didn't line up:


[-- Attachment #2: Screen Shot 2022-09-19 at 11.17.52 AM.png --]
[-- Type: image/png, Size: 91654 bytes --]

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


Also, I know this is meant to teach the key-bindings, but it
seems like a transient of this stuff might also be useful to
newbies.

-- 

Howard

Re: which-key

[Emanuel Berg]

Too hot code for many:

;;; -*- lexical-binding: t -*-
;;
;; this file:
;;   https://dataswamp.org/~incal/emacs-init/show-cmd.el

(defun show-key-command (&optional key cmd)
  (interactive)
  (let*((key-ps      "hit key(s)!")
        (ps           (if cmd
                          (format "%s   %s " cmd key-ps)
                        key-ps) )
        (k            (or key (read-key-sequence-vector ps)))
        (new-cmd      (key-binding k))
        (cmd-or-undef (if new-cmd
                          (format "`%s'" new-cmd)
                        "undefined")) )
    (if (and key cmd)
        (string= new-cmd cmd)
      (if key
          (message "%s" cmd-or-undef)
        (unless (equal k [7]) ; [7] is C-g or `keyboard-quit'
          (show-key-command nil cmd-or-undef) )))))

;; (show-key-command)
;;                   ^ eval me :)

-- 
underground experts united
https://dataswamp.org/~incal

Re: Adding a "quick-help" menu

[Philip Kaludercic]

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


(Sorry for the delay, I got distracted)

Philip Kaludercic <philipk@posteo.net> writes:

> Stefan Kangas <stefankangas@gmail.com> writes:
>
>> Philip Kaludercic <philipk@posteo.net> writes:
>>
>>> Lars Ingebrigtsen <larsi@gnus.org> writes:
>>>
>>>> Philip Kaludercic <philipk@posteo.net> writes:
>>>>
>>>>> There is a fork of mg (MicroEmacs)[0] that binds C-h q to a command that
>>>>> pops up a buffer with these contents:
>>>>
>>>> I think having a "cheat sheet" like this would be useful.
>>>
>>> Calling it a "cheat sheet" sounds like a good idea.  I've added
>>> `cheat-sheet' as an alias:
>>
>> Thanks, this looks great.  Some comments after testing it:
>>
>> - I think we should use `help-for-help-header' for the headlines, not
>>   capitalize them, and align them with :align-to.
>
> That can be done.

This has turned out to be more complicated than I had initially assumed,
because way the menu is constructed inserting special properties isn't
that easy.  Do you think that this would be a hard requirement.

>> - Should it be modal, like `C-h C-h'?
>>
>> - If not, I think it would be nice if you could remove it by typing "q"
>>   again.
>>
>>   Perhaps point should be moved to the new buffer by default?  (But then
>>   again, it doesn't do that with "*Help*" by default, sadly.)  So maybe
>>   a repeat-map is appropriate?  Just some ideas.
>
> That depends on how this is to be used.  Is this something a new user
> would use to quickly peek if they don't know how to do something, or
> should it serve as a permanent "cheat sheet" at the bottom of the screen
> (sort of like Nano).

I really think that this should be a persistent menu, so closing the
menu with "q" seems like the wrong thing.  Again, this is not a
which-key alternative, the target audience are people who are struggling
to remember how to open a file or kill a line.

>> - The keys should be linked to the corresponding command docstrings.
>
> This can also be done.

Has been added in the patch below.

>> - Wishlist: It would be great if it had an optional vertical view,
>>   perhaps that you could toggle with both a command and defcustom.
>>   Perhaps the vertical view could even be the default if the window
>>   width is too narrow to fit it all?
>
> I was just thinking about this too.  I implemented this vertically,
> which is more complicated, because that is what the mg fork did too, but
> mg has no horizontal splits, so it had no choice.

I haven't implemented this yet, because I am uncertain if it is worth
the additional complexity.

>> Also, some nits:
>>
>> - "other" should be "other win." or "other window".
>>
>> - "rev. search" should be "search backwards".
>>
>> - "replace" could be "search & replace" or "search&replace"
>
> We can try this, my only concern is that this might use too much
> horizontal space.

Also did this, it seems to be fine.


[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #2: 0001-Add-a-quick-help-menu.patch --]
[-- Type: text/x-patch, Size: 6388 bytes --]

From aa5e4b0e6f4aa60fed9c5b1dde3c590fc9a62e61 Mon Sep 17 00:00:00 2001
From: Philip Kaludercic <philipk@posteo.net>
Date: Sat, 17 Sep 2022 16:52:01 +0200
Subject: [PATCH] Add a quick-help menu

* lisp/help.el (help-map): Bind 'help-quit-or-quick' instead of 'help-quit'.
(help-quick-sections): Add variable.
(help-quick): Add main command.
(cheat-sheet): Add alias for 'help-quick'.
(help-quit-or-quick): Add auxiliary command.
---
 lisp/help.el | 134 ++++++++++++++++++++++++++++++++++++++++++++++++++-
 1 file changed, 133 insertions(+), 1 deletion(-)

diff --git a/lisp/help.el b/lisp/help.el
index b4b9120da3..1d960cf269 100644
--- a/lisp/help.el
+++ b/lisp/help.el
@@ -112,7 +112,7 @@ help-map
     (define-key map "v" 'describe-variable)
     (define-key map "w" 'where-is)
     (define-key map "x" 'describe-command)
-    (define-key map "q" 'help-quit)
+    (define-key map "q" 'help-quit-or-quick)
     map)
   "Keymap for characters following the Help key.")
 
@@ -125,11 +125,143 @@ global-map
 (defvar help-button-cache nil)
 
 \f
+
+(defvar help-quick-sections
+  '(("File"
+     (save-buffers-kill-terminal . "exit")
+     (find-file . "find")
+     (write-file . "write")
+     (save-buffer . "save")
+     (save-some-buffers . "all"))
+    ("Buffer"
+     (kill-buffer . "kill")
+     (list-buffers . "list")
+     (switch-to-buffer . "switch")
+     (goto-line . "goto line")
+     (read-only-mode . "read only"))
+    ("Window"
+     (delete-window . "only other")
+     (delete-other-windows . "only this")
+     (split-window-below . "split vert.")
+     (split-window-right . "split horiz.")
+     (other-window . "other window"))
+    ("Mark & Kill"
+     (set-mark-command . "mark")
+     (kill-line . "kill line")
+     (kill-ring-save . "kill region")
+     (yank . "yank")
+     (exchange-point-and-mark . "swap"))
+    ("Projects"
+     (project-switch-project . "switch")
+     (project-find-file . "find file")
+     (project-find-regexp . "search")
+     (project-query-replace-regexp . "search & replace")
+     (project-compile . "compile"))
+    ("Misc."
+     (undo . "undo")
+     (isearch-forward . "search")
+     (isearch-backward . "reverse search")
+     (query-replace . "search & replace")
+     (fill-paragraph . "reformat"))))
+
+(declare-function prop-match-value "text-property-search" (match))
+
+;; Inspired by a mg fork (https://github.com/troglobit/mg)
+(defun help-quick ()
+  "Display a quick-help buffer."
+  (interactive)
+  (with-current-buffer (get-buffer-create "*Quick Help*")
+    (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)
+        (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))
+                     (key (if bind
+                              (propertize
+                               (key-description bind)
+                               'face 'help-key-binding)
+                            (throw 'skip nil))))
+                (setq max-cmd-len (max (length (cdr ent)) max-cmd-len)
+                      max-key-len (max (length key) max-key-len))
+                (push (list key (cdr ent) (car ent)) keys))))
+          (when keys
+            (let ((fmt (format "%%-%ds %%-%ds%s" max-key-len max-cmd-len
+                               (make-string padding ?\s)))
+                  (width (+ max-key-len 1 max-cmd-len padding)))
+              (push `(,width
+                      ,(propertize
+                        (concat
+                         (car section)
+                         (make-string (- width (length (car section))) ?\s))
+                        'face 'bold)
+                      ,@(mapcar (lambda (ent)
+                                  (format fmt
+                                          (propertize
+                                           (car ent)
+                                           'quick-help-cmd
+                                           (caddr ent))
+                                          (cadr ent)))
+                                keys))
+                    blocks)))))
+
+      ;; Insert each rectangle in order until they don't fit into the
+      ;; frame any more, in which case the next sections are inserted
+      ;; in a new "line".
+      (erase-buffer)
+      (dolist (block (nreverse blocks))
+        (when (> (+ (car block) (current-column)) (frame-width))
+          (goto-char (point-max))
+          (newline 2))
+        (save-excursion
+          (insert-rectangle (cdr block)))
+        (end-of-line))
+      (delete-trailing-whitespace)
+
+      (save-excursion
+        (goto-char (point-min))
+        (while-let ((match (text-property-search-forward 'quick-help-cmd)))
+          (make-text-button (prop-match-beginning match)
+                            (prop-match-end match)
+                            'mouse-face 'highlight
+                            'button t
+                            'keymap button-map
+                            'action #'describe-symbol
+                            'button-data (prop-match-value match)))))
+
+    (help-mode)
+
+    ;; Display the buffer at the bottom of the frame...
+    (with-selected-window (display-buffer-at-bottom (current-buffer) '())
+      ;; ... mark it as dedicated to prevent focus from being stolen
+      (set-window-dedicated-p (selected-window) t)
+      ;; ... and shrink it immediately.
+      (fit-window-to-buffer))
+    (message
+     (substitute-command-keys "Toggle the quick help buffer using \\[help-quit-or-quick]."))))
+
+(defalias 'cheat-sheet #'help-quick)
+
 (defun help-quit ()
   "Just exit from the Help command's command loop."
   (interactive)
   nil)
 
+(defun help-quit-or-quick ()
+  "Call `help-quit' or  `help-quick' depending on the context."
+  (interactive)
+  (cond
+   (help-buffer-under-preparation
+    ;; FIXME: There should be a better way to detect if we are in the
+    ;;        help command loop.
+    (help-quit))
+   ((and-let* ((window (get-buffer-window "*Quick Help*")))
+      (quit-window t window)))
+   ((help-quick))))
+
 (defvar help-return-method nil
   "What to do to \"exit\" the help buffer.
 This is a list
-- 
2.37.3

Re: Adding a "quick-help" menu

[Lars Ingebrigtsen]

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

Philip Kaludercic <philipk@posteo.net> writes:

> * lisp/help.el (help-map): Bind 'help-quit-or-quick' instead of 'help-quit'.
> (help-quick-sections): Add variable.

I gave it a quick test, and it looks good to me.  However, things don't
line up on Ubuntu by default due to bug#57962 (which we really should
try to fix soonish):


[-- Attachment #2: Type: image/png, Size: 95697 bytes --]

Re: Adding a "quick-help" menu

[Philip Kaludercic]

Lars Ingebrigtsen <larsi@gnus.org> writes:

> Philip Kaludercic <philipk@posteo.net> writes:
>
>> * lisp/help.el (help-map): Bind 'help-quit-or-quick' instead of 'help-quit'.
>> (help-quick-sections): Add variable.
>
> I gave it a quick test, and it looks good to me.  However, things don't
> line up on Ubuntu by default due to bug#57962 (which we really should
> try to fix soonish):

One annoyance I have, that your screenshot illustrates is that the
keybinding face is applied beyond just the key, even though I just
`propertize' the result of (key-description bind).  It seems the issue
is that

   (format "%-10s" (propertize "test" 'prop 'val))

evaluates to

   #("test      " 0 10 (prop val))

instead of just

   #("test      " 0 4 (prop val))

Re: Adding a "quick-help" menu

[Philip Kaludercic]

Lars Ingebrigtsen <larsi@gnus.org> writes:

> Philip Kaludercic <philipk@posteo.net> writes:
>
>> * lisp/help.el (help-map): Bind 'help-quit-or-quick' instead of 'help-quit'.
>> (help-quick-sections): Add variable.
>
> I gave it a quick test, and it looks good to me.  However, things don't
> line up on Ubuntu by default due to bug#57962 (which we really should
> try to fix soonish):

So is this issue blocking the application of my patch, or should I go
ahead and push the current version?

Re: Adding a "quick-help" menu

[Lars Ingebrigtsen]

Philip Kaludercic <philipk@posteo.net> writes:

> One annoyance I have, that your screenshot illustrates is that the
> keybinding face is applied beyond just the key, even though I just
> `propertize' the result of (key-description bind).  It seems the issue
> is that
>
>    (format "%-10s" (propertize "test" 'prop 'val))
>
> evaluates to
>
>    #("test      " 0 10 (prop val))
>
> instead of just
>
>    #("test      " 0 4 (prop val))

Yes, I think you have to compute the widths "by hand" and avoid %10s
format directives, unfortunately.

Re: Adding a "quick-help" menu

[Lars Ingebrigtsen]

Philip Kaludercic <philipk@posteo.net> writes:

> So is this issue blocking the application of my patch, or should I go
> ahead and push the current version?

No, not a blocker -- go ahead and push when you feel it's ready.

Re: Adding a "quick-help" menu

[Philip Kaludercic]

Lars Ingebrigtsen <larsi@gnus.org> writes:

> Philip Kaludercic <philipk@posteo.net> writes:
>
>> So is this issue blocking the application of my patch, or should I go
>> ahead and push the current version?
>
> No, not a blocker -- go ahead and push when you feel it's ready.

Done.

Re: Adding a "quick-help" menu

[Howard Melman]

A few comments on the text.

In Window I think C-x 0 should be called kill (or close)
because that what it does to the window, and this is
meaningful if there is more than 2 windows in the frame.
Kill matches the usage in Buffer.  And perhaps C-x 1 should
be labeled "kill others".

Also I think C-x o should be called switch just like C-x b
in Buffer.

In Mark & Kill I would put Kill Line first so that the mark
command is closer to the region and yank commands.

Finally the text for C-x C-c is "exit" in the File column
and I don't think that's clear enough that it exits emacs
and not just a file.  I know there isn't room to add emacs
but maybe "quit" is clearer as quitting a file makes less
sense (IMHO) than exiting one.

-- 

Howard

Re: Adding a "quick-help" menu

[Philip Kaludercic]

Howard Melman <hmelman@gmail.com> writes:

> A few comments on the text.
>
> In Window I think C-x 0 should be called kill (or close)
> because that what it does to the window, and this is
> meaningful if there is more than 2 windows in the frame.
> Kill matches the usage in Buffer.  And perhaps C-x 1 should
> be labeled "kill others".
>
> Also I think C-x o should be called switch just like C-x b
> in Buffer.
>
> In Mark & Kill I would put Kill Line first so that the mark
> command is closer to the region and yank commands.
>
> Finally the text for C-x C-c is "exit" in the File column
> and I don't think that's clear enough that it exits emacs
> and not just a file.  I know there isn't room to add emacs
> but maybe "quit" is clearer as quitting a file makes less
> sense (IMHO) than exiting one.

The contents of the help buffer are specified by the
`help-quick-sections' variable in lisp/help.el.  Feel free to prepare a
patch with your suggestions, that would make it easier to see how they
look like.

Re: Adding a "quick-help" menu

[Howard Melman]

On Oct 16, 2022, at 12:01 PM, Philip Kaludercic <philipk@posteo.net> wrote:
> 
> Howard Melman <hmelman@gmail.com> writes:
> 
>> A few comments on the text.
>> 
>> In Window I think C-x 0 should be called kill (or close)
>> because that what it does to the window, and this is
>> meaningful if there is more than 2 windows in the frame.
>> Kill matches the usage in Buffer.  And perhaps C-x 1 should
>> be labeled "kill others".
>> 
>> Also I think C-x o should be called switch just like C-x b
>> in Buffer.
>> 
>> In Mark & Kill I would put Kill Line first so that the mark
>> command is closer to the region and yank commands.
>> 
>> Finally the text for C-x C-c is "exit" in the File column
>> and I don't think that's clear enough that it exits emacs
>> and not just a file.  I know there isn't room to add emacs
>> but maybe "quit" is clearer as quitting a file makes less
>> sense (IMHO) than exiting one.
> 
> The contents of the help buffer are specified by the
> `help-quick-sections' variable in lisp/help.el.  Feel free to prepare a
> patch with your suggestions, that would make it easier to see how they
> look like.

I don't build my own emacs and haven't signed papers, so I hope
my mere comments are understandable and sufficient for consideration.

Howard

Re: Adding a "quick-help" menu

[Philip Kaludercic]

Howard Melman <hmelman@gmail.com> writes:

> On Oct 16, 2022, at 12:01 PM, Philip Kaludercic <philipk@posteo.net>
> wrote:
>> 
>> Howard Melman <hmelman@gmail.com> writes:
>> 
>>> A few comments on the text.
>>> 
>>> In Window I think C-x 0 should be called kill (or close)
>>> because that what it does to the window, and this is
>>> meaningful if there is more than 2 windows in the frame.
>>> Kill matches the usage in Buffer.  And perhaps C-x 1 should
>>> be labeled "kill others".
>>> 
>>> Also I think C-x o should be called switch just like C-x b
>>> in Buffer.
>>> 
>>> In Mark & Kill I would put Kill Line first so that the mark
>>> command is closer to the region and yank commands.
>>> 
>>> Finally the text for C-x C-c is "exit" in the File column
>>> and I don't think that's clear enough that it exits emacs
>>> and not just a file.  I know there isn't room to add emacs
>>> but maybe "quit" is clearer as quitting a file makes less
>>> sense (IMHO) than exiting one.
>> 
>> The contents of the help buffer are specified by the
>> `help-quick-sections' variable in lisp/help.el.  Feel free to prepare a
>> patch with your suggestions, that would make it easier to see how they
>> look like.
>
> I don't build my own emacs and haven't signed papers, so I hope
> my mere comments are understandable and sufficient for consideration.

No problem, here is how the buffer looks like after applying your
suggestions:

--8<---------------cut here---------------start------------->8---
File           Buffer             Window              Mark & Kill          Projects                  Misc.
C-x C-f find   C-x k   kill       C-x 0 kill          C-k     kill line    C-x p p switch            C-x C-c exit
C-x C-w write  C-x b   switch     C-x 1 kill others   C-SPC   mark         C-x p f find file         C-_     undo
C-x C-s save   M-g g   goto line  C-x 2 split vert.   M-w     kill region  C-x p g search            C-s     search
C-x s   all    C-x C-q read only  C-x 3 split horiz.  C-y     yank         C-x p r search & replace  M-%     search & replace
				  C-x o switch        C-x C-x swap         C-x p c compile           M-q     reformat
--8<---------------cut here---------------end--------------->8---

Instead of renaming "C-x C-c" I have moved it over to "Misc." and
removed reverse search.  There is some space under "File" and "Buffer"
now, but I can't think an elementary command that would be a good fit.
Any ideas?

> Howard

Re: Adding a "quick-help" menu

[Howard Melman]

Philip Kaludercic <philipk@posteo.net> writes:

> No problem, here is how the buffer looks like after applying your
> suggestions:
>
> File           Buffer             Window              Mark & Kill          Projects                  Misc.
> C-x C-f find   C-x k   kill       C-x 0 kill          C-k     kill line    C-x p p switch            C-x C-c exit
> C-x C-w write  C-x b   switch     C-x 1 kill others   C-SPC   mark         C-x p f find file         C-_     undo
> C-x C-s save   M-g g   goto line  C-x 2 split vert.   M-w     kill region  C-x p g search            C-s     search
> C-x s   all    C-x C-q read only  C-x 3 split horiz.  C-y     yank         C-x p r search & replace  M-%     search & replace
> 				  C-x o switch        C-x C-x swap         C-x p c compile           M-q     reformat
>

Hmmm, having just seen Lars' image I didn't realize there
was also a Projects and Misc. column.

> Instead of renaming "C-x C-c" I have moved it over to "Misc." and
> removed reverse search.

So I agree C-x C-c makes some sense under Misc, but it is
the only one in that column with an extra key, making it
wider.  I'll not that the actual File menu has C-x C-c in it
and it's labeled Quit, so there's precedent for that too
(the File column here has longer bindings).

Projects should probably be Project to match the plurality
of File, Buffer and Window.

> There is some space under "File" and "Buffer" now, but I
> can't think an elementary command that would be a good
> fit.  Any ideas?

Maybe:

C-x x r rename
C-x x g revert
C-x x n clone
C-x C-j dired

clone is a bit advanced but conceivably interesting for a
newbie.  I'm not sure dired-jump is suitable, but I use it a
lot (way more than the others) and dired is something I
think everyone should find useful.  Maybe it's called
"browse" here?

Researching the above I realize that perhaps C-x C-w should
be called "save as" instead of "write".  That's what it's
called in the File menu.

Lastly I'm not sure if it fits or was considered but as a
newbie I'd appreciate knowing about some prefix keys like

C-h help
M-g goto
M-s search
C-x r rects and registers
C-x 4 windows
C-x 5 frames
C-x x buffers
C-x p projects
C-x t tabs
C-x v version control

particularly with which-key enabled which would easily
offer more help if these are tried (C-h works too).  I'm not
sure all of those are appropriate, but it's what came to mind.

-- 

Howard

RE: [External] : Re: Adding a "quick-help" menu

[Drew Adams]

Well, since someone asked for opinions, and few've been
expressed so far, here's one, FWIW.

I'm not in favor of this quick-help menu - neither the
organization nor the choice of what to present (so much
Project, really?).  Nor even how it's presented (UI).

I particularly don't recommend replacing the usual `C-h q'
with a `C-h q' where `q' doesn't mean "quit".  "Quit or
quick" is not a good idea, IMO.  I vote to keep `q' as
"quit" - here, there, and everywhere, unless there's some
overriding good reason for `q' to do something else.  And
even then, don't give it a "quit-or-<other>" behavior.

More could be said, but that's enough.

I'd recommend that if someone really thinks this is a good
idea then add it to GNU ELPA as a tiny library.  Then see
how much favor and use it gains.  If users, especially new 
users, start to say how much they appreciate it, then
consider melding it into the default UI.  There's no hurry.

Re: Adding a "quick-help" menu

[Stefan Kangas]

Philip Kaludercic <philipk@posteo.net> writes:

>> - I think we should use `help-for-help-header' for the headlines, not
>>   capitalize them, and align them with :align-to.
>
> That can be done.

I note that you did not use the `help-for-help-header' face for the
headlines.  They are also manually aligned, not with :align-to.

I tried with this naive patch, which means that alignment is off, but
the results look promising to me:

diff --git a/lisp/help.el b/lisp/help.el
index 1cfd044db8..3979d772bc 100644
--- a/lisp/help.el
+++ b/lisp/help.el
@@ -197,7 +197,7 @@ help-quick
                         (concat
                          (car section)
                          (make-string (- width (length (car section))) ?\s))
-                        'face 'bold)
+                        'face 'help-for-help-header)
                       ,@(mapcar (lambda (ent)
                                   (format fmt
                                           (propertize

In any case, I don't think using the face `bold' is best here, as that
makes this hard to customize.  I'd prefer a proper defface (whether it
inherits from `help-for-help-header' by default or not).

Re: Adding a "quick-help" menu

[Eli Zaretskii]

> From: Philip Kaludercic <philipk@posteo.net>
> Cc: emacs-devel@gnu.org
> Date: Sun, 16 Oct 2022 22:44:33 +0000
> 
> --8<---------------cut here---------------start------------->8---
> File           Buffer             Window              Mark & Kill          Projects                  Misc.
> C-x C-f find   C-x k   kill       C-x 0 kill          C-k     kill line    C-x p p switch            C-x C-c exit
> C-x C-w write  C-x b   switch     C-x 1 kill others   C-SPC   mark         C-x p f find file         C-_     undo
> C-x C-s save   M-g g   goto line  C-x 2 split vert.   M-w     kill region  C-x p g search            C-s     search
> C-x s   all    C-x C-q read only  C-x 3 split horiz.  C-y     yank         C-x p r search & replace  M-%     search & replace
> 				  C-x o switch        C-x C-x swap         C-x p c compile           M-q     reformat
> --8<---------------cut here---------------end--------------->8---
> 
> Instead of renaming "C-x C-c" I have moved it over to "Misc."

It is IMO wrong to stuff C-x C-c too far from the beginning.  Exiting
an unfamiliar application is a frequent need, and it should ideally be
right at the beginning.

Re: Adding a "quick-help" menu

[Philip Kaludercic]

Eli Zaretskii <eliz@gnu.org> writes:

>> From: Philip Kaludercic <philipk@posteo.net>
>> Cc: emacs-devel@gnu.org
>> Date: Sun, 16 Oct 2022 22:44:33 +0000
>> 
>> --8<---------------cut here---------------start------------->8---
>> File           Buffer             Window              Mark & Kill          Projects                  Misc.
>> C-x C-f find   C-x k   kill       C-x 0 kill          C-k     kill line    C-x p p switch            C-x C-c exit
>> C-x C-w write  C-x b   switch     C-x 1 kill others   C-SPC   mark         C-x p f find file         C-_     undo
>> C-x C-s save   M-g g   goto line  C-x 2 split vert.   M-w     kill region  C-x p g search            C-s     search
>> C-x s   all    C-x C-q read only  C-x 3 split horiz.  C-y     yank         C-x p r search & replace  M-%     search & replace
>> 				  C-x o switch        C-x C-x swap         C-x p c compile           M-q     reformat
>> --8<---------------cut here---------------end--------------->8---
>> 
>> Instead of renaming "C-x C-c" I have moved it over to "Misc."
>
> It is IMO wrong to stuff C-x C-c too far from the beginning.  Exiting
> an unfamiliar application is a frequent need, and it should ideally be
> right at the beginning.

I tend to agree, but it is also true that "File" might be the wrong
section.  Perhaps one should reconsider the order and move "Misc." to
the first column?

Re: Adding a "quick-help" menu

[Philip Kaludercic]

Stefan Kangas <stefankangas@gmail.com> writes:

> Philip Kaludercic <philipk@posteo.net> writes:
>
>>> - I think we should use `help-for-help-header' for the headlines, not
>>>   capitalize them, and align them with :align-to.
>>
>> That can be done.
>
> I note that you did not use the `help-for-help-header' face for the
> headlines.  They are also manually aligned, not with :align-to.
>
> I tried with this naive patch, which means that alignment is off, but
> the results look promising to me:
>
> diff --git a/lisp/help.el b/lisp/help.el
> index 1cfd044db8..3979d772bc 100644
> --- a/lisp/help.el
> +++ b/lisp/help.el
> @@ -197,7 +197,7 @@ help-quick
>                          (concat
>                           (car section)
>                           (make-string (- width (length (car section))) ?\s))
> -                        'face 'bold)
> +                        'face 'help-for-help-header)
>                        ,@(mapcar (lambda (ent)
>                                    (format fmt
>                                            (propertize
>
> In any case, I don't think using the face `bold' is best here, as that
> makes this hard to customize.  I'd prefer a proper defface (whether it
> inherits from `help-for-help-header' by default or not).

FWIW I totally agree, and that was just forgetfulness on my part.  As to
:align-to, I believe I already explained that it was difficult to make
use of the property considering the manner in which the buffer is
prepared.

Re: Adding a "quick-help" menu

[Eli Zaretskii]

> From: Philip Kaludercic <philipk@posteo.net>
> Cc: hmelman@gmail.com,  emacs-devel@gnu.org
> Date: Mon, 17 Oct 2022 06:29:59 +0000
> 
> Eli Zaretskii <eliz@gnu.org> writes:
> 
> >> From: Philip Kaludercic <philipk@posteo.net>
> >> Cc: emacs-devel@gnu.org
> >> Date: Sun, 16 Oct 2022 22:44:33 +0000
> >> 
> >> --8<---------------cut here---------------start------------->8---
> >> File           Buffer             Window              Mark & Kill          Projects                  Misc.
> >> C-x C-f find   C-x k   kill       C-x 0 kill          C-k     kill line    C-x p p switch            C-x C-c exit
> >> C-x C-w write  C-x b   switch     C-x 1 kill others   C-SPC   mark         C-x p f find file         C-_     undo
> >> C-x C-s save   M-g g   goto line  C-x 2 split vert.   M-w     kill region  C-x p g search            C-s     search
> >> C-x s   all    C-x C-q read only  C-x 3 split horiz.  C-y     yank         C-x p r search & replace  M-%     search & replace
> >> 				  C-x o switch        C-x C-x swap         C-x p c compile           M-q     reformat
> >> --8<---------------cut here---------------end--------------->8---
> >> 
> >> Instead of renaming "C-x C-c" I have moved it over to "Misc."
> >
> > It is IMO wrong to stuff C-x C-c too far from the beginning.  Exiting
> > an unfamiliar application is a frequent need, and it should ideally be
> > right at the beginning.
> 
> I tend to agree, but it is also true that "File" might be the wrong
> section.

"File" is not too bad because most applications have "Exit" or "Quit"
on their File menu.

We don't have to put Exit on File, but we should not stash it too far
from the beginning, IMO.

> Perhaps one should reconsider the order and move "Misc." to
> the first column?

I would call it "Edit" instead of "Misc", and I would have it be the
2nd or the 3rd column.

Re: Adding a "quick-help" menu

[Stefan Kangas]

Philip Kaludercic <philipk@posteo.net> writes:

> I tend to agree, but it is also true that "File" might be the wrong
> section.  Perhaps one should reconsider the order and move "Misc." to
> the first column?

Or File as the first, and Misc as the second?

OTOH, the "File" menu usually has "Quit" in it, so maybe it's fine to
keep it there but move it to the bottom?

Re: Adding a "quick-help" menu

[Howard Melman]

On Oct 17, 2022, at 3:12 AM, Stefan Kangas <stefankangas@gmail.com> wrote:
> 
> Philip Kaludercic <philipk@posteo.net> writes:
> 
>> I tend to agree, but it is also true that "File" might be the wrong
>> section.  Perhaps one should reconsider the order and move "Misc." to
>> the first column?
> 
> Or File as the first, and Misc as the second?
> 
> OTOH, the "File" menu usually has "Quit" in it, so maybe it's fine to
> keep it there but move it to the bottom?

I would leave it in the File menu and call it Quit.  

In most apps it's found in the file menu and in this case the width
of the keybindings works out.

Howard

Re: Adding a "quick-help" menu

[Protesilaos Stavrou]

> From: Philip Kaludercic <philipk@posteo.net>
> Date: Mon, 17 Oct 2022 06:31:02 +0000
>
> Stefan Kangas <stefankangas@gmail.com> writes:
>
>> Philip Kaludercic <philipk@posteo.net> writes:
>>
>>>> - I think we should use `help-for-help-header' for the headlines, not
>>>>   capitalize them, and align them with :align-to.
>>>
>>> That can be done.
>>
>> I note that you did not use the `help-for-help-header' face for the
>> headlines.  They are also manually aligned, not with :align-to.
>>
>> I tried with this naive patch, which means that alignment is off, but
>> the results look promising to me:
>>
>> diff --git a/lisp/help.el b/lisp/help.el
>> index 1cfd044db8..3979d772bc 100644
>> --- a/lisp/help.el
>> +++ b/lisp/help.el
>> @@ -197,7 +197,7 @@ help-quick
>>                          (concat
>>                           (car section)
>>                           (make-string (- width (length (car section))) ?\s))
>> -                        'face 'bold)
>> +                        'face 'help-for-help-header)
>>                        ,@(mapcar (lambda (ent)
>>                                    (format fmt
>>                                            (propertize
>>
>> In any case, I don't think using the face `bold' is best here, as that
>> makes this hard to customize.  I'd prefer a proper defface (whether it
>> inherits from `help-for-help-header' by default or not).
>
> FWIW I totally agree, and that was just forgetfulness on my part.  As to
> :align-to, I believe I already explained that it was difficult to make
> use of the property considering the manner in which the buffer is
> prepared.

Thanks for doing this!

The format notwithstanding, C-h q could also be mentioned in the
TUTORIAL, no?

I can suggest a patch for it and then do the translation at least for
the Greek version.

-- 
Protesilaos Stavrou
https://protesilaos.com

Re: Adding a "quick-help" menu

[Eli Zaretskii]

> From: Protesilaos Stavrou <info@protesilaos.com>
> Cc: Lars Ingebrigtsen <larsi@gnus.org>, emacs-devel@gnu.org
> Date: Thu, 20 Oct 2022 08:58:09 +0300
> 
> The format notwithstanding, C-h q could also be mentioned in the
> TUTORIAL, no?

I'm not sure, FWIW.  Why is it important to have "C-h q" in the
tutorial?  We only show a handful of Help commands there, and we do
that for a reason.

Re: Adding a "quick-help" menu

[Philip Kaludercic]

Eli Zaretskii <eliz@gnu.org> writes:

>> From: Protesilaos Stavrou <info@protesilaos.com>
>> Cc: Lars Ingebrigtsen <larsi@gnus.org>, emacs-devel@gnu.org
>> Date: Thu, 20 Oct 2022 08:58:09 +0300
>> 
>> The format notwithstanding, C-h q could also be mentioned in the
>> TUTORIAL, no?
>
> I'm not sure, FWIW.  Why is it important to have "C-h q" in the
> tutorial?  We only show a handful of Help commands there, and we do
> that for a reason.

I could imagine that something along the lines of "If you find it
difficult to remember the important bindings, you can always request an
overview with C-h q".

Re: Adding a "quick-help" menu

[Eli Zaretskii]

> From: Philip Kaludercic <philipk@posteo.net>
> Cc: Protesilaos Stavrou <info@protesilaos.com>,  stefankangas@gmail.com,
>   larsi@gnus.org,  emacs-devel@gnu.org
> Date: Thu, 20 Oct 2022 11:27:34 +0000
> 
> Eli Zaretskii <eliz@gnu.org> writes:
> 
> >> From: Protesilaos Stavrou <info@protesilaos.com>
> >> Cc: Lars Ingebrigtsen <larsi@gnus.org>, emacs-devel@gnu.org
> >> Date: Thu, 20 Oct 2022 08:58:09 +0300
> >> 
> >> The format notwithstanding, C-h q could also be mentioned in the
> >> TUTORIAL, no?
> >
> > I'm not sure, FWIW.  Why is it important to have "C-h q" in the
> > tutorial?  We only show a handful of Help commands there, and we do
> > that for a reason.
> 
> I could imagine that something along the lines of "If you find it
> difficult to remember the important bindings, you can always request an
> overview with C-h q".

There are more important C-h bindings than that, if we think we should
have more in the tutorial.

I think we should see how helpful this new binding is before we decide
it is a good addition to the tutorial.  We've just added it a few days
ago.

Re: Adding a "quick-help" menu

[Philip Kaludercic]

Eli Zaretskii <eliz@gnu.org> writes:

>> From: Philip Kaludercic <philipk@posteo.net>
>> Cc: Protesilaos Stavrou <info@protesilaos.com>,  stefankangas@gmail.com,
>>   larsi@gnus.org,  emacs-devel@gnu.org
>> Date: Thu, 20 Oct 2022 11:27:34 +0000
>> 
>> Eli Zaretskii <eliz@gnu.org> writes:
>> 
>> >> From: Protesilaos Stavrou <info@protesilaos.com>
>> >> Cc: Lars Ingebrigtsen <larsi@gnus.org>, emacs-devel@gnu.org
>> >> Date: Thu, 20 Oct 2022 08:58:09 +0300
>> >> 
>> >> The format notwithstanding, C-h q could also be mentioned in the
>> >> TUTORIAL, no?
>> >
>> > I'm not sure, FWIW.  Why is it important to have "C-h q" in the
>> > tutorial?  We only show a handful of Help commands there, and we do
>> > that for a reason.
>> 
>> I could imagine that something along the lines of "If you find it
>> difficult to remember the important bindings, you can always request an
>> overview with C-h q".
>
> There are more important C-h bindings than that, if we think we should
> have more in the tutorial.

Out of curiosity, what do you think these should be?

> I think we should see how helpful this new binding is before we decide
> it is a good addition to the tutorial.  We've just added it a few days
> ago.

This sounds good to me.

Re: Adding a "quick-help" menu

[Eli Zaretskii]

> From: Philip Kaludercic <philipk@posteo.net>
> Cc: info@protesilaos.com,  stefankangas@gmail.com,  larsi@gnus.org,
>   emacs-devel@gnu.org
> Date: Thu, 20 Oct 2022 16:37:31 +0000
> 
> Eli Zaretskii <eliz@gnu.org> writes:
> 
> > There are more important C-h bindings than that, if we think we should
> > have more in the tutorial.
> 
> Out of curiosity, what do you think these should be?

"C-h m" and "C-h v" come to mind.