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

[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

[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.

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

[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

[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: 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: 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
--
 -... --- .-. . -.. ..--.. ...-.-

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: 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: 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: 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: 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: 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: 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: 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: 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

[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: 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: [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: 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]

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]

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

`keysee.el' uses buffer *Completions*.

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: 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

[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

[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

[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: 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

[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 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

[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

[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: [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

[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

[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: 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: 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]

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: 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

[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: 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

[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

[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:

> 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

[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

[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

[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

[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

[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.

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

Making Emacs popular again with a video

[Nathan Colinet]

Hello,

I read on the mailing list that you're looking for a way to make Emacs 
popular again. I thought I could share my idea.

I started using emacs a year ago and when I started everything was 
really confusing, what is a frame, what is a buffer, how to install 
packages, what are major and minor modes, etc.. I wanted to give up but 
then I saw a 1 hour talk about Emacs that shows how powerful it is. Then 
I was hooked. Unfortunately the sound was no good at all and it was way 
too long. I think it could be really benefic for emacs to have a 5-10 
minutes video that would present Emacs not as an old obscure porgram but 
as an amazing fresh looking tool that drastically improves efficiency. I 
think people nowadays need an out-of-the-box experience, that's why 
promoting doom-emacs or spacemacs might be better than the default Emacs.

I think if the video is well realised it could really be a huge win.

Stay safe and well,

Nathan Colinet

Re: Making Emacs popular again with a video

[Andreas Röhler]

Am 08.05.20 um 10:26 schrieb Nathan Colinet:
> Hello,
> 
> I read on the mailing list that you're looking for a way to make Emacs 
> popular again. I thought I could share my idea.
> 
> I started using emacs a year ago and when I started everything was 
> really confusing, what is a frame, what is a buffer, how to install 
> packages, what are major and minor modes, etc.. I wanted to give up but 
> then I saw a 1 hour talk about Emacs that shows how powerful it is. Then 
> I was hooked. Unfortunately the sound was no good at all and it was way 
> too long. I think it could be really benefic for emacs to have a 5-10 
> minutes video that would present Emacs not as an old obscure porgram but 
> as an amazing fresh looking tool that drastically improves efficiency. I 
> think people nowadays need an out-of-the-box experience, that's why 
> promoting doom-emacs or spacemacs might be better than the default Emacs.
> 
> I think if the video is well realised it could really be a huge win.
> 
> Stay safe and well,
> 
> Nathan Colinet
> 
> 
> 

Hi,

thanks bringing that up. Agree such a video might be helpful. The 
reasons however, why Emacs is a kind of niche nowadays are multiple and 
complex. Leaving apart all items Emacs itself can't change, there is 
something which can be done IMO: making Emacs ready for a beginner in 
programming resp. for non-programmers. Make Emacs appear mannerly as 
just an editor first. Which also means: at the beginning leave apart all 
complex stuff useful for advanced programmers only.

For instance at "Introduction" fairly everything in first paragraphs 
IMHO may be dropped resp. should be moved at later sections. Copy stuff 
below for the convenience of the reader here.

All the day enjoying Emacs,
Andreas

Copy:

Introduction
************

You are reading about GNU Emacs, the GNU incarnation of the advanced,
self-documenting, customizable, extensible editor Emacs.  (The ‘G’ in
GNU (GNU’s Not Unix) is not silent.)

    We call Emacs “advanced” because it can do much more than simple
insertion and deletion of text.  It can control subprocesses, indent
programs automatically, show multiple files at once, edit remote files
like they were local files, and more.  Emacs editing commands operate in
terms of characters, words, lines, sentences, paragraphs, and pages, as
well as expressions and comments in various programming languages.

    “Self-documenting” means that at any time you can use special
commands, known as “help commands”, to find out what your options are,
or to find out what any command does, or to find all the commands that
pertain to a given topic.  *Note Help::.

    “Customizable” means that you can easily alter the behavior of Emacs
commands in simple ways.  For instance, if you use a programming
language in which comments start with ‘<**’ and end with ‘**>’, you can
tell the Emacs comment manipulation commands to use those strings (*note
Comments::).  To take another example, you can rebind the basic cursor
motion commands (up, down, left and right) to any keys on the keyboard
that you find comfortable.  *Note Customization::.

Re: Making Emacs popular again with a video

[Nathan Colinet]

Hi,

I agree that's too advanced for a beginner user.

On 2020-05-09 09:50, Andreas Röhler wrote:
>
>
> Am 08.05.20 um 10:26 schrieb Nathan Colinet:
>> Hello,
>>
>> I read on the mailing list that you're looking for a way to make 
>> Emacs popular again. I thought I could share my idea.
>>
>> I started using emacs a year ago and when I started everything was 
>> really confusing, what is a frame, what is a buffer, how to install 
>> packages, what are major and minor modes, etc.. I wanted to give up 
>> but then I saw a 1 hour talk about Emacs that shows how powerful it 
>> is. Then I was hooked. Unfortunately the sound was no good at all and 
>> it was way too long. I think it could be really benefic for emacs to 
>> have a 5-10 minutes video that would present Emacs not as an old 
>> obscure porgram but as an amazing fresh looking tool that drastically 
>> improves efficiency. I think people nowadays need an out-of-the-box 
>> experience, that's why promoting doom-emacs or spacemacs might be 
>> better than the default Emacs.
>>
>> I think if the video is well realised it could really be a huge win.
>>
>> Stay safe and well,
>>
>> Nathan Colinet
>>
>>
>>
>
> Hi,
>
> thanks bringing that up. Agree such a video might be helpful. The 
> reasons however, why Emacs is a kind of niche nowadays are multiple 
> and complex. Leaving apart all items Emacs itself can't change, there 
> is something which can be done IMO: making Emacs ready for a beginner 
> in programming resp. for non-programmers. Make Emacs appear mannerly 
> as just an editor first. Which also means: at the beginning leave 
> apart all complex stuff useful for advanced programmers only.
>
> For instance at "Introduction" fairly everything in first paragraphs 
> IMHO may be dropped resp. should be moved at later sections. Copy 
> stuff below for the convenience of the reader here.
>
> All the day enjoying Emacs,
> Andreas
>
> Copy:
>
> Introduction
> ************
>
> You are reading about GNU Emacs, the GNU incarnation of the advanced,
> self-documenting, customizable, extensible editor Emacs.  (The ‘G’ in
> GNU (GNU’s Not Unix) is not silent.)
>
>    We call Emacs “advanced” because it can do much more than simple
> insertion and deletion of text.  It can control subprocesses, indent
> programs automatically, show multiple files at once, edit remote files
> like they were local files, and more.  Emacs editing commands operate in
> terms of characters, words, lines, sentences, paragraphs, and pages, as
> well as expressions and comments in various programming languages.
>
>    “Self-documenting” means that at any time you can use special
> commands, known as “help commands”, to find out what your options are,
> or to find out what any command does, or to find all the commands that
> pertain to a given topic.  *Note Help::.
>
>    “Customizable” means that you can easily alter the behavior of Emacs
> commands in simple ways.  For instance, if you use a programming
> language in which comments start with ‘<**’ and end with ‘**>’, you can
> tell the Emacs comment manipulation commands to use those strings (*note
> Comments::).  To take another example, you can rebind the basic cursor
> motion commands (up, down, left and right) to any keys on the keyboard
> that you find comfortable.  *Note Customization::.
>

Re: Making Emacs popular again with a video

[Richard Stallman]

[[[ To any NSA and FBI agents reading my email: please consider    ]]]
[[[ whether defending the US Constitution against all enemies,     ]]]
[[[ foreign or domestic, requires you to follow Snowden's example. ]]]

  > > For instance at "Introduction" fairly everything in first paragraphs 
  > > IMHO may be dropped resp. should be moved at later sections. Copy 
  > > stuff below for the convenience of the reader here.

Perhaps there is no longer a need to inform the public of those
three basic capabilities of Emacs.

Do Emacs's current competitors have the same capabilities?

    > You are reading about GNU Emacs, the GNU incarnation of the advanced,
    > self-documenting, customizable, extensible editor Emacs. 
-- 
Dr Richard Stallman
Chief GNUisance of the GNU Project (https://gnu.org)
Founder, Free Software Foundation (https://fsf.org)
Internet Hall-of-Famer (https://internethalloffame.org)

GNU Emacs raison d'etre

[excalamus--- via Emacs development discussions.]

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

May 11, 2020, 23:12 by rms@gnu.org:

> Perhaps there is no longer a need to inform the public of those
> three basic capabilities of Emacs.
>
> Do Emacs's current competitors have the same capabilities?
>
> > You are reading about GNU Emacs, the GNU incarnation of the advanced,
> > self-documenting, customizable, extensible editor Emacs. 
>
What are we competing for?  I feel that while other threads are examining "missing features", it would be helpful to examine what GNU Emacs does offer.  Not only in software features, but maybe also in philosophy, community, or tradition.

What is it about GNU Emacs that makes this mailing list bustle with enthusiasm?  Other editors use GPL, provide source code, have documentation, are customizable, and extendable.  There's something in how GNU Emacs implements these that is different.  I feel like there are taters to find if we dig a little.

Is it because Emacs Lisp is unique to Emacs that Emacs teaches as well as documents?
Is it that by being a pseudo-Lisp machine, Emacs puts users in the zone of proximal development?
Is GNU Emacs the best embodiment of the GNU philosophy?  


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

Re: GNU Emacs raison d'etre

[Karl Fogel]

On 12 May 2020, excalamus--- via "Emacs development discussions." wrote:
>May 11, 2020, 23:12 by rms@gnu.org:
>What are we competing for?  I feel that while other threads are
>examining "missing features", it would be helpful to examine what GNU
>Emacs does offer.  Not only in software features, but maybe also in
>philosophy, community, or tradition.
>
>What is it about GNU Emacs that makes this mailing list bustle with
>enthusiasm?  Other editors use GPL, provide source code, have
>documentation, are customizable, and extendable.  There's something
>in how GNU Emacs implements these that is different.  I feel like
>there are taters to find if we dig a little.
>
>Is it because Emacs Lisp is unique to Emacs that Emacs teaches as
>well as documents?
>Is it that by being a pseudo-Lisp machine, Emacs puts users in the
>zone of proximal development?
>Is GNU Emacs the best embodiment of the GNU philosophy? 

Sure, I'll take the bait:

To the best of my knowledge, no other editing environment rewards sustained user investment so well.

With Emacs, if you keep investing -- i.e., acquiring knowledge and skill by reading documentation, writing customizations, and exploring others' customizations -- Emacs keeps rewarding you with a better and better editing experience.  The degree to which it does this seems normal to many of us here, because we've been used to it for many years.  I think we sometimes fail to appreciate the degree to which non-users, potential ("Emacs-curious") users, and even many actual new users are *not* aware of it: they don't realize how enormous the reward can be, and how broad its scope.

This should probably affect how we think about promoting Emacs.  Emacs shouldn't necessarily try to attract everyone who needs to edit text [1].  Many people who edit text nonetheless don't view text editing as a primary activity worthy of investment.  Those users are not good candidates for Emacs.

Emacs's best prospects are with the sorts of people who *do* see -- or who can be persuaded to see -- text editing as worthy of investment.  There's a loose correlation in which good programmers tend to be those sorts of people, because good programmers are usually willing to invest in learning their tools in general.  E.g., they'll learn their text editor the same way they'll learn their debugger, their programming framework, etc.  But the set isn't limited to just programmers.  For example, scientists and other academics who edit LaTeX documents are often good candidates for Emacs usage, because by both temperament and life situation they are well-positioned to understand how sustained investment in learning their editing environment could pay off in the long term.

So I suggest that GNU Emacs's raison d'être is to be the text editor that best rewards sustained user investment.

I think Emacs actually does so right now, too, and that we just haven't always communicated this fact clearly enough.

Thus, instead of focusing on making Emacs easier for new users, it would be better to focus on smoothing out discontinuities in Emacs' investment-reward curve.  The long-term health of Emacs as a project will not come from a large number of lightly committed users who don't appreciate what makes Emacs unique, but rather from a smaller number of users for whom Emacs is important and irreplaceable.

I'm not suggesting that we shouldn't improve the new-user experience in Emacs, of course.  We should make it as easy as possible for newcomers *while still prioritizing invested users*.   In user experience design, there are frequently tradeoffs between making things easy for newcomers and making them rewarding for experts.  Unfortunately, too often in design discussions, the new user experience automatically wins out -- it's like some kind of magic card that people play (even sometimes unconsciously) in UI/UX discussions.  For Emacs, this would be a mistake.  Emacs's great strength will never be in its new-user experience, and this is in some ways a necessary consequence of Emacs being so great for highly invested long-term users.

This also suggests that the sorts of features that highly-invested users tend to want -- for example, LSP-based features -- should be more important to us than how square the menus are or what menu items are shown in a default startup configuration.  When we make decisions that disappoint the core user base, we endanger the project much more than when we make decisions that disappoint users (or potential users) who weren't likely to become highly invested anyway.

(The fact that Emacs promotes free software by being a good GPL'd program is nice too, and is important to many of us, but it's not unique to Emacs.)

Best regards,
-Karl

Re: GNU Emacs raison d'etre

[Andreas Röhler]

On 13.05.20 18:18, Karl Fogel wrote:
> On 12 May 2020, excalamus--- via "Emacs development discussions." wrote:
>> May 11, 2020, 23:12 by rms@gnu.org:
>> What are we competing for?  I feel that while other threads are
>> examining "missing features", it would be helpful to examine what GNU
>> Emacs does offer.  Not only in software features, but maybe also in
>> philosophy, community, or tradition.
>>
>> What is it about GNU Emacs that makes this mailing list bustle with
>> enthusiasm?  Other editors use GPL, provide source code, have
>> documentation, are customizable, and extendable.  There's something
>> in how GNU Emacs implements these that is different.  I feel like
>> there are taters to find if we dig a little.
>>
>> Is it because Emacs Lisp is unique to Emacs that Emacs teaches as
>> well as documents?
>> Is it that by being a pseudo-Lisp machine, Emacs puts users in the
>> zone of proximal development?
>> Is GNU Emacs the best embodiment of the GNU philosophy?
> Sure, I'll take the bait:
>
> To the best of my knowledge, no other editing environment rewards sustained user investment so well.
>
> With Emacs, if you keep investing -- i.e., acquiring knowledge and skill by reading documentation, writing customizations, and exploring others' customizations -- Emacs keeps rewarding you with a better and better editing experience.  The degree to which it does this seems normal to many of us here, because we've been used to it for many years.  I think we sometimes fail to appreciate the degree to which non-users, potential ("Emacs-curious") users, and even many actual new users are *not* aware of it: they don't realize how enormous the reward can be, and how broad its scope.
>
> This should probably affect how we think about promoting Emacs.  Emacs shouldn't necessarily try to attract everyone who needs to edit text [1].  Many people who edit text nonetheless don't view text editing as a primary activity worthy of investment.  Those users are not good candidates for Emacs.
>
> Emacs's best prospects are with the sorts of people who *do* see -- or who can be persuaded to see -- text editing as worthy of investment.  There's a loose correlation in which good programmers tend to be those sorts of people, because good programmers are usually willing to invest in learning their tools in general.  E.g., they'll learn their text editor the same way they'll learn their debugger, their programming framework, etc.  But the set isn't limited to just programmers.  For example, scientists and other academics who edit LaTeX documents are often good candidates for Emacs usage, because by both temperament and life situation they are well-positioned to understand how sustained investment in learning their editing environment could pay off in the long term.
>
> So I suggest that GNU Emacs's raison d'être is to be the text editor that best rewards sustained user investment.
>
> I think Emacs actually does so right now, too, and that we just haven't always communicated this fact clearly enough.
>
> Thus, instead of focusing on making Emacs easier for new users, it would be better to focus on smoothing out discontinuities in Emacs' investment-reward curve.  The long-term health of Emacs as a project will not come from a large number of lightly committed users who don't appreciate what makes Emacs unique, but rather from a smaller number of users for whom Emacs is important and irreplaceable.
>
> I'm not suggesting that we shouldn't improve the new-user experience in Emacs, of course.  We should make it as easy as possible for newcomers *while still prioritizing invested users*.   In user experience design, there are frequently tradeoffs between making things easy for newcomers and making them rewarding for experts.  Unfortunately, too often in design discussions, the new user experience automatically wins out -- it's like some kind of magic card that people play (even sometimes unconsciously) in UI/UX discussions.  For Emacs, this would be a mistake.  Emacs's great strength will never be in its new-user experience, and this is in some ways a necessary consequence of Emacs being so great for highly invested long-term users.

Agree with everything beside two last paragraphs. Enjoying the 
possibilities to extend and assisting new users being productive seems 
no contradiction. May you give an example where an smooth entrance 
hinders the power of more complex functionality?

Sure, as it was mentioned in other post, writing an introduction for 
beginners is difficult, it is an art of its own.


>
> This also suggests that the sorts of features that highly-invested users tend to want -- for example, LSP-based features -- should be more important to us than how square the menus are or what menu items are shown in a default startup configuration.  When we make decisions that disappoint the core user base, we endanger the project much more than when we make decisions that disappoint users (or potential users) who weren't likely to become highly invested anyway.
>
> (The fact that Emacs promotes free software by being a good GPL'd program is nice too, and is important to many of us, but it's not unique to Emacs.)
>
> Best regards,
> -Karl
>

Re: GNU Emacs raison d'etre

[Karl Fogel]

On 13 May 2020, Andreas Röhler wrote:
>Agree with everything beside two last paragraphs. Enjoying the
>possibilities to extend and assisting new users being productive seems 
>no contradiction. May you give an example where an smooth entrance
>hinders the power of more complex functionality?

The newcomer-vs-expert tradeoff is real, and it's pervasive throughout UI and UX design.

One example is button-based functionality.  For both experts and newcomers, those buttons/icons take away screen real estate -- but for newcomers they make features easier to find, so it's worth it.  For experts, they *just* take away screen real estate, while providing little or no benefit.

Use of small symbols to indicate state in the modeline is another area.  Experienced users know what "**" in the mode line means, what "%" means, etc.  Newcomers are frequently confused by the mode line; it is noise to them, until they know how to interpret it -- but that takes a bit of investment.  Now, we could provide bigger, more verbose signs of current state -- but then we'd be taking away screen real estate again.

Another area is the keybinding space and the minibuffer.  Just about every time I have watched a new user use Emacs, I have noticed how frequently they accidentally hit some key combination or sequence and wind up in some weird state that they never meant to be in -- and don't know how to get out of.  Often they have minibuffer prompts sitting around all the time, and are unaware that Emacs is asking them for some piece of information (after all, the user didn't mean to put Emacs into that state and has no idea she did so).  But having those keybindings available is *good* for experts, as we know from personal experience.

I could go on.  I've taught many newcomers to Emacs, and often the things that are hardest for them are exactly the things that are *good* for the experienced user.

These design tradeoffs cannot be avoided.  It would be a fallacy to think that it's always possible to be *both* maximally newcomer-friendly and investor-friendly.  

(The term "user-friendly" is itself misleading.  There is no such thing as "a user" in a way that makes the term "user-friendly" meaningful.  Better terms would at least attempt to make important distinctions -- "newcomer-friendly", "expert-friendly", "ADHD-friendly", "limited-movement-friendly", "visually-impaired-friendly", etc -- and would encourage designers to understand that being good in some categories means being bad in others.)

Best regards,
-Karl

Re: GNU Emacs raison d'etre

[Dmitry Gutov]

On 13.05.2020 23:05, Karl Fogel wrote:
> Use of small symbols to indicate state in the modeline is another area.  Experienced users know what "**" in the mode line means, what "%" means, etc.  Newcomers are frequently confused by the mode line; it is noise to them, until they know how to interpret it -- but that takes a bit of investment.  Now, we could provide bigger, more verbose signs of current state -- but then we'd be taking away screen real estate again.
> 
> Another area is the keybinding space and the minibuffer.  Just about every time I have watched a new user use Emacs, I have noticed how frequently they accidentally hit some key combination or sequence and wind up in some weird state that they never meant to be in -- and don't know how to get out of.  Often they have minibuffer prompts sitting around all the time, and are unaware that Emacs is asking them for some piece of information (after all, the user didn't mean to put Emacs into that state and has no idea she did so).  But having those keybindings available is*good*  for experts, as we know from personal experience.

I might with agree with you principle, but both examples seem suspect.

First, the "low investment" editors frequently have higher density of 
information in the UI elements that correspond to our mode-line and 
fringe, margins, etc. Largely thanks to their technical capabilities 
(various-sized fonts, graphics, being able to fit different kinds of 
indicators together on a "fringe"). So it appears at least in this area 
Emacs has been overtaken purely on technical grounds.

Regarding the key combinations and the minibuffer, there is no hard 
evidence that our current behavior is supremely optimal. In fact, I'm 
fairly sure that by being risk-averse and resistant to change, and by 
having no UX experts around, Emacs loses out on some possible 
advancements in usability. Even expert-friendly ones.

So I would recommend not becoming complacent, or becoming assured that 
workflows you have spent some time getting accustomed to, can't be improved.

> I could go on.  I've taught many newcomers to Emacs, and often the things that are hardest for them are exactly the things that are*good*  for the experienced user.
> 
> These design tradeoffs cannot be avoided.  It would be a fallacy to think that it's always possible to be*both*  maximally newcomer-friendly and investor-friendly.

The last sentence is sensible, but it's generally beside the point: I'm 
sure we still have a long way to go in both directions.

And unfortunately, in practice around here "prioritizing invested users" 
somehow turns out to mean "let's not make existing users uncomfortable". 
By changing defaults, introducing new workflows, or changing old ones. 
Which, in the long run, serves neither crowd.

Re: GNU Emacs raison d'etre

[Karl Fogel]

On 13 May 2020, Dmitry Gutov wrote:
>I might with agree with you principle, but both examples seem suspect.
>
>First, the "low investment" editors frequently have higher density of
>information in the UI elements that correspond to our mode-line and 
>fringe, margins, etc. Largely thanks to their technical capabilities
>(various-sized fonts, graphics, being able to fit different kinds of 
>indicators together on a "fringe"). So it appears at least in this
>area Emacs has been overtaken purely on technical grounds.

*nod*.  There might be room for improvement in how Emacs uses various visual areas, though, having watched many different programmers using many different kinds of editors, I think Emacs's mode line actually scores pretty well on the indicator front (once one learns how to interpret it).

But in any case, note that these other editors also face this same tradeoff.  You can see it in Microsoft Word, for example: in recent versions, its default startup control panel looks like the cockpit of Boeing 747.  Experienced users complain noisily about it (you can find various blog posts and other chatter about this on the Net), but this UI change was made so that *new* users could find a visual path to anything they might be looking for.

The tradeoff will always be there, even if sometimes there is room for Emacs to improve -- i.e., room for Emacs to "get to the tradeoff point", so to speak.

>Regarding the key combinations and the minibuffer, there is no hard
>evidence that our current behavior is supremely optimal. In fact, I'm 
>fairly sure that by being risk-averse and resistant to change, and by
>having no UX experts around, Emacs loses out on some possible 
>advancements in usability. Even expert-friendly ones.
>
>So I would recommend not becoming complacent, or becoming assured that
>workflows you have spent some time getting accustomed to, can't be
>improved.

Absolutely.

But the particular *way* in which we've crowded the keybinding space is independent of the fact that the space is crowded, and necessarily must be crowded if it is to offer experts the quick access to functionality that they want.  Crowding the keybinding space is good for high-investment users and bad for newcomers (that's why newcomers to Emacs so often trip accidentally over unexpectedly combustible key sequences).  That tradeoff will always be there, no matter what the particular mapping of key sequences to functionality is.

So I think my example there holds up pretty well.

>> I could go on.  I've taught many newcomers to Emacs, and often the things that are hardest for them are exactly the things that are*good*  for the experienced user.
>> These design tradeoffs cannot be avoided.  It would be a fallacy to
>> think that it's always possible to be*both*  maximally
>> newcomer-friendly and investor-friendly.
>
>The last sentence is sensible, but it's generally beside the point:
>I'm sure we still have a long way to go in both directions.

Very good point: there are some things we could that would get us closer to the point where tradeoff decisions are necessary.  But not everything we contemplate doing will be in that category.  Some of the things we want to do will already *be* at the tradeoff point, and then we will have a decision to make.

>> This also suggests that the sorts of features that highly-invested
>> users tend to want -- for example, LSP-based features
>
>LSP is a high-investment feature?
>
>Reminder: it came to us from VS Code, Microsoft's text editor for
>programmers.

Not quite.  What I wrote, exactly, is that it is the sort of feature that highly-invested users tend to want.  That is different in a subtle way.  By not supplying the sorts of things that LSP would enable, we signal to high-investment users that there is an entire area of improvement that Emacs is not going to explore.  So while lack of LSP hurts both newcomers and experts, it discourages the experts more, because they are looking for signals that continued investment will lead to increased reward.

Put another way: LSP is the sort of thing that enables highly-invested users -- the kinds of people who write or would consider writing Elisp -- to build new functionality into Emacs, perhaps even functionality we cannot predict today.  While LSP is a good thing for all users, newcomers and experts alike, it specifically *rewards* further investment by users who are motivated to make (and capable of making) investments based on LSP's availability.  It is an expertise amplifier.  When we fail to include an expertise amplifier like that, we "bend the curve" -- in the wrong direction.

Best regards,
-Karl

Re: GNU Emacs raison d'etre

[Dmitry Gutov]

On 14.05.2020 01:04, Karl Fogel wrote:
> On 13 May 2020, Dmitry Gutov wrote:
>> I might with agree with you principle, but both examples seem suspect.
>>
>> First, the "low investment" editors frequently have higher density of
>> information in the UI elements that correspond to our mode-line and
>> fringe, margins, etc. Largely thanks to their technical capabilities
>> (various-sized fonts, graphics, being able to fit different kinds of
>> indicators together on a "fringe"). So it appears at least in this
>> area Emacs has been overtaken purely on technical grounds.
> 
> *nod*.  There might be room for improvement in how Emacs uses various visual areas, though, having watched many different programmers using many different kinds of editors, I think Emacs's mode line actually scores pretty well on the indicator front (once one learns how to interpret it).

I think the mode-line is more or less average by today's standards. But 
of course it wins on customizability. The fringes a significantly less 
functional, though. :-(

> But in any case, note that these other editors also face this same tradeoff.  You can see it in Microsoft Word, for example: in recent versions, its default startup control panel looks like the cockpit of Boeing 747.  Experienced users complain noisily about it (you can find various blog posts and other chatter about this on the Net), but this UI change was made so that *new* users could find a visual path to anything they might be looking for.
> 
> The tradeoff will always be there, even if sometimes there is room for Emacs to improve -- i.e., room for Emacs to "get to the tradeoff point", so to speak.

Yes, the tradeoff is somewhere in there, but my problem with the 
conclusion is that it would be really easy to misapply your principle 
(e.g. by saying we don't need fancier buttons, even though we probably 
do, or that the Getting Started guide is good enough and doesn't need 
improvement, and someone should go work on specialized Org-mode docs 
instead).

Making good use of it seems difficult.

The kind of person who *could* make a better judgment in this area is 
someone who specializes on UX. And they are rare guests around here.

> But the particular *way* in which we've crowded the keybinding space is independent of the fact that the space is crowded, and necessarily must be crowded if it is to offer experts the quick access to functionality that they want.  Crowding the keybinding space is good for high-investment users and bad for newcomers (that's why newcomers to Emacs so often trip accidentally over unexpectedly combustible key sequences).  That tradeoff will always be there, no matter what the particular mapping of key sequences to functionality is.

Are you sure that this particular aspect is _bad_ for new users, though? 
Nobody likes to stretch they hand too far. But I'll grant you this 
point, that Emacs is *somewhat* on the side of high-investment here.

This part is expected of a professional tool, however, and the 
experience for newcomers could be improved without taking away much from 
the "oldies". See the 'transient' package, for example, recently 
proposed for inclusion on emacs-devel.

>>> I could go on.  I've taught many newcomers to Emacs, and often the things that are hardest for them are exactly the things that are*good*  for the experienced user.
>>> These design tradeoffs cannot be avoided.  It would be a fallacy to
>>> think that it's always possible to be*both*  maximally
>>> newcomer-friendly and investor-friendly.
>>
>> The last sentence is sensible, but it's generally beside the point:
>> I'm sure we still have a long way to go in both directions.
> 
> Very good point: there are some things we could that would get us closer to the point where tradeoff decisions are necessary.  But not everything we contemplate doing will be in that category.  Some of the things we want to do will already *be* at the tradeoff point, and then we will have a decision to make.

Some of them, probably. At this point, I think, there are still a lot of 
decisions that would bring us closer to newcomer-friendliness while 
keeping no worse high-investment compatibility.

>>> This also suggests that the sorts of features that highly-invested
>>> users tend to want -- for example, LSP-based features
>>
>> LSP is a high-investment feature?
>>
>> Reminder: it came to us from VS Code, Microsoft's text editor for
>> programmers.
> 
> Not quite.  What I wrote, exactly, is that it is the sort of feature that highly-invested users tend to want.  That is different in a subtle way.  By not supplying the sorts of things that LSP would enable, we signal to high-investment users that there is an entire area of improvement that Emacs is not going to explore.  So while lack of LSP hurts both newcomers and experts, it discourages the experts more, because they are looking for signals that continued investment will lead to increased reward.

I'm glad that we both like LSP, or at least the idea of it.

But it seems these days almost everybody wants it, except for MS Word 
and Notepad users.

> Put another way: LSP is the sort of thing that enables highly-invested users -- the kinds of people who write or would consider writing Elisp -- to build new functionality into Emacs, perhaps even functionality we cannot predict today.  While LSP is a good thing for all users, newcomers and experts alike, it specifically *rewards* further investment by users who are motivated to make (and capable of making) investments based on LSP's availability.  It is an expertise amplifier.  When we fail to include an expertise amplifier like that, we "bend the curve" -- in the wrong direction.

There are certain aspects where LSP is not exactly perfect: the 
functionality it allows is limited by the protocol, and by LSP servers 
available currently. It's an "ecosystem amplifier", or maybe an 
equalizer even.

I mean, it for sure is great, not to be lagging in language support for 
a whole number of languages where we did before. But there are different 
protocols that allow more powerful extensibility. nREPL, for example.

Re: GNU Emacs raison d'etre

[Karl Fogel]

On 14 May 2020, Dmitry Gutov wrote:
>Yes, the tradeoff is somewhere in there, but my problem with the
>conclusion is that it would be really easy to misapply your principle 
>(e.g. by saying we don't need fancier buttons, even though we probably
>do, or that the Getting Started guide is good enough and doesn't need 
>improvement, and someone should go work on specialized Org-mode docs
>instead).
>
>Making good use of it seems difficult.

Any guiding principle can be misused, but that doesn't make it useless.

The particular misuses you cite above are speculative -- no one's actually saying those things, as far as I'm aware.

In a reply to Christopher Lemmer Webber just now [1], I got a little bit more specific:

  > If we just say "Emacs should be easier for newcomers to learn",
  > that's not a useful rallying cry IMHO.  If we say instead "Emacs
  > should try to attract newcomers who have a higher-than-average
  > probability of becoming high-investment users, and should explain
  > early on to those newcomers what the road ahead looks like", *then*
  > we have a high-level guiding principle we can actually use.

So there's some concrete guidance about *how* we might seek to improve the Getting Started guide (and other things like the Emacs web site, starter videos, etc):

* Tell newcomers up front that Emacs really starts to be worth it after a few years, not a few weeks.  Set expectations right from the start.

* Show them some of the abilities they will eventually have, so that they can see why it's worth it to make the investment.

* Also tell them about the ways in which Emacs may frustrate them along the way, and explain that those frustrations are common and are sometimes inevitably entangled with the same things that make Emacs winning in the long term.

I find it fairly easy to come up with ways in which this principle would provide guidance in certain decisions.  I could try to list more of those ways, if it would be helpful, but I just don't want to get into a sub-discussion about each such example.  It's meant to be a high-level principle, after all.

Ultimately, I personally find it helpful in thinking about how to teach Emacs and how to write packages.  Here is the principle, reworded slightly after a suggestion from H. Dieter Wilhelm:

"GNU Emacs's raison d'être is to be the text manipulation environment that best rewards sustained user investment."

Apparently some other people here find it useful as well.   You might or might not be one of them, but I can at least promise you that I'll never use this principle to make bad suggestions about ways in which Emacs should be made unfriendly to newcomers :-).

>The kind of person who *could* make a better judgment in this area is
>someone who specializes on UX. And they are rare guests around here.

More UX expertise would always help, naturally, but those of us who are here are not wholly ignorant of the field either, nor of the questions and tradeoffs that need to be dealt with.

>Are you sure that this particular aspect is _bad_ for new users, though?

Yes.  I am sure.

I've taught Emacs to a lot of people -- scores of them, at least; I don't keep track, but the sample size is large enough to be beyond merely anecdotal at this point.  I've watched newcomers run into the same obstacles over and over, and this particular obstacle is always one of the first they encounter.

>Nobody likes to stretch they hand too far. But I'll grant you
>this point, that Emacs is *somewhat* on the side of high-investment
>here.
>
>This part is expected of a professional tool, however, and the
>experience for newcomers could be improved without taking away much
>from the "oldies". See the 'transient' package, for example, recently 
>proposed for inclusion on emacs-devel.

I don't have any experience using 'transient', so I'd need more explanation from you to understand what you meant by that part.  (I tried to understand 'transient' from reading [2] and [3], but unfortunately -- and somewhat surprisingly! -- the documentation at those pages does not give a single concrete example of transient's use.)

However, your assertion that "the experience for newcomers could be improved without taking away much from the 'oldies'" is exactly what I'm arguing is not true.  I actually think we can't (much) improve this particular part of the experience for newcomers without taking away one of the things about Emacs that most rewards investment.

The newcomers who eventually *do* become experts do so in part by first stumbling across new commands accidentally (in that crowded keybinding space) and then using help tools like `C-h l' to see what they just did.  So one of the things we should prioritize is teaching newcomers how important those help facilities are and how to use them in a smart way.  I'm specifically saying that this is *more important for Emacs than it is for other editors*.  Sure, users of (say) the Atom editor should eventually know how to use the built-in help there too.  But it's a difference in prioritization: for Emacs users, using that built-in help is more important than it would be in other editors, and the methods and circumstances of using the help are different too.  So we should incorporate that fact into how we present Emacs to new users.

(Again, this is from at least some experience.  The users I've taught who have gone on to become proficient Emacs users are ones who invested very early in learning the various help facilities and when to use them.)

>Some of them, probably. At this point, I think, there are still a lot
>of decisions that would bring us closer to newcomer-friendliness while 
>keeping no worse high-investment compatibility.

That could be true, though I'm a bit more skeptical than you are.  In any case, it does not make the principle inoperative; it is consistent with the principle.

I believe we'll make better decisions if we keep in mind that "friendly to newcomers" is not, in itself, the primary goal.

>I'm glad that we both like LSP, or at least the idea of it.
>
>But it seems these days almost everybody wants it, except for MS Word
>and Notepad users.

Yes.  High-investment users, however, see more possibilities from LSP than low-investment users do -- they'll go farther with it.

>There are certain aspects where LSP is not exactly perfect: the
>functionality it allows is limited by the protocol, and by LSP servers 
>available currently. It's an "ecosystem amplifier", or maybe an
>equalizer even.
>
>I mean, it for sure is great, not to be lagging in language support
>for a whole number of languages where we did before. But there are
>different protocols that allow more powerful extensibility. nREPL, for
>example.

Ah, that's a technical question about the suitability of LSP for a particular problem space, and I'm not well-informed enough to have a useful opinion there.  If you say nREPL, I'm not going to argue! :-)

Best regards,
-Karl

[1] https://lists.gnu.org/archive/html/emacs-devel/2020-05/msg01893.html

    From: Karl Fogel <kfogel@red-bean.com>
    To: Christopher Lemmer Webber <cwebber@dustycloud.org>
    Cc: ndame <ndame@protonmail.com>,  Emacs developers <emacs-devel@gnu.org>
    Subject: Re: What is the most useful potential feature which Emacs lacks?
    Date: Wed, 13 May 2020 23:08:04 -0500
    Message-ID: <87y2pvqhuj.fsf@red-bean.com>

[2] https://github.com/magit/transient/blob/master/lisp/transient.el

[3] https://emacsair.me/2019/02/14/transient-0.1/

Re: GNU Emacs raison d'etre

[Dmitry Gutov]

On 14.05.2020 07:56, Karl Fogel wrote:

 > Any guiding principle can be misused, but that doesn't make it useless.

 > The particular misuses you cite above are speculative -- no one's
 > actually saying those things, as far as I'm aware.

Actually, those examples are closer to the discussions I have taken 
part in (let's not change xxx because existing users will complain; and 
the newbies will just have to get in line, the entry barrier is high 
anyway, who cares if they have to learn one more thing to get started).

On the flip side, I don't remember anybody propose to make key bindings 
less "staggered".

> In a reply to Christopher Lemmer Webber just now [1], I got a little bit more specific:
> 
>    > If we just say "Emacs should be easier for newcomers to learn",
>    > that's not a useful rallying cry IMHO.  If we say instead "Emacs
>    > should try to attract newcomers who have a higher-than-average
>    > probability of becoming high-investment users, and should explain
>    > early on to those newcomers what the road ahead looks like", *then*
>    > we have a high-level guiding principle we can actually use.

I think we already do (the rest flocks to #1, #2 and #4 popular 
options). No need to try harder in that direction.

> So there's some concrete guidance about *how* we might seek to improve the Getting Started guide (and other things like the Emacs web site, starter videos, etc):
> 
> * Tell newcomers up front that Emacs really starts to be worth it after a few years, not a few weeks.  Set expectations right from the start.

That feels like giving up. And "worth it" depends on personal 
expectations. From reading comments on Reddit, converts from Vim, for 
instance, try Spacemacs or Doom Emacs, and seemingly become satisfied in 
a matter of days.

> * Show them some of the abilities they will eventually have, so that they can see why it's worth it to make the investment.

Not sure what you have in mind here. If it's a "here's not an Emacs 
would solve a problem", this could turn into a useful tutorial for 
journeyman emacsers.

> * Also tell them about the ways in which Emacs may frustrate them along the way, and explain that those frustrations are common and are sometimes inevitably entangled with the same things that make Emacs winning in the long term.

Not a bad advice, but deciding on such a list in official documentation 
might not be easy (people have opinions). Once we do decide, it would be 
better to try to improve these things first.

> Ultimately, I personally find it helpful in thinking about how to teach Emacs and how to write packages.  Here is the principle, reworded slightly after a suggestion from H. Dieter Wilhelm:
> 
> "GNU Emacs's raison d'être is to be the text manipulation environment that best rewards sustained user investment."

I still don't like it. It either means "you don't get much until you 
struggle for a while" (which just sounds discouraging) and/or "no other 
program comes even close at text manipulation", which is... pretty 
conceited and kind of limited at the same time. I mean, Emacs is great 
and all, but I don't have "text manipulation" as the #1 goal in my life. 
Or even among top 10 goals.

The higher-level things one can implement with Emacs Lisp are a lot more 
interesting.

>> Are you sure that this particular aspect is _bad_ for new users, though?
> 
> Yes.  I am sure.
> 
> I've taught Emacs to a lot of people -- scores of them, at least; I don't keep track, but the sample size is large enough to be beyond merely anecdotal at this point.  I've watched newcomers run into the same obstacles over and over, and this particular obstacle is always one of the first they encounter.

Okay, but is it still a problem after they've tried Emacs for a day, for 
instance? For a week?

These periods of time would of course suggest Emacs is not ideal for 
total newbies, but they're not the kind of "sustained investment" you 
described either.

>> This part is expected of a professional tool, however, and the
>> experience for newcomers could be improved without taking away much
>>from the "oldies". See the 'transient' package, for example, recently 
>> proposed for inclusion on emacs-devel.
> 
> I don't have any experience using 'transient', so I'd need more explanation from you to understand what you meant by that part.  (I tried to understand 'transient' from reading [2] and [3], but unfortunately -- and somewhat surprisingly! -- the documentation at those pages does not give a single concrete example of transient's use.)

You press 'C-x', wait a while - and it pops up a window with the 
descriptions of all commands whose bindings start with 'C-x'. Same for 
all other "incomplete" key sequences. Looks pretty handy for beginners.

> However, your assertion that "the experience for newcomers could be improved without taking away much from the 'oldies'" is exactly what I'm arguing is not true.  I actually think we can't (much) improve this particular part of the experience for newcomers without taking away one of the things about Emacs that most rewards investment.
> 
> The newcomers who eventually *do* become experts do so in part by first stumbling across new commands accidentally (in that crowded keybinding space) and then using help tools like `C-h l' to see what they just did.  So one of the things we should prioritize is teaching newcomers how important those help facilities are and how to use them in a smart way.  I'm specifically saying that this is *more important for Emacs than it is for other editors*.  Sure, users of (say) the Atom editor should eventually know how to use the built-in help there too.  But it's a difference in prioritization: for Emacs users, using that built-in help is more important than it would be in other editors, and the methods and circumstances of using the help are different too.  So we should incorporate that fact i
 nto how we present Emacs to new users.

Yes, ok. Maybe this one is harder to improve that some others.

>> Some of them, probably. At this point, I think, there are still a lot
>> of decisions that would bring us closer to newcomer-friendliness while
>> keeping no worse high-investment compatibility.
> 
> That could be true, though I'm a bit more skeptical than you are.  In any case, it does not make the principle inoperative; it is consistent with the principle.
> 
> I believe we'll make better decisions if we keep in mind that "friendly to newcomers" is not, in itself, the primary goal.

It's not like extreme user-friendliness was ever a guiding principle 
here. :-)

In this we're, again, similar to other professional software.

Re: GNU Emacs raison d'etre

[Jean-Christophe Helary]

> On May 17, 2020, at 10:28, Dmitry Gutov <dgutov@yandex.ru> wrote:
> 
>>> This part is expected of a professional tool, however, and the
>>> experience for newcomers could be improved without taking away much
>>> from the "oldies". See the 'transient' package, for example, recently proposed for inclusion on emacs-devel.
>> I don't have any experience using 'transient', so I'd need more explanation from you to understand what you meant by that part.  (I tried to understand 'transient' from reading [2] and [3], but unfortunately -- and somewhat surprisingly! -- the documentation at those pages does not give a single concrete example of transient's use.)
> 
> You press 'C-x', wait a while - and it pops up a window with the descriptions of all commands whose bindings start with 'C-x'. Same for all other "incomplete" key sequences. Looks pretty handy for beginners.

which-key seems to do something similar. I like it very much because it helps see the rationale behind keybinding. After a while you get to learn the bindings for the commands you use the most and you can easily explore new commands.


Jean-Christophe Helary
-----------------------------------------------
http://mac4translators.blogspot.com @brandelune

transient

[Richard Stallman]

[[[ To any NSA and FBI agents reading my email: please consider    ]]]
[[[ whether defending the US Constitution against all enemies,     ]]]
[[[ foreign or domestic, requires you to follow Snowden's example. ]]]

  > I like it very much because it helps see the rationale behind
  > keybinding. After a while you get to learn the bindings for the
  > commands you use the most and you can easily explore new commands.

For those that know Transient -- do you think it would provide that
benefit too?

-- 
Dr Richard Stallman
Chief GNUisance of the GNU Project (https://gnu.org)
Founder, Free Software Foundation (https://fsf.org)
Internet Hall-of-Famer (https://internethalloffame.org)

Re: transient

[Joost Kremers]

On Mon, May 18 2020, Richard Stallman wrote:
>   > I like it very much because it helps see the rationale 
>   > behind
>   > keybinding. After a while you get to learn the bindings for 
>   > the
>   > commands you use the most and you can easily explore new 
>   > commands.
>
> For those that know Transient -- do you think it would provide 
> that
> benefit too?

Well, which-key simply displays existing keybindings. A package 
author doesn't have to do anything, which-key just works.

Transient OTOH defines its own key sequences, so you can't use it 
to show users existing keybindings. If a package author wants 
their package to work with transient, they have to define 
transient menus for all functionality they want to expose.

Transient key bindings also work differently from standard Emacs 
key bindings. That's not a bad thing, because transient's main 
purpose is to provide an interface to external command line 
programs (such as git, as it was originally developed as part of 
magit) and it's well-suited for that.

It would be possible to use transient to provide an interface to 
Emacs packages, but the interface would be different from what is 
standard, so it's not a which-key replacement.


-- 
Joost Kremers
Life has its moments

which-key

[Richard Stallman]

[[[ To any NSA and FBI agents reading my email: please consider    ]]]
[[[ whether defending the US Constitution against all enemies,     ]]]
[[[ foreign or domestic, requires you to follow Snowden's example. ]]]

  > Well, which-key simply displays existing keybindings. A package 
  > author doesn't have to do anything, which-key just works.

I see.  That sounds useful.  Does anyone disagree?

-- 
Dr Richard Stallman
Chief GNUisance of the GNU Project (https://gnu.org)
Founder, Free Software Foundation (https://fsf.org)
Internet Hall-of-Famer (https://internethalloffame.org)