discoverability, better defaults and which-key in Emacs

discoverability, better defaults and which-key in Emacs

[Jeremy Bryant]

A recent theme of discussion has been improving discoverability of Emacs
features, and in a related way, 'better defaults'.

Here is a suggestion - include which-key in core and potentially enable
by for new users.

I understand it is in ELPA already.

Author Justin has expressed openness to the idea in
https://github.com/justbur/emacs-which-key/issues/355


What do people think?
What work needs to be done and how?

Re: discoverability, better defaults and which-key in Emacs

[Po Lu]

Jeremy Bryant <jb@jeremybryant.net> writes:

> Here is a suggestion - include which-key in core and potentially enable
> by for new users.
>
> I understand it is in ELPA already.
>
> Author Justin has expressed openness to the idea in
> https://github.com/justbur/emacs-which-key/issues/355

I don't think enabling it by default is all that desirable, since its
popups are far more intrusive than keystrokes are when echoed, but
moving it to core is a decent idea.

Re: discoverability, better defaults and which-key in Emacs

[Philip Kaludercic]

Po Lu <luangruo@yahoo.com> writes:

> Jeremy Bryant <jb@jeremybryant.net> writes:
>
>> Here is a suggestion - include which-key in core and potentially enable
>> by for new users.
>>
>> I understand it is in ELPA already.
>>
>> Author Justin has expressed openness to the idea in
>> https://github.com/justbur/emacs-which-key/issues/355
>
> I don't think enabling it by default is all that desirable, since its
> popups are far more intrusive than keystrokes are when echoed, but
> moving it to core is a decent idea.

I second this concern, it also promotes the inefficient practice of
inspecting keymaps by waiting for the idle timer to be triggered.

Re: discoverability, better defaults and which-key in Emacs

[Dmitry Gutov]

On 03/02/2024 15:40, Philip Kaludercic wrote:
> Po Lu<luangruo@yahoo.com>  writes:
> 
>> Jeremy Bryant<jb@jeremybryant.net>  writes:
>>
>>> Here is a suggestion - include which-key in core and potentially enable
>>> by for new users.
>>>
>>> I understand it is in ELPA already.
>>>
>>> Author Justin has expressed openness to the idea in
>>> https://github.com/justbur/emacs-which-key/issues/355
>> I don't think enabling it by default is all that desirable, since its
>> popups are far more intrusive than keystrokes are when echoed, but
>> moving it to core is a decent idea.
> I second this concern, it also promotes the inefficient practice of
> inspecting keymaps by waiting for the idle timer to be triggered.

What if instead of having the help on a timer, the timer would add a 
small hint in the echo about how to invoke help (i.e. press C-h)?

The interface for displaying help could be which-key (it seems to look 
pretty enough), or just the current 'C-h' help, depending on the settings.

The result, though, is that everybody learns to press 'C-h' when they 
want to explore what the current prefix map contains and not just wait 
for the timer.

Re: discoverability, better defaults and which-key in Emacs

[Philip Kaludercic]

Dmitry Gutov <dmitry@gutov.dev> writes:

> On 03/02/2024 15:40, Philip Kaludercic wrote:
>> Po Lu<luangruo@yahoo.com>  writes:
>> 
>>> Jeremy Bryant<jb@jeremybryant.net>  writes:
>>>
>>>> Here is a suggestion - include which-key in core and potentially enable
>>>> by for new users.
>>>>
>>>> I understand it is in ELPA already.
>>>>
>>>> Author Justin has expressed openness to the idea in
>>>> https://github.com/justbur/emacs-which-key/issues/355
>>> I don't think enabling it by default is all that desirable, since its
>>> popups are far more intrusive than keystrokes are when echoed, but
>>> moving it to core is a decent idea.
>> I second this concern, it also promotes the inefficient practice of
>> inspecting keymaps by waiting for the idle timer to be triggered.
>
> What if instead of having the help on a timer, the timer would add a
> small hint in the echo about how to invoke help (i.e. press C-h)?

I think that would be a significant improvement if it is to be enabled
by default.  I don't have an issue with the presentation (though the
transient buffer is my preferred UX).

> The interface for displaying help could be which-key (it seems to look
> pretty enough), or just the current 'C-h' help, depending on the
> settings.
>
> The result, though, is that everybody learns to press 'C-h' when they
> want to explore what the current prefix map contains and not just wait
> for the timer.

Re: discoverability, better defaults and which-key in Emacs

[Dmitry Gutov]

On 05/02/2024 09:11, Philip Kaludercic wrote:
> Dmitry Gutov <dmitry@gutov.dev> writes:
> 
>> On 03/02/2024 15:40, Philip Kaludercic wrote:
>>> Po Lu<luangruo@yahoo.com>  writes:
>>>
>>>> Jeremy Bryant<jb@jeremybryant.net>  writes:
>>>>
>>>>> Here is a suggestion - include which-key in core and potentially enable
>>>>> by for new users.
>>>>>
>>>>> I understand it is in ELPA already.
>>>>>
>>>>> Author Justin has expressed openness to the idea in
>>>>> https://github.com/justbur/emacs-which-key/issues/355
>>>> I don't think enabling it by default is all that desirable, since its
>>>> popups are far more intrusive than keystrokes are when echoed, but
>>>> moving it to core is a decent idea.
>>> I second this concern, it also promotes the inefficient practice of
>>> inspecting keymaps by waiting for the idle timer to be triggered.
>>
>> What if instead of having the help on a timer, the timer would add a
>> small hint in the echo about how to invoke help (i.e. press C-h)?
> 
> I think that would be a significant improvement if it is to be enabled
> by default.  I don't have an issue with the presentation (though the
> transient buffer is my preferred UX).

Is "transient buffer" the same as what which-key uses? I think the 
'transient' package uses similar display.

Re: discoverability, better defaults and which-key in Emacs

[Philip Kaludercic]

Dmitry Gutov <dmitry@gutov.dev> writes:

> On 05/02/2024 09:11, Philip Kaludercic wrote:
>> Dmitry Gutov <dmitry@gutov.dev> writes:
>> 
>>> On 03/02/2024 15:40, Philip Kaludercic wrote:
>>>> Po Lu<luangruo@yahoo.com>  writes:
>>>>
>>>>> Jeremy Bryant<jb@jeremybryant.net>  writes:
>>>>>
>>>>>> Here is a suggestion - include which-key in core and potentially enable
>>>>>> by for new users.
>>>>>>
>>>>>> I understand it is in ELPA already.
>>>>>>
>>>>>> Author Justin has expressed openness to the idea in
>>>>>> https://github.com/justbur/emacs-which-key/issues/355
>>>>> I don't think enabling it by default is all that desirable, since its
>>>>> popups are far more intrusive than keystrokes are when echoed, but
>>>>> moving it to core is a decent idea.
>>>> I second this concern, it also promotes the inefficient practice of
>>>> inspecting keymaps by waiting for the idle timer to be triggered.
>>>
>>> What if instead of having the help on a timer, the timer would add a
>>> small hint in the echo about how to invoke help (i.e. press C-h)?
>> I think that would be a significant improvement if it is to be
>> enabled
>> by default.  I don't have an issue with the presentation (though the
>> transient buffer is my preferred UX).
>
> Is "transient buffer" the same as what which-key uses? I think the
> 'transient' package uses similar display.

I don't know, what I meant with transient buffer is that it isn't
persistent, as is the case with C-h C-h where a new window pops up that
is no different than any other window and behaves consistently.
Transient buffers, in my experience, usually gobble up all key-presses
and re-implement their own "MVC" that can differ in subtle points.

Re: discoverability, better defaults and which-key in Emacs

[Dmitry Gutov]

On 05/02/2024 20:47, Philip Kaludercic wrote:
>>>> What if instead of having the help on a timer, the timer would add a
>>>> small hint in the echo about how to invoke help (i.e. press C-h)?
>>> I think that would be a significant improvement if it is to be
>>> enabled
>>> by default.  I don't have an issue with the presentation (though the
>>> transient buffer is my preferred UX).
>> Is "transient buffer" the same as what which-key uses? I think the
>> 'transient' package uses similar display.
> I don't know, what I meant with transient buffer is that it isn't
> persistent, as is the case with C-h C-h where a new window pops up that
> is no different than any other window and behaves consistently.
> Transient buffers, in my experience, usually gobble up all key-presses
> and re-implement their own "MVC" that can differ in subtle points.

What I'm wondering, is where to do from here.

If you like which-key's UI (and I don't mind it, aside from the timer 
thing -- seems like it can be more useful than the current 
'describe-bindings' in many cases), then we could ask the author for 
this different mode of operation, where the timer only tells the user 
how to get this transient menu with hints (pressing C-h), but the menu 
itself isn't shown.

Or more generally we'll have such a timer globally, and the message 
("use C-h") would be independent from which-key. But which-key can plug 
into the "C-h" binding one way or another, to replace describe-bindings 
if the user configured it this way.

Re: discoverability, better defaults and which-key in Emacs

[Justin Burkett]

> If you like which-key's UI (and I don't mind it, aside from the timer
> thing -- seems like it can be more useful than the current
> 'describe-bindings' in many cases), then we could ask the author for
> this different mode of operation, where the timer only tells the user
> how to get this transient menu with hints (pressing C-h), but the menu
> itself isn't shown.
>
> Or more generally we'll have such a timer globally, and the message
> ("use C-h") would be independent from which-key. But which-key can plug
> into the "C-h" binding one way or another, to replace describe-bindings
> if the user configured it this way.

I'm the author of which-key, and I've been following along but don't
have a strong opinion on whether it should be on by default, so I'll
let you all decide.

I should mention in response to the comments above that this feature
is partially implemented through the following setup (from the
README). It simply sets a long delay for the timer and allows you to
use C-h to trigger the popup.

     ;; Allow C-h to trigger which-key before it is done automatically
     (setq which-key-show-early-on-C-h t)
     ;; make sure which-key doesn't show normally but refreshes
quickly after it is
     ;; triggered.
     (setq which-key-idle-delay 10000)
     (setq which-key-idle-secondary-delay 0.05)
     (which-key-mode)

Justin


On Mon, Feb 5, 2024 at 2:17 PM Dmitry Gutov <dmitry@gutov.dev> wrote:
>
> On 05/02/2024 20:47, Philip Kaludercic wrote:
> >>>> What if instead of having the help on a timer, the timer would add a
> >>>> small hint in the echo about how to invoke help (i.e. press C-h)?
> >>> I think that would be a significant improvement if it is to be
> >>> enabled
> >>> by default.  I don't have an issue with the presentation (though the
> >>> transient buffer is my preferred UX).
> >> Is "transient buffer" the same as what which-key uses? I think the
> >> 'transient' package uses similar display.
> > I don't know, what I meant with transient buffer is that it isn't
> > persistent, as is the case with C-h C-h where a new window pops up that
> > is no different than any other window and behaves consistently.
> > Transient buffers, in my experience, usually gobble up all key-presses
> > and re-implement their own "MVC" that can differ in subtle points.
>
> What I'm wondering, is where to do from here.
>
> If you like which-key's UI (and I don't mind it, aside from the timer
> thing -- seems like it can be more useful than the current
> 'describe-bindings' in many cases), then we could ask the author for
> this different mode of operation, where the timer only tells the user
> how to get this transient menu with hints (pressing C-h), but the menu
> itself isn't shown.
>
> Or more generally we'll have such a timer globally, and the message
> ("use C-h") would be independent from which-key. But which-key can plug
> into the "C-h" binding one way or another, to replace describe-bindings
> if the user configured it this way.

Re: discoverability, better defaults and which-key in Emacs

[Dmitry Gutov]

On 05/02/2024 21:33, Justin Burkett wrote:
>> If you like which-key's UI (and I don't mind it, aside from the timer
>> thing -- seems like it can be more useful than the current
>> 'describe-bindings' in many cases), then we could ask the author for
>> this different mode of operation, where the timer only tells the user
>> how to get this transient menu with hints (pressing C-h), but the menu
>> itself isn't shown.
>>
>> Or more generally we'll have such a timer globally, and the message
>> ("use C-h") would be independent from which-key. But which-key can plug
>> into the "C-h" binding one way or another, to replace describe-bindings
>> if the user configured it this way.
> I'm the author of which-key, and I've been following along but don't
> have a strong opinion on whether it should be on by default, so I'll
> let you all decide.
> 
> I should mention in response to the comments above that this feature
> is partially implemented through the following setup (from the
> README). It simply sets a long delay for the timer and allows you to
> use C-h to trigger the popup.
> 
>       ;; Allow C-h to trigger which-key before it is done automatically
>       (setq which-key-show-early-on-C-h t)
>       ;; make sure which-key doesn't show normally but refreshes
> quickly after it is
>       ;; triggered.
>       (setq which-key-idle-delay 10000)
>       (setq which-key-idle-secondary-delay 0.05)
>       (which-key-mode)

Nice, thanks. These settings are for the second option, right? "More 
generally ...", etc.

What is missing is the note in the echo area that tells the user to 
press C-h after a timeout (like 200ms or so) if they want help in the 
middle of typing a key sequence.

Re: discoverability, better defaults and which-key in Emacs

[Justin Burkett]

On Mon, Feb 5, 2024 at 6:05 PM Dmitry Gutov <dmitry@gutov.dev> wrote:
>
> On 05/02/2024 21:33, Justin Burkett wrote:
> >> If you like which-key's UI (and I don't mind it, aside from the timer
> >> thing -- seems like it can be more useful than the current
> >> 'describe-bindings' in many cases), then we could ask the author for
> >> this different mode of operation, where the timer only tells the user
> >> how to get this transient menu with hints (pressing C-h), but the menu
> >> itself isn't shown.
> >>
> >> Or more generally we'll have such a timer globally, and the message
> >> ("use C-h") would be independent from which-key. But which-key can plug
> >> into the "C-h" binding one way or another, to replace describe-bindings
> >> if the user configured it this way.
> > I'm the author of which-key, and I've been following along but don't
> > have a strong opinion on whether it should be on by default, so I'll
> > let you all decide.
> >
> > I should mention in response to the comments above that this feature
> > is partially implemented through the following setup (from the
> > README). It simply sets a long delay for the timer and allows you to
> > use C-h to trigger the popup.
> >
> >       ;; Allow C-h to trigger which-key before it is done automatically
> >       (setq which-key-show-early-on-C-h t)
> >       ;; make sure which-key doesn't show normally but refreshes
> > quickly after it is
> >       ;; triggered.
> >       (setq which-key-idle-delay 10000)
> >       (setq which-key-idle-secondary-delay 0.05)
> >       (which-key-mode)
>
> Nice, thanks. These settings are for the second option, right? "More
> generally ...", etc.
>
> What is missing is the note in the echo area that tells the user to
> press C-h after a timeout (like 200ms or so) if they want help in the
> middle of typing a key sequence.

True, but I think a message like that could be useful regardless of
whether which-key is active (i.e., for `describe-prefix-bindings`).

Re: discoverability, better defaults and which-key in Emacs

[Dmitry Gutov]

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

On 06/02/2024 04:49, Justin Burkett wrote:
>> What is missing is the note in the echo area that tells the user to
>> press C-h after a timeout (like 200ms or so) if they want help in the
>> middle of typing a key sequence.
> True, but I think a message like that could be useful regardless of
> whether which-key is active (i.e., for `describe-prefix-bindings`).

Right. :)

How about this?

Since echo-keystrokes is 1 second by default, which defines a 
significant timeout already, I think this can work without a yet another 
timer.

[-- Attachment #2: echo_keystrokes_help.diff --]
[-- Type: text/x-patch, Size: 1067 bytes --]

diff --git a/src/keyboard.c b/src/keyboard.c
index 1f7253a7da1..6d3db5ab615 100644
--- a/src/keyboard.c
+++ b/src/keyboard.c
@@ -589,6 +589,15 @@ echo_dash (void)
   AUTO_STRING (dash, "-");
   kset_echo_string (current_kboard,
 		    concat2 (KVAR (current_kboard, echo_string), dash));
+
+  if (echo_keystrokes_help)
+    {
+      AUTO_STRING (help, " (\\`C-h' for help)");
+      kset_echo_string (current_kboard,
+			concat2 (KVAR (current_kboard, echo_string),
+				 calln (Qsubstitute_command_keys, help)));
+    }
+
   echo_now ();
 }
 
@@ -13228,6 +13237,10 @@ syms_of_keyboard (void)
 If the value is zero, don't echo at all.  */);
   Vecho_keystrokes = make_fixnum (1);
 
+  DEFVAR_BOOL ("echo-keystrokes-help", echo_keystrokes_help,
+	       doc: /* Non-nil means append small help text to the unfinished commands' echo. */);
+  echo_keystrokes_help = true;
+
   DEFVAR_LISP ("polling-period", Vpolling_period,
 	      doc: /* Interval between polling for input during Lisp execution.
 The reason for polling is to make C-g work to stop a running program.

Re: discoverability, better defaults and which-key in Emacs

[Eli Zaretskii]

> Date: Wed, 7 Feb 2024 01:12:37 +0200
> Cc: Philip Kaludercic <philipk@posteo.net>, Po Lu <luangruo@yahoo.com>,
>  Jeremy Bryant <jb@jeremybryant.net>, Emacs Devel <emacs-devel@gnu.org>
> From: Dmitry Gutov <dmitry@gutov.dev>
> 
> How about this?
> 
> Since echo-keystrokes is 1 second by default, which defines a 
> significant timeout already, I think this can work without a yet another 
> timer.

LGTM, but it should be a defcustom.

Re: discoverability, better defaults and which-key in Emacs

[Dmitry Gutov]

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

On 07/02/2024 14:35, Eli Zaretskii wrote:
>> Date: Wed, 7 Feb 2024 01:12:37 +0200
>> Cc: Philip Kaludercic <philipk@posteo.net>, Po Lu <luangruo@yahoo.com>,
>>   Jeremy Bryant <jb@jeremybryant.net>, Emacs Devel <emacs-devel@gnu.org>
>> From: Dmitry Gutov <dmitry@gutov.dev>
>>
>> How about this?
>>
>> Since echo-keystrokes is 1 second by default, which defines a
>> significant timeout already, I think this can work without a yet another
>> timer.
> 
> LGTM, but it should be a defcustom.

All right, see the attached.

[-- Attachment #2: echo_keystrokes_help.diff --]
[-- Type: text/x-patch, Size: 2055 bytes --]

diff --git a/etc/NEWS b/etc/NEWS
index ee7462cb2aa..d4b8bf21f94 100644
--- a/etc/NEWS
+++ b/etc/NEWS
@@ -307,6 +307,9 @@ between the auto save file and the current file.
 ** 'ffap-lax-url' now defaults to nil.
 Previously, it was set to t but this broke remote file name detection.
 
+** Unfinished commands' echo now ends with a suggestion to use Help
+Customize 'echo-keystrokes-help' to nil to hide it.
+
 \f
 * Editing Changes in Emacs 30.1
 
diff --git a/lisp/cus-start.el b/lisp/cus-start.el
index 7e0b64e9067..3fe62c8d0da 100644
--- a/lisp/cus-start.el
+++ b/lisp/cus-start.el
@@ -371,6 +371,7 @@ minibuffer-prompt-properties--setter
 	     (auto-save-timeout auto-save (choice (const :tag "off" nil)
 						  (integer :format "%v")))
 	     (echo-keystrokes minibuffer number)
+             (echo-keystrokes-help minibuffer boolean "30.1")
 	     (polling-period keyboard float)
 	     (double-click-time mouse (restricted-sexp
 				       :match-alternatives (integerp 'nil 't)))
diff --git a/src/keyboard.c b/src/keyboard.c
index 1f7253a7da1..6d3db5ab615 100644
--- a/src/keyboard.c
+++ b/src/keyboard.c
@@ -589,6 +589,15 @@ echo_dash (void)
   AUTO_STRING (dash, "-");
   kset_echo_string (current_kboard,
 		    concat2 (KVAR (current_kboard, echo_string), dash));
+
+  if (echo_keystrokes_help)
+    {
+      AUTO_STRING (help, " (\\`C-h' for help)");
+      kset_echo_string (current_kboard,
+			concat2 (KVAR (current_kboard, echo_string),
+				 calln (Qsubstitute_command_keys, help)));
+    }
+
   echo_now ();
 }
 
@@ -13228,6 +13237,10 @@ syms_of_keyboard (void)
 If the value is zero, don't echo at all.  */);
   Vecho_keystrokes = make_fixnum (1);
 
+  DEFVAR_BOOL ("echo-keystrokes-help", echo_keystrokes_help,
+	       doc: /* Non-nil means append small help text to the unfinished commands' echo. */);
+  echo_keystrokes_help = true;
+
   DEFVAR_LISP ("polling-period", Vpolling_period,
 	      doc: /* Interval between polling for input during Lisp execution.
 The reason for polling is to make C-g work to stop a running program.

Re: discoverability, better defaults and which-key in Emacs

[Eli Zaretskii]

> Date: Wed, 7 Feb 2024 20:31:04 +0200
> Cc: justin@burkett.cc, philipk@posteo.net, luangruo@yahoo.com,
>  jb@jeremybryant.net, emacs-devel@gnu.org
> From: Dmitry Gutov <dmitry@gutov.dev>
> 
> > LGTM, but it should be a defcustom.
> 
> All right, see the attached.

Thanks.  Nitpicking:

> --- a/etc/NEWS
> +++ b/etc/NEWS
> @@ -307,6 +307,9 @@ between the auto save file and the current file.
>  ** 'ffap-lax-url' now defaults to nil.
>  Previously, it was set to t but this broke remote file name detection.
>  
> +** Unfinished commands' echo now ends with a suggestion to use Help

Heading lines in NEWS should end with a period.

> +Customize 'echo-keystrokes-help' to nil to hide it.
                                           ^^^^^^^^^^
"to prevent it" is better, I think.

Re: discoverability, better defaults and which-key in Emacs

[Dmitry Gutov]

On 07/02/2024 21:13, Eli Zaretskii wrote:
>> Date: Wed, 7 Feb 2024 20:31:04 +0200
>> Cc:justin@burkett.cc,philipk@posteo.net,luangruo@yahoo.com,
>>   jb@jeremybryant.net,emacs-devel@gnu.org
>> From: Dmitry Gutov<dmitry@gutov.dev>
>>
>>> LGTM, but it should be a defcustom.
>> All right, see the attached.
> Thanks.  Nitpicking:
> 
>> --- a/etc/NEWS
>> +++ b/etc/NEWS
>> @@ -307,6 +307,9 @@ between the auto save file and the current file.
>>   ** 'ffap-lax-url' now defaults to nil.
>>   Previously, it was set to t but this broke remote file name detection.
>>   
>> +** Unfinished commands' echo now ends with a suggestion to use Help
> Heading lines in NEWS should end with a period.
> 
>> +Customize 'echo-keystrokes-help' to nil to hide it.
>                                             ^^^^^^^^^^
> "to prevent it" is better, I think.

Thanks for the comments, pushed to master as f444786e587.

Re: discoverability, better defaults and which-key in Emacs

[Visuwesh]

[புதன் பிப்ரவரி 07, 2024] Dmitry Gutov wrote:

> [...]
> diff --git a/src/keyboard.c b/src/keyboard.c
> index 1f7253a7da1..6d3db5ab615 100644
> --- a/src/keyboard.c
> +++ b/src/keyboard.c
> @@ -589,6 +589,15 @@ echo_dash (void)
>    AUTO_STRING (dash, "-");
>    kset_echo_string (current_kboard,
>  		    concat2 (KVAR (current_kboard, echo_string), dash));
> +
> +  if (echo_keystrokes_help)
> +    {
> +      AUTO_STRING (help, " (\\`C-h' for help)");
                               ^^^^^^^

Shouldn't this part use the value of help-char instead?  (There's also
the complication with help-form.)

> +      kset_echo_string (current_kboard,
> +			concat2 (KVAR (current_kboard, echo_string),
> +				 calln (Qsubstitute_command_keys, help)));
> +    }
> +
>    echo_now ();
>  }
>  
> @@ -13228,6 +13237,10 @@ syms_of_keyboard (void)
>  If the value is zero, don't echo at all.  */);
>    Vecho_keystrokes = make_fixnum (1);
>  
> +  DEFVAR_BOOL ("echo-keystrokes-help", echo_keystrokes_help,
> +	       doc: /* Non-nil means append small help text to the unfinished commands' echo. */);
> +  echo_keystrokes_help = true;
> +
>    DEFVAR_LISP ("polling-period", Vpolling_period,
>  	      doc: /* Interval between polling for input during Lisp execution.
>  The reason for polling is to make C-g work to stop a running program.

Re: discoverability, better defaults and which-key in Emacs

[Eli Zaretskii]

> From: Visuwesh <visuweshm@gmail.com>
> Cc: Eli Zaretskii <eliz@gnu.org>,  justin@burkett.cc,  philipk@posteo.net,
>   luangruo@yahoo.com,  jb@jeremybryant.net,  emacs-devel@gnu.org
> Date: Thu, 08 Feb 2024 07:16:56 +0530
> 
> [புதன் பிப்ரவரி 07, 2024] Dmitry Gutov wrote:
> 
> > [...]
> > diff --git a/src/keyboard.c b/src/keyboard.c
> > index 1f7253a7da1..6d3db5ab615 100644
> > --- a/src/keyboard.c
> > +++ b/src/keyboard.c
> > @@ -589,6 +589,15 @@ echo_dash (void)
> >    AUTO_STRING (dash, "-");
> >    kset_echo_string (current_kboard,
> >  		    concat2 (KVAR (current_kboard, echo_string), dash));
> > +
> > +  if (echo_keystrokes_help)
> > +    {
> > +      AUTO_STRING (help, " (\\`C-h' for help)");
>                                ^^^^^^^
> 
> Shouldn't this part use the value of help-char instead?  (There's also
> the complication with help-form.)

I'm not sure using help-char here is TRT: that character is only in
effect in this situation of it has no binding prefixed by what the
user already typed.  So the effect of changing help-char could be
confusing for newbies, who are the main audience of this feature.  But
I added F1 to that text, which should help if someone did change
help-char.

Thanks.

Re: discoverability, better defaults and which-key in Emacs

[Dmitry Gutov]

On 08/02/2024 08:59, Eli Zaretskii wrote:
> But
> I added F1 to that text, which should help if someone did change
> help-char.

Whether help-char is changed, or 'C-h' is rebound anyway, can all be 
detected at runtime. <f1> can also have a different binding in the 
current prefix map--then the new message would be doubly incorrect.

I'd rather we picked one (preferably correct) suggestion and printed that.

For context: I customize echo-keystrokes to a very low value and 
currently see this help message quite often.

Re: discoverability, better defaults and which-key in Emacs

[Eli Zaretskii]

> Date: Thu, 8 Feb 2024 14:18:34 +0200
> Cc: justin@burkett.cc, philipk@posteo.net, luangruo@yahoo.com,
>  jb@jeremybryant.net, emacs-devel@gnu.org
> From: Dmitry Gutov <dmitry@gutov.dev>
> 
> On 08/02/2024 08:59, Eli Zaretskii wrote:
> > But
> > I added F1 to that text, which should help if someone did change
> > help-char.
> 
> Whether help-char is changed, or 'C-h' is rebound anyway, can all be 
> detected at runtime. <f1> can also have a different binding in the 
> current prefix map--then the new message would be doubly incorrect.

How frequently do people rebind F1?  IME, never.

But I don't object to adding runtime detection of the help keys.

> I'd rather we picked one (preferably correct) suggestion and printed that.

Most people will never rebind C-h.  Those who do could rebind it to a
character that cannot be used in this situation because it is already
bound in various prefix maps.  Having two alternatives there increases
the probability that one of them will work.

> For context: I customize echo-keystrokes to a very low value and 
> currently see this help message quite often.

If the message annoys you, you can disable it.

Re: discoverability, better defaults and which-key in Emacs

[Dmitry Gutov]

On 08/02/2024 15:02, Eli Zaretskii wrote:
>> Date: Thu, 8 Feb 2024 14:18:34 +0200
>> Cc: justin@burkett.cc, philipk@posteo.net, luangruo@yahoo.com,
>>   jb@jeremybryant.net, emacs-devel@gnu.org
>> From: Dmitry Gutov <dmitry@gutov.dev>
>>
>> On 08/02/2024 08:59, Eli Zaretskii wrote:
>>> But
>>> I added F1 to that text, which should help if someone did change
>>> help-char.
>>
>> Whether help-char is changed, or 'C-h' is rebound anyway, can all be
>> detected at runtime. <f1> can also have a different binding in the
>> current prefix map--then the new message would be doubly incorrect.
> 
> How frequently do people rebind F1?  IME, never.

Sure, likewise with C-h. That's why the original patch was probably okay 
as-is.

> But I don't object to adding runtime detection of the help keys.

Good.

>> I'd rather we picked one (preferably correct) suggestion and printed that.
> 
> Most people will never rebind C-h.  Those who do could rebind it to a
> character that cannot be used in this situation because it is already
> bound in various prefix maps.  Having two alternatives there increases
> the probability that one of them will work.

If we consider the situations where C-h or f1 is rebound, having 
misleading text in the message (with bindings that don't work) should 
concern us as well. Even if one of the suggestions is likely to work 
anyway (while the other doesn't).

>> For context: I customize echo-keystrokes to a very low value and
>> currently see this help message quite often.
> 
> If the message annoys you, you can disable it.

Sure - this is not a deal-breaker. But the more features I disable the 
less problems I could find while dogfooding. Until now I've been running 
with it, and it seemed unobtrusive enough.

Runtime detection might even make it occasionally helpful in odd 
contexts where something shadows the binding.

Re: discoverability, better defaults and which-key in Emacs

[Eli Zaretskii]

> Date: Thu, 8 Feb 2024 15:36:43 +0200
> Cc: visuweshm@gmail.com, justin@burkett.cc, philipk@posteo.net,
>  luangruo@yahoo.com, jb@jeremybryant.net, emacs-devel@gnu.org
> From: Dmitry Gutov <dmitry@gutov.dev>
> 
> > How frequently do people rebind F1?  IME, never.
> 
> Sure, likewise with C-h.

No, C-h is different.  At least in the past some people wanted it to
do the same as Backspace (we even have a special mode for that
contingency).  But F1 was a relatively late addition to Emacs, from
when people were accustomed to have it invoke some help function, and
no application I'm aware of has it bound to something else, unlike
some other Fn keys.  So I'm quite surprised to hear your "sure" above.
Did you actually see that in the wild?

> > Most people will never rebind C-h.  Those who do could rebind it to a
> > character that cannot be used in this situation because it is already
> > bound in various prefix maps.  Having two alternatives there increases
> > the probability that one of them will work.
> 
> If we consider the situations where C-h or f1 is rebound, having 
> misleading text in the message (with bindings that don't work) should 
> concern us as well. Even if one of the suggestions is likely to work 
> anyway (while the other doesn't).

If you can come up with a code that detects at run time that help-key
and/or F1 was rebound to a key that will not invoke
describe-prefix-bindings, such a key should indeed better be removed
from the message.  But can we reliably do that?  If we cannot, having
two keys there instead of one is better.

Re: discoverability, better defaults and which-key in Emacs

[Dmitry Gutov]

On 08/02/2024 15:52, Eli Zaretskii wrote:
>> Date: Thu, 8 Feb 2024 15:36:43 +0200
>> Cc:visuweshm@gmail.com,justin@burkett.cc,philipk@posteo.net,
>>   luangruo@yahoo.com,jb@jeremybryant.net,emacs-devel@gnu.org
>> From: Dmitry Gutov<dmitry@gutov.dev>
>>
>>> How frequently do people rebind F1?  IME, never.
>> Sure, likewise with C-h.
> No, C-h is different.  At least in the past some people wanted it to
> do the same as Backspace (we even have a special mode for that
> contingency).  But F1 was a relatively late addition to Emacs, from
> when people were accustomed to have it invoke some help function, and
> no application I'm aware of has it bound to something else, unlike
> some other Fn keys.  So I'm quite surprised to hear your "sure" above.
> Did you actually see that in the wild?

I have seen neither exactly, but as a data point I can say that sometime 
until 2014 company-mode used <f1> as a binding in company-active-map.

Not in a prefix map (so this is not an exact match), but still in a way 
that prevents help commands such as '<f1> v' from working. Later we 
added 'C-h' for the same binding (because "<f1> is extremely 
touch-typing unfriendly"), but as I'm looking at it now, the <f1> 
binding is still there.

>>> Most people will never rebind C-h.  Those who do could rebind it to a
>>> character that cannot be used in this situation because it is already
>>> bound in various prefix maps.  Having two alternatives there increases
>>> the probability that one of them will work.
>> If we consider the situations where C-h or f1 is rebound, having
>> misleading text in the message (with bindings that don't work) should
>> concern us as well. Even if one of the suggestions is likely to work
>> anyway (while the other doesn't).
> If you can come up with a code that detects at run time that help-key
> and/or F1 was rebound to a key that will not invoke
> describe-prefix-bindings, such a key should indeed better be removed
> from the message.  But can we reliably do that?  If we cannot, having
> two keys there instead of one is better.

I think we should be able to, but since help-key doesn't call any 
command directly through a map or fallback binding of some sort (instead 
it's dispatched ad-hoc), the solution I have tried so far (also using 
substitute-command-keys) did not help.

Re: discoverability, better defaults and which-key in Emacs

[Dmitry Gutov]

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

On 08/02/2024 16:43, Dmitry Gutov wrote:
> If you can come up with a code that detects at run time that help-key
> and/or F1 was rebound to a key that will not invoke
> describe-prefix-bindings, such a key should indeed better be removed
> from the message.  But can we reliably do that?  If we cannot, having
> two keys there instead of one is better.

Here's a rough draft.

It seems to work in the basic cases that I've tried (changing help-char 
to something with a binding and rebinding <f1>), but doesn't account for 
key translations for far (e.g. if help-char is ?X and the prefix map has 
?x, this isn't caught).

Also, piping the current used map through so many methods is pretty 
messy, I'm sure whether I've used the appropriate value in other 
callsites of echo_now and echo_dash. There's also echo_update...

So if anybody has something simpler in mind that'd be welcome.

[-- Attachment #2: echo_keystrokes_help_v3.diff --]
[-- Type: text/x-patch, Size: 5133 bytes --]

diff --git a/lisp/help.el b/lisp/help.el
index 72a4f8a800d..4a93e1cd915 100644
--- a/lisp/help.el
+++ b/lisp/help.el
@@ -2253,6 +2253,22 @@ help-form-show
 	(with-output-to-temp-buffer " *Char Help*"
 	  (princ msg)))))
 
+(defun help--append-suffix (str map)
+  (catch 'res
+    (dolist (val help-event-list)
+      (let ((key (vector (if (eql val 'help)
+                             help-char
+                           val))))
+        (unless (and map (lookup-key map key))
+          (throw 'res
+                 (concat
+                  str
+                  (substitute-command-keys
+                   (format
+                    " (\\`%s' for help)"
+                    (key-description key))))))))
+    str))
+
 \f
 (defun help--docstring-quote (string)
   "Return a doc string that represents STRING.
diff --git a/src/keyboard.c b/src/keyboard.c
index 10cdef67348..8467b48c266 100644
--- a/src/keyboard.c
+++ b/src/keyboard.c
@@ -335,7 +335,7 @@ #define GROW_RAW_KEYBUF							\
 static void recursive_edit_unwind (Lisp_Object buffer);
 static Lisp_Object command_loop (void);
 
-static void echo_now (void);
+static void echo_now (Lisp_Object map);
 static ptrdiff_t echo_length (void);
 
 static void safe_run_hooks_maybe_narrowed (Lisp_Object, struct window *);
@@ -553,7 +553,7 @@ echo_add_key (Lisp_Object c)
    character.  */
 
 static void
-echo_dash (void)
+echo_dash (Lisp_Object map)
 {
   /* Do nothing if not echoing at all.  */
   if (NILP (KVAR (current_kboard, echo_string)))
@@ -595,15 +595,14 @@ echo_dash (void)
 
   if (echo_keystrokes_help)
     {
-      Lisp_Object help;
-
-      help = build_string (" (\\`C-h' or \\`<f1>' for help)");
-      kset_echo_string (current_kboard,
-			concat2 (KVAR (current_kboard, echo_string),
-				 calln (Qsubstitute_command_keys, help)));
+       kset_echo_string (current_kboard,
+			CALLN (Ffuncall,
+			       intern_c_string ("help--append-suffix"),
+			       KVAR (current_kboard, echo_string),
+			       map));
     }
 
-  echo_now ();
+  echo_now (map);
 }
 
 static void
@@ -629,7 +628,7 @@ echo_update (void)
 	    echo_add_key (c);
 	}
 
-      echo_now ();
+      echo_now (Qnil);
     }
 }
 
@@ -637,7 +636,7 @@ echo_update (void)
    doing so.  */
 
 static void
-echo_now (void)
+echo_now (Lisp_Object map)
 {
   if (!current_kboard->immediate_echo
       /* This test breaks calls that use `echo_now' to display the echo_prompt.
@@ -646,7 +645,7 @@ echo_now (void)
       current_kboard->immediate_echo = true;
       echo_update ();
       /* Put a dash at the end to invite the user to type more.  */
-      echo_dash ();
+      echo_dash (map);
     }
 
   echoing = true;
@@ -1597,7 +1596,7 @@ command_loop_1 (void)
 	{
 	  current_kboard->immediate_echo = false;
 	  /* Refresh the echo message.  */
-	  echo_now ();
+	  echo_now (Qnil);
 	}
       else
 	cancel_echoing ();
@@ -2739,7 +2738,7 @@ read_char (int commandflag, Lisp_Object map,
 	  || ok_to_echo_at_next_pause == NULL))
     cancel_echoing ();
   else
-    echo_dash ();
+    echo_dash (map);
 
   /* Try reading a character via menu prompting in the minibuf.
      Try this before the sit-for, because the sit-for
@@ -2846,7 +2845,7 @@ read_char (int commandflag, Lisp_Object map,
 	 This is because we are probably about to display a menu,
 	 and we don't want to delay before doing so.  */
       if (EVENT_HAS_PARAMETERS (prev_event))
-	echo_now ();
+	echo_now (map);
       else
 	{
 	  Lisp_Object tem0;
@@ -2859,7 +2858,7 @@ read_char (int commandflag, Lisp_Object map,
 	  unbind_to (count, Qnil);
 	  if (EQ (tem0, Qt)
 	      && ! CONSP (Vunread_command_events))
-	    echo_now ();
+	    echo_now (map);
 	}
     }
 
@@ -3263,7 +3262,7 @@ read_char (int commandflag, Lisp_Object map,
       kset_echo_string (current_kboard, saved_echo_string);
       kset_echo_prompt (current_kboard, saved_echo_prompt);
       if (saved_immediate_echo)
-	echo_now ();
+	echo_now (map);
 
       /* The input method can return no events.  */
       if (! CONSP (tem))
@@ -10490,7 +10489,7 @@ read_key_sequence (Lisp_Object *keybuf, Lisp_Object prompt,
              since it forces us to fiddle with current_kboard->immediate_echo
              before and after.  */
 	  current_kboard->immediate_echo = false;
-	  echo_now ();
+	  echo_now (Qnil);
           if (!echo_keystrokes_p ())
 	    current_kboard->immediate_echo = false;
 	}
@@ -10499,7 +10498,7 @@ read_key_sequence (Lisp_Object *keybuf, Lisp_Object prompt,
 	       && echo_keystrokes_p ())
 	/* This doesn't put in a dash if the echo buffer is empty, so
 	   you don't always see a dash hanging out in the minibuffer.  */
-	echo_dash ();
+	echo_dash (Qnil);
     }
 
   /* Record the initial state of the echo area and this_command_keys;
@@ -10695,7 +10694,7 @@ read_key_sequence (Lisp_Object *keybuf, Lisp_Object prompt,
 	      /* Set immediate_echo to false so as to force echo_now to
 		 redisplay (it will set immediate_echo right back to true).  */
 	      current_kboard->immediate_echo = false;
-	      echo_now ();
+	      echo_now (Qnil);
 	    }
 	  used_mouse_menu = used_mouse_menu_history[t];
 	}

Re: discoverability, better defaults and which-key in Emacs

[Dmitry Gutov]

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

On 08/02/2024 18:12, Dmitry Gutov wrote:
> On 08/02/2024 16:43, Dmitry Gutov wrote:
>> If you can come up with a code that detects at run time that help-key
>> and/or F1 was rebound to a key that will not invoke
>> describe-prefix-bindings, such a key should indeed better be removed
>> from the message.  But can we reliably do that?  If we cannot, having
>> two keys there instead of one is better.
> 
> Here's a rough draft.
> 
> It seems to work in the basic cases that I've tried (changing help-char 
> to something with a binding and rebinding <f1>), but doesn't account for 
> key translations for far (e.g. if help-char is ?X and the prefix map has 
> ?x, this isn't caught).
> 
> Also, piping the current used map through so many methods is pretty 
> messy, I'm sure whether I've used the appropriate value in other 
> callsites of echo_now and echo_dash. There's also echo_update...
> 
> So if anybody has something simpler in mind that'd be welcome.

Here's that simpler version.

It doesn't address the "key translations" example above, but it seems 
rare enough, and it should be possible to fix later.

So I suggest we install this now.

[-- Attachment #2: echo_keystrokes_help_v4.diff --]
[-- Type: text/x-patch, Size: 1812 bytes --]

diff --git a/lisp/help.el b/lisp/help.el
index 72a4f8a800d..07eed2861c2 100644
--- a/lisp/help.el
+++ b/lisp/help.el
@@ -2253,6 +2253,27 @@ help-form-show
 	(with-output-to-temp-buffer " *Char Help*"
 	  (princ msg)))))
 
+(defun help--append-keystrokes-help (str)
+  (let* ((keys (this-single-command-keys))
+         (bindings (delete nil
+                           (mapcar (lambda (map) (lookup-key map keys t))
+                                   (current-active-maps t)))))
+    (catch 'res
+      (dolist (val help-event-list)
+        (let ((key (vector (if (eql val 'help)
+                               help-char
+                             val))))
+          (unless (seq-find (lambda (map) (and (keymapp map) (lookup-key map key)))
+                            bindings)
+            (throw 'res
+                   (concat
+                    str
+                    (substitute-command-keys
+                     (format
+                      " (\\`%s' for help)"
+                      (key-description key))))))))
+      str)))
+
 \f
 (defun help--docstring-quote (string)
   "Return a doc string that represents STRING.
diff --git a/src/keyboard.c b/src/keyboard.c
index 10cdef67348..8cc1b2ec756 100644
--- a/src/keyboard.c
+++ b/src/keyboard.c
@@ -594,14 +594,9 @@ echo_dash (void)
 		    concat2 (KVAR (current_kboard, echo_string), dash));
 
   if (echo_keystrokes_help)
-    {
-      Lisp_Object help;
-
-      help = build_string (" (\\`C-h' or \\`<f1>' for help)");
-      kset_echo_string (current_kboard,
-			concat2 (KVAR (current_kboard, echo_string),
-				 calln (Qsubstitute_command_keys, help)));
-    }
+    kset_echo_string (current_kboard,
+		      calln (intern_c_string ("help--append-keystrokes-help"),
+			     KVAR (current_kboard, echo_string)));
 
   echo_now ();
 }

Re: discoverability, better defaults and which-key in Emacs

[Po Lu]

Dmitry Gutov <dmitry@gutov.dev> writes:

> diff --git a/src/keyboard.c b/src/keyboard.c
> index 10cdef67348..8cc1b2ec756 100644
> --- a/src/keyboard.c
> +++ b/src/keyboard.c
> @@ -594,14 +594,9 @@ echo_dash (void)
>  		    concat2 (KVAR (current_kboard, echo_string), dash));
>  
>    if (echo_keystrokes_help)
> -    {
> -      Lisp_Object help;
> -
> -      help = build_string (" (\\`C-h' or \\`<f1>' for help)");
> -      kset_echo_string (current_kboard,
> -			concat2 (KVAR (current_kboard, echo_string),
> -				 calln (Qsubstitute_command_keys, help)));
> -    }
> +    kset_echo_string (current_kboard,
> +		      calln (intern_c_string ("help--append-keystrokes-help"),
> +			     KVAR (current_kboard, echo_string)));
>  
>    echo_now ();
>  }

Please replace the call to intern_c_string with a DEFSYM.  There's no
good reason not to.

Re: discoverability, better defaults and which-key in Emacs

[Dmitry Gutov]

On 11/02/2024 04:39, Po Lu wrote:
> Dmitry Gutov<dmitry@gutov.dev>  writes:
> 
>> diff --git a/src/keyboard.c b/src/keyboard.c
>> index 10cdef67348..8cc1b2ec756 100644
>> --- a/src/keyboard.c
>> +++ b/src/keyboard.c
>> @@ -594,14 +594,9 @@ echo_dash (void)
>>   		    concat2 (KVAR (current_kboard, echo_string), dash));
>>   
>>     if (echo_keystrokes_help)
>> -    {
>> -      Lisp_Object help;
>> -
>> -      help = build_string (" (\\`C-h' or \\`<f1>' for help)");
>> -      kset_echo_string (current_kboard,
>> -			concat2 (KVAR (current_kboard, echo_string),
>> -				 calln (Qsubstitute_command_keys, help)));
>> -    }
>> +    kset_echo_string (current_kboard,
>> +		      calln (intern_c_string ("help--append-keystrokes-help"),
>> +			     KVAR (current_kboard, echo_string)));
>>   
>>     echo_now ();
>>   }
> Please replace the call to intern_c_string with a DEFSYM.  There's no
> good reason not to.

Thanks, I'll do that when committing.

Re: discoverability, better defaults and which-key in Emacs

[Eli Zaretskii]

> Date: Sun, 11 Feb 2024 04:17:21 +0200
> From: Dmitry Gutov <dmitry@gutov.dev>
> Cc: visuweshm@gmail.com, justin@burkett.cc, philipk@posteo.net,
>  luangruo@yahoo.com, jb@jeremybryant.net, emacs-devel@gnu.org
> 
> Here's that simpler version.
> 
> It doesn't address the "key translations" example above, but it seems 
> rare enough, and it should be possible to fix later.
> 
> So I suggest we install this now.

This basically throws away the addition of F1 I did, doesn't it?  I
added it for a reason, and I don't want to lose it.  If you want to
make sure F1 is bound to help-command, and omit it from the message if
not, that is fine by me.  But I object to omitting it unconditionally.

Re: discoverability, better defaults and which-key in Emacs

[Dmitry Gutov]

On 11/02/2024 08:49, Eli Zaretskii wrote:
>> Date: Sun, 11 Feb 2024 04:17:21 +0200
>> From: Dmitry Gutov<dmitry@gutov.dev>
>> Cc:visuweshm@gmail.com,justin@burkett.cc,philipk@posteo.net,
>>   luangruo@yahoo.com,jb@jeremybryant.net,emacs-devel@gnu.org
>>
>> Here's that simpler version.
>>
>> It doesn't address the "key translations" example above, but it seems
>> rare enough, and it should be possible to fix later.
>>
>> So I suggest we install this now.
> This basically throws away the addition of F1 I did, doesn't it?  I
> added it for a reason, and I don't want to lose it.  If you want to
> make sure F1 is bound to help-command, and omit it from the message if
> not, that is fine by me.  But I object to omitting it unconditionally.

Not quite. <f1> is in help-event-list.

This function iterates among the available options, and if it sees that 
help-char is bound in the current prefix map(s), it tries <f1>, and if 
that one is bound as well, the last remaining element, which is '?'.

It also prints the value of help-char correctly if it was changed to a 
different value (if it's not bound in the current prefix map(s)).

Re: discoverability, better defaults and which-key in Emacs

[Eli Zaretskii]

> Date: Sun, 11 Feb 2024 14:26:38 +0200
> Cc: visuweshm@gmail.com, justin@burkett.cc, philipk@posteo.net,
>  luangruo@yahoo.com, jb@jeremybryant.net, emacs-devel@gnu.org
> From: Dmitry Gutov <dmitry@gutov.dev>
> 
> >> So I suggest we install this now.
> > This basically throws away the addition of F1 I did, doesn't it?  I
> > added it for a reason, and I don't want to lose it.  If you want to
> > make sure F1 is bound to help-command, and omit it from the message if
> > not, that is fine by me.  But I object to omitting it unconditionally.
> 
> Not quite. <f1> is in help-event-list.
> 
> This function iterates among the available options, and if it sees that 
> help-char is bound in the current prefix map(s), it tries <f1>, and if 
> that one is bound as well, the last remaining element, which is '?'.
> 
> It also prints the value of help-char correctly if it was changed to a 
> different value (if it's not bound in the current prefix map(s)).

OK, thanks.  Then I have no objections.

Re: discoverability, better defaults and which-key in Emacs

[Dmitry Gutov]

On 11/02/2024 17:00, Eli Zaretskii wrote:
>> This function iterates among the available options, and if it sees that
>> help-char is bound in the current prefix map(s), it tries <f1>, and if
>> that one is bound as well, the last remaining element, which is '?'.
>>
>> It also prints the value of help-char correctly if it was changed to a
>> different value (if it's not bound in the current prefix map(s)).
> OK, thanks.  Then I have no objections.

Very good. Pushed to master.

Re: discoverability, better defaults and which-key in Emacs

[Eli Zaretskii]

> Date: Thu, 8 Feb 2024 16:43:41 +0200
> Cc: visuweshm@gmail.com, justin@burkett.cc, philipk@posteo.net,
>  luangruo@yahoo.com, jb@jeremybryant.net, emacs-devel@gnu.org
> From: Dmitry Gutov <dmitry@gutov.dev>
> 
> >> If we consider the situations where C-h or f1 is rebound, having
> >> misleading text in the message (with bindings that don't work) should
> >> concern us as well. Even if one of the suggestions is likely to work
> >> anyway (while the other doesn't).
> > If you can come up with a code that detects at run time that help-key
> > and/or F1 was rebound to a key that will not invoke
> > describe-prefix-bindings, such a key should indeed better be removed
> > from the message.  But can we reliably do that?  If we cannot, having
> > two keys there instead of one is better.
> 
> I think we should be able to, but since help-key doesn't call any 
> command directly through a map or fallback binding of some sort (instead 
> it's dispatched ad-hoc), the solution I have tried so far (also using 
> substitute-command-keys) did not help.

Maybe Stefan (CC'ed) could have an idea.  In general, since the key
sequence was just echoed, we do know what sequence was typed, and can
test whether adding help-char to it would produce a binding, like what
we do in read_key_sequence where we decide whether to invoke
prefix-help-command.

Re: discoverability, better defaults and which-key in Emacs

[Dmitry Gutov]

On 08/02/2024 15:02, Eli Zaretskii wrote:
>> Date: Thu, 8 Feb 2024 14:18:34 +0200
>> Cc: justin@burkett.cc, philipk@posteo.net, luangruo@yahoo.com,
>>   jb@jeremybryant.net, emacs-devel@gnu.org
>> From: Dmitry Gutov <dmitry@gutov.dev>
>>
>> On 08/02/2024 08:59, Eli Zaretskii wrote:
>>> But
>>> I added F1 to that text, which should help if someone did change
>>> help-char.
>>
>> Whether help-char is changed, or 'C-h' is rebound anyway, can all be
>> detected at runtime. <f1> can also have a different binding in the
>> current prefix map--then the new message would be doubly incorrect.
> 
> How frequently do people rebind F1?  IME, never.

Sure, likewise with C-h. That's why the original patch was probably okay 
as-is.

> But I don't object to adding runtime detection of the help keys.

Good.

>> I'd rather we picked one (preferably correct) suggestion and printed that.
> 
> Most people will never rebind C-h.  Those who do could rebind it to a
> character that cannot be used in this situation because it is already
> bound in various prefix maps.  Having two alternatives there increases
> the probability that one of them will work.

If we consider the situations where C-h or f1 is rebound, having 
misleading text in the message (with bindings that don't work) should 
concern us as well. Even if one of the suggestions is likely to work 
anyway (while the other doesn't).

>> For context: I customize echo-keystrokes to a very low value and
>> currently see this help message quite often.
> 
> If the message annoys you, you can disable it.

Sure - this is not a deal-breaker. But the more features I disable the 
less problems I could find while dogfooding. Until now I've been running 
with it, and it seemed unobtrusive enough.

Runtime detection might even make it occasionally helpful in odd 
contexts where something shadows the binding.

Rebinding Fn [Re: discoverability, better defaults and which-key in Emacs]

[Alan Mackenzie]

Hello, Eli.

On Thu, Feb 08, 2024 at 15:02:50 +0200, Eli Zaretskii wrote:
> > Date: Thu, 8 Feb 2024 14:18:34 +0200
> > Cc: justin@burkett.cc, philipk@posteo.net, luangruo@yahoo.com,
> >  jb@jeremybryant.net, emacs-devel@gnu.org
> > From: Dmitry Gutov <dmitry@gutov.dev>

> > On 08/02/2024 08:59, Eli Zaretskii wrote:
> > > But
> > > I added F1 to that text, which should help if someone did change
> > > help-char.

> > Whether help-char is changed, or 'C-h' is rebound anyway, can all be 
> > detected at runtime. <f1> can also have a different binding in the 
> > current prefix map--then the new message would be doubly incorrect.

> How frequently do people rebind F1?  IME, never.

I bind F1 all the time, in the global map, and have done for over 20
years.  It selects the first created frame (which happens to be
conveniently called "F1" on a tty).  Likewise for F2 to F11.

Standard Emacs is strangely deficient in keyboard commands to select
frames.  C-x 5 o is unusably cumbersome if there are more than two or
three frames.

[ .... ]

-- 
Alan Mackenzie (Nuremberg, Germany).

Re: Rebinding Fn [Re: discoverability, better defaults and which-key in Emacs]

[Eli Zaretskii]

> Date: Thu, 8 Feb 2024 13:51:21 +0000
> Cc: Dmitry Gutov <dmitry@gutov.dev>, visuweshm@gmail.com, justin@burkett.cc,
>  philipk@posteo.net, luangruo@yahoo.com, jb@jeremybryant.net,
>  emacs-devel@gnu.org
> From: Alan Mackenzie <acm@muc.de>
> 
> > How frequently do people rebind F1?  IME, never.
> 
> I bind F1 all the time

And you need the help advice Dmitry added?

Re: Rebinding Fn [Re: discoverability, better defaults and which-key in Emacs]

[Alan Mackenzie]

Hello, Eli.

On Thu, Feb 08, 2024 at 15:55:36 +0200, Eli Zaretskii wrote:
> > Date: Thu, 8 Feb 2024 13:51:21 +0000
> > Cc: Dmitry Gutov <dmitry@gutov.dev>, visuweshm@gmail.com, justin@burkett.cc,
> >  philipk@posteo.net, luangruo@yahoo.com, jb@jeremybryant.net,
> >  emacs-devel@gnu.org
> > From: Alan Mackenzie <acm@muc.de>

> > > How frequently do people rebind F1?  IME, never.

> > I bind F1 all the time

> And you need the help advice Dmitry added?

No, of course not.  I just felt I needed to add a correction.  It is
perhaps unwise to suggest that something doable in Emacs hasn't been
done.  Somebody, somewhere, _will_ have done it.

-- 
Alan Mackenzie (Nuremberg, Germany).

Re: discoverability, better defaults and which-key in Emacs

[Po Lu]

Dmitry Gutov <dmitry@gutov.dev> writes:

> +  if (echo_keystrokes_help)
> +    {
> +      AUTO_STRING (help, " (\\`C-h' for help)");
> +      kset_echo_string (current_kboard,
> +			concat2 (KVAR (current_kboard, echo_string),
> +				 calln (Qsubstitute_command_keys, help)));
> +    }

Just for the record, calling functions defined in Lisp with automatic
variables as arguments will give rise to mysterious crashes down the
line.  Strings constructed by AUTO_STRING must never be returned,
provided to Lisp, or referenced after moving out of scope, as its name
suggests.

Re: discoverability, better defaults and which-key in Emacs

[Dmitry Gutov]

On 08/02/2024 15:25, Po Lu wrote:
> Dmitry Gutov<dmitry@gutov.dev>  writes:
> 
>> +  if (echo_keystrokes_help)
>> +    {
>> +      AUTO_STRING (help, " (\\`C-h' for help)");
>> +      kset_echo_string (current_kboard,
>> +			concat2 (KVAR (current_kboard, echo_string),
>> +				 calln (Qsubstitute_command_keys, help)));
>> +    }
> Just for the record, calling functions defined in Lisp with automatic
> variables as arguments will give rise to mysterious crashes down the
> line.  Strings constructed by AUTO_STRING must never be returned,
> provided to Lisp, or referenced after moving out of scope, as its name
> suggests.

It was used with 'concat' here to construct a new string.

Is that still a problem?

Re: discoverability, better defaults and which-key in Emacs

[Dmitry Gutov]

On 08/02/2024 15:27, Dmitry Gutov wrote:
> On 08/02/2024 15:25, Po Lu wrote:
>> Dmitry Gutov<dmitry@gutov.dev>  writes:
>>
>>> +  if (echo_keystrokes_help)
>>> +    {
>>> +      AUTO_STRING (help, " (\\`C-h' for help)");
>>> +      kset_echo_string (current_kboard,
>>> +            concat2 (KVAR (current_kboard, echo_string),
>>> +                 calln (Qsubstitute_command_keys, help)));
>>> +    }
>> Just for the record, calling functions defined in Lisp with automatic
>> variables as arguments will give rise to mysterious crashes down the
>> line.  Strings constructed by AUTO_STRING must never be returned,
>> provided to Lisp, or referenced after moving out of scope, as its name
>> suggests.
> 
> It was used with 'concat' here to construct a new string.
> 
> Is that still a problem?

Ah, I passed it to Lisp function first. Gotcha. Thanks.

Re: discoverability, better defaults and which-key in Emacs

[Eli Zaretskii]

> From: Jeremy Bryant <jb@jeremybryant.net>
> Date: Wed, 31 Jan 2024 23:23:29 +0000
> 
> A recent theme of discussion has been improving discoverability of Emacs
> features, and in a related way, 'better defaults'.
> 
> Here is a suggestion - include which-key in core and potentially enable
> by for new users.

How do we detect "new users"?

If we include which-key, but do not enable it by default, would that
be good enough?

Another idea is to add a feature whereby, after some delay after the
user types an incomplete key sequence, the buffer usually popped by
C-h or '?' pops up automatically.  This would be a smaller change in
the UX, which might therefore be more easily acceptable even by
not-so-new users.

Re: discoverability, better defaults and which-key in Emacs

[Jeremy Bryant]

Eli Zaretskii <eliz@gnu.org> writes:

>> From: Jeremy Bryant <jb@jeremybryant.net>
>> Date: Wed, 31 Jan 2024 23:23:29 +0000
>> 
>> A recent theme of discussion has been improving discoverability of Emacs
>> features, and in a related way, 'better defaults'.
>> 
>> Here is a suggestion - include which-key in core and potentially enable
>> by for new users.
>
> How do we detect "new users"?

Good question, how about a user entry on the splashscreen?

> If we include which-key, but do not enable it by default, would that
> be good enough?

Yes.
How can I help with this?

Move the .el files from the ELPA package into lisp/ ?
Manual entry- ?

>
> Another idea is to add a feature whereby, after some delay after the
> user types an incomplete key sequence, the buffer usually popped by
> C-h or '?' pops up automatically.  This would be a smaller change in
> the UX, which might therefore be more easily acceptable even by
> not-so-new users.

Interesting, which buffer and part of the code is this?
(it seems to appear in *Help*)

Re: discoverability, better defaults and which-key in Emacs

[Eli Zaretskii]

> From: Jeremy Bryant <jb@jeremybryant.net>
> Cc: justin@burkett.cc, emacs-devel@gnu.org
> Date: Thu, 01 Feb 2024 21:16:43 +0000
> 
> >> Here is a suggestion - include which-key in core and potentially enable
> >> by for new users.
> >
> > How do we detect "new users"?
> 
> Good question, how about a user entry on the splashscreen?

I don't think I understand, please elaborate.  Do you mean we will ask
users to say, up front, that they consider themselves "new users",
each time they start a new Emacs session?

> > If we include which-key, but do not enable it by default, would that
> > be good enough?
> 
> Yes.
> How can I help with this?
> 
> Move the .el files from the ELPA package into lisp/ ?
> Manual entry- ?

Something like that.  Philip and Stefan will be able to describe the
details.

> > Another idea is to add a feature whereby, after some delay after the
> > user types an incomplete key sequence, the buffer usually popped by
> > C-h or '?' pops up automatically.  This would be a smaller change in
> > the UX, which might therefore be more easily acceptable even by
> > not-so-new users.
> 
> Interesting, which buffer and part of the code is this?
> (it seems to appear in *Help*)

Yes, it appears in *Help*, and is produced by describe-prefix-bindings
(via prefix-help-command).

Re: discoverability, better defaults and which-key in Emacs

[Emanuel Berg]

Eli Zaretskii wrote:

>>>> Here is a suggestion - include which-key in core and
>>>> potentially enable by for new users.
>>>
>>> How do we detect "new users"?
>> 
>> Good question, how about a user entry on the splashscreen?
>
> I don't think I understand, please elaborate. Do you mean we
> will ask users to say, up front, that they consider
> themselves "new users", each time they start a new
> Emacs session?

Instead of Emacs finding out who is a new user or old, new and
old users alike should find what they look for in Emacs.

With configuration, maybe one can have a FAQ specifically for
that. If one has the 20 most common configuration use cases
listed with Elisp one-liners to do it, that would be a good
start. And beyond that, people already have experience anyway.

Another case is finding code in core Emacs and in ELPA to do
stuff so one don't spend time writing Elisp for that oneself.
This is an area where I failed big time myself. Maybe today
googling can offer more as much more code is available online?

Probably someone is working on an AI tool as we speak, so that
one can truly "ask Emacs".

I for one would be very interested to know what of my Elisp
I can discard in favor of using stuff in core Emacs.
But I don't have a confident answer how to find out.

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

Re: discoverability, better defaults and which-key in Emacs

[Eli Zaretskii]

> From: Emanuel Berg <incal@dataswamp.org>
> Date: Fri, 02 Feb 2024 08:00:22 +0100
> 
> Instead of Emacs finding out who is a new user or old, new and
> old users alike should find what they look for in Emacs.
> 
> With configuration, maybe one can have a FAQ specifically for
> that. If one has the 20 most common configuration use cases
> listed with Elisp one-liners to do it, that would be a good
> start. And beyond that, people already have experience anyway.

This idea came up several times here, and was met with a general
agreement, but no one stepped forward to work on those "most common
configurations".  And it is not easy to do, since the configurations
depend on the needs of the user (whether the user is a programmer and
in what language(s), what other tasks and jobs does the user want to
accomplish in Emacs -- email, todo items, etc.) and also some general
user preferences (mouse vs keyboard etc.).

Patches welcome, of course.

> Another case is finding code in core Emacs and in ELPA to do
> stuff so one don't spend time writing Elisp for that oneself.
> This is an area where I failed big time myself. Maybe today
> googling can offer more as much more code is available online?

The Emacs apropos commands, if used wisely, should help you.  You
might find that some of our documentation needs to be enhanced to make
discoverability easier, in which case please report the deficiencies,
so we could make this better.

> I for one would be very interested to know what of my Elisp
> I can discard in favor of using stuff in core Emacs.
> But I don't have a confident answer how to find out.

Some Emacs commands I suggest for this are:

  C-u M-x apropos
  M-x apropos-documentation
  C-h R elisp RET followed by 'i' (Info-index) and the subject

RE: [External] : Re: discoverability, better defaults and which-key in Emacs

[Drew Adams]

> > Another case is finding code in core Emacs and in ELPA to do
> > stuff so one don't spend time writing Elisp for that oneself.
> > This is an area where I failed big time myself. Maybe today
> > googling can offer more as much more code is available online?
> 
> The Emacs apropos commands, if used wisely, should help you.  You
> might find that some of our documentation needs to be enhanced to make
> discoverability easier, in which case please report the deficiencies,
> so we could make this better.
> 
> > I for one would be very interested to know what of my Elisp
> > I can discard in favor of using stuff in core Emacs.
> > But I don't have a confident answer how to find out.
> 
> Some Emacs commands I suggest for this are:
>   C-u M-x apropos
>   M-x apropos-documentation
>   C-h R elisp RET followed by 'i' (Info-index) and the subject

+1 to all of that.
___

The most important aid for users - esp. but not
only new users - is IMHO for them to learn how
to better "ask Emacs".  Emacs provides lots of
ways to discover and find things, from the most
common or superficial things (help keys, menus)
to those deepest in its belly (Lisp, C).

That fact isn't obvious to new users, and even
old users can benefit from being reminded of it.
Learning better how to ask Emacs is always
possible, regardless of level of familiarity or
years of use.
___

Every top-level, superficially obvious point of
entry could help pass the message to a user to
help yourself by learning better how to "ask
Emacs".  Top-level entry points can include
toolbar, menu-bar Help menu, splash screen,
`C-h t' tutorial,...
___

[ Maybe even every *Help* buffer could have a
  link (the same one-line link) to a manual
  entry or to some other presentation of info
  about asking Emacs (i.e., finding things).

  Perhaps with an added boost from AI-thingies,
  such a link could be *Help*-context sensitive.

  And perhaps (with AI) some actions that users
  take could (optionally) sometimes be followed
  by a popup tip about a handy (maybe quicker)
  way to ask Emacs about something they seem to
  be looking for or not be aware of. ]

Re: [External] : Re: discoverability, better defaults and which-key in Emacs

[Emanuel Berg]

Drew Adams wrote:

>>> I for one would be very interested to know what of my
>>> Elisp I can discard in favor of using stuff in core Emacs.
>>> But I don't have a confident answer how to find out.
>> 
>> Some Emacs commands I suggest for this are:
>>   C-u M-x apropos
>>   M-x apropos-documentation
>>   C-h R elisp RET followed by 'i' (Info-index) and the subject
>
> +1 to all of that.
>
> The most important aid for users - esp. but not only new
> users - is IMHO for them to learn how to better "ask Emacs".

If sorted alphabetically, this is my first Elisp file, abc.el.

After that, the second file, align-from-left.el.

How do I ask Emacs if someone already wrote it and made
it available?

I think part of the problem is before one has programmed it,
it is very difficult to formulate it in an exact way, and one
doesn't always have a clear image what one is doing, even.

I'm not challenging anyone to ask Emacs, rather ... they are
two examples what stuff I have been writing and many, many
times wondered how anyone would ever know, what everyone else
are writing. Someone else must have already written it, right?

Interestingly, it is often easier to find advanced, specialized
stuff than small math and data manipulation functions.
Since they are so general, if one searches, one gets a lot of
hits, a lot of them doing something quite similar but not
exactly the same.

Maybe someone already tried to have Lisp with standard
libraries. Several times?

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

(require 'cl-lib)

(defun alphabet (&optional as-list)
  (let ((abc "a b c d e f g h i j k l m n o p q r s t u v w x y z"))
    (if as-list
        (cl-remove ?\s (string-to-list abc))
      abc) ))

;; (alphabet)   ; a b c d e f g h i j k l m n o p q r s t u v w x y z
;; (alphabet t) ; (97 98 99 100 101 102 103 104 105 106 107 108 ...)

(defun echo-alphabet (&optional num)
  (interactive "P")
  (or num (setq num (length (alphabet t))))
  (let*((part       (cl-subseq (alphabet t) 0 num))
        (str-list   (mapcar (lambda (c) (char-to-string c)) part))
        (str-almost (format "%s" str-list))
        (str        (substring str-almost 1 (1- (length str-almost)))) )
    (message str) ))

(defalias 'abc #'echo-alphabet)

;; (echo-alphabet)     ; a b c d e f g h i j k l m n o p q r s t u v w x y z
;; (echo-alphabet   2) ; a b
;; (echo-alphabet  -2) ; a b c d e f g h i j k l m n o p q r s t u v w x
;; (echo-alphabet  10) ; a b c d e f g h i j
;; (echo-alphabet -10) ; a b c d e f g h i j k l m n o p

(provide 'abc)

;;; -*- lexical-binding: t -*-
;;
;; this file:
;;   https://dataswamp.org/~incal/emacs-init/align-from-left.el

(require 'cl-lib)

(let ((alf-regexp))
  (defun align-from-left (&optional set-regexp)
    (interactive "p")
    (let ((default-regexp "^\\|[[:punct:]]\\|[[:space:]][[:alnum:]]"))
      (unless (stringp set-regexp)
        (cl-case set-regexp
          ( 4 (setq alf-regexp (read-regexp "regexp: ")))
          (16 (setq alf-regexp default-regexp))
          ( t (unless alf-regexp
                (setq alf-regexp default-regexp) )))))
    (let ((beg (point))
          (re  (or (and (stringp set-regexp) set-regexp)
                    alf-regexp) ))
      (when (re-search-backward re (line-beginning-position) t)
        (while (looking-at "[[:space:]]")
          (forward-char) )
        (insert (make-string (- beg (point)) ?\s)) ))))

(declare-function align-from-left nil)

(provide 'align-from-left)


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

Re: [External] : Re: discoverability, better defaults and which-key in Emacs

[Emanuel Berg]

Drew Adams wrote:

> And perhaps (with AI) some actions that users take could
> (optionally) sometimes be followed by a popup tip about
> a handy (maybe quicker) way to ask Emacs about something
> they seem to be looking for or not be aware of.

One will document the individual pieces and they will be nodes
in a huge AI-searchable network, so that everyone can polish
their gems in peace and quiet, then AI will help newcomers
navigate and integrate everything seamlessly :)

One should feed the entire Emacs world, all Usenet groups,
mailing lists, web forums and so on into an AI and train it on
that. And of course the source and documentation and manual.

And #emacs as well, the entire backlog. If the AI can figure
out what is offtopic, jokes etc.

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

Re: [External] : Re: discoverability, better defaults and which-key in Emacs

[Jeremy Bryant]

> +1 to all of that.
> ___
>
> The most important aid for users - esp. but not
> only new users - is IMHO for them to learn how
> to better "ask Emacs".  Emacs provides lots of
> ways to discover and find things, from the most
> common or superficial things (help keys, menus)
> to those deepest in its belly (Lisp, C).
>
> That fact isn't obvious to new users, and even
> old users can benefit from being reminded of it.
> Learning better how to ask Emacs is always
> possible, regardless of level of familiarity or
> years of use.
> ___
>
> Every top-level, superficially obvious point of
> entry could help pass the message to a user to
> help yourself by learning better how to "ask
> Emacs".  Top-level entry points can include
> toolbar, menu-bar Help menu, splash screen,
> `C-h t' tutorial,...
> ___
>
> [ Maybe even every *Help* buffer could have a
>   link (the same one-line link) to a manual
>   entry or to some other presentation of info
>   about asking Emacs (i.e., finding things).
>
>   Perhaps with an added boost from AI-thingies,
>   such a link could be *Help*-context sensitive.
>
>   And perhaps (with AI) some actions that users
>   take could (optionally) sometimes be followed
>   by a popup tip about a handy (maybe quicker)
>   way to ask Emacs about something they seem to
>   be looking for or not be aware of. ]

How about discoverability regular reminders being a user-option (called something like
discoverability-help-buffer), available to new and veteran users alike?

This would make the *Help* buffers bigger but with useful reminders such
as C-h S info-lookup-symbol to jump to the manual etc, and can be turned
off at will?

Re: discoverability, better defaults and which-key in Emacs

[Jeremy Bryant]

Eli Zaretskii <eliz@gnu.org> writes:

>> From: Emanuel Berg <incal@dataswamp.org>
>> Date: Fri, 02 Feb 2024 08:00:22 +0100
>> 
>> Instead of Emacs finding out who is a new user or old, new and
>> old users alike should find what they look for in Emacs.
>> 
>> With configuration, maybe one can have a FAQ specifically for
>> that. If one has the 20 most common configuration use cases
>> listed with Elisp one-liners to do it, that would be a good
>> start. And beyond that, people already have experience anyway.
>
> This idea came up several times here, and was met with a general
> agreement, but no one stepped forward to work on those "most common
> configurations".  And it is not easy to do, since the configurations
> depend on the needs of the user (whether the user is a programmer and
> in what language(s), what other tasks and jobs does the user want to
> accomplish in Emacs -- email, todo items, etc.) and also some general
> user preferences (mouse vs keyboard etc.).
>
> Patches welcome, of course.

Would it be useful to have a few 'starter' commented init files /
configurations.
This would be a built-in version of personal init files, but very small,
and commented.

I can work on such minimal configurations, would you suggest a patch
somewhere specifically in the Emacs tree?  I can work on a patch.



>> Another case is finding code in core Emacs and in ELPA to do
>> stuff so one don't spend time writing Elisp for that oneself.
>> This is an area where I failed big time myself. Maybe today
>> googling can offer more as much more code is available online?
>
> The Emacs apropos commands, if used wisely, should help you.  You
> might find that some of our documentation needs to be enhanced to make
> discoverability easier, in which case please report the deficiencies,
> so we could make this better.
>
>> I for one would be very interested to know what of my Elisp
>> I can discard in favor of using stuff in core Emacs.
>> But I don't have a confident answer how to find out.
>
> Some Emacs commands I suggest for this are:
>
>   C-u M-x apropos
>   M-x apropos-documentation
>   C-h R elisp RET followed by 'i' (Info-index) and the subject

Would it make sense to have a specific small section in the Emacs manual
that
Then a link to that manual section could be provided early on
A sort of 'discoverability start point'?
I can work on a manual patch if you think this would be a good place for
it?

Re: discoverability, better defaults and which-key in Emacs

[Eli Zaretskii]

> From: Jeremy Bryant <jb@jeremybryant.net>
> Cc: Emanuel Berg <incal@dataswamp.org>, emacs-devel@gnu.org
> Date: Sat, 03 Feb 2024 11:39:50 +0000
> 
> 
> Eli Zaretskii <eliz@gnu.org> writes:
> 
> >> From: Emanuel Berg <incal@dataswamp.org>
> >> Date: Fri, 02 Feb 2024 08:00:22 +0100
> >> 
> >> Instead of Emacs finding out who is a new user or old, new and
> >> old users alike should find what they look for in Emacs.
> >> 
> >> With configuration, maybe one can have a FAQ specifically for
> >> that. If one has the 20 most common configuration use cases
> >> listed with Elisp one-liners to do it, that would be a good
> >> start. And beyond that, people already have experience anyway.
> >
> > This idea came up several times here, and was met with a general
> > agreement, but no one stepped forward to work on those "most common
> > configurations".  And it is not easy to do, since the configurations
> > depend on the needs of the user (whether the user is a programmer and
> > in what language(s), what other tasks and jobs does the user want to
> > accomplish in Emacs -- email, todo items, etc.) and also some general
> > user preferences (mouse vs keyboard etc.).
> >
> > Patches welcome, of course.
> 
> Would it be useful to have a few 'starter' commented init files /
> configurations.
> This would be a built-in version of personal init files, but very small,
> and commented.

I think the idea was to have an interactive feature, whereby a user is
asked questions regarding his/her preferences and needs, and the
related features are then enabled.

A related idea was to come up with mostly-independent groups of
settings that are suitable for some general usage pattern.  For
example, someone who needs to develop Python programs might want
certain optional features enabled.

Having init files like you suggest once again places the burden on the
users to read the comments and decide what to do about them.  I think
this is not the optimal solution.

> > Some Emacs commands I suggest for this are:
> >
> >   C-u M-x apropos
> >   M-x apropos-documentation
> >   C-h R elisp RET followed by 'i' (Info-index) and the subject
> 
> Would it make sense to have a specific small section in the Emacs manual
> that
> Then a link to that manual section could be provided early on
> A sort of 'discoverability start point'?

We already have it: see the beginning of the "Help" node in the user
manual.

Re: discoverability, better defaults and which-key in Emacs

[Jeremy Bryant]

>> > Patches welcome, of course.
>> 
>> Would it be useful to have a few 'starter' commented init files /
>> configurations.
>> This would be a built-in version of personal init files, but very small,
>> and commented.
>
> I think the idea was to have an interactive feature, whereby a user is
> asked questions regarding his/her preferences and needs, and the
> related features are then enabled.
>
> A related idea was to come up with mostly-independent groups of
> settings that are suitable for some general usage pattern.  For
> example, someone who needs to develop Python programs might want
> certain optional features enabled.
>
> Having init files like you suggest once again places the burden on the
> users to read the comments and decide what to do about them.  I think
> this is not the optimal solution.

I understand.  How should this be implemented, would this be a new file
in the Emacs tree, or part of an existing file.
I can volunteer to work on an early prototype.

>
>> > Some Emacs commands I suggest for this are:
>> >
>> >   C-u M-x apropos
>> >   M-x apropos-documentation
>> >   C-h R elisp RET followed by 'i' (Info-index) and the subject
>> 
>> Would it make sense to have a specific small section in the Emacs manual
>> that
>> Then a link to that manual section could be provided early on
>> A sort of 'discoverability start point'?
>
> We already have it: see the beginning of the "Help" node in the user
> manual.

Good.  As part of a discoverability feature, perhaps we could link to
this node in more places, eg in C-h C-h itself

Re: discoverability, better defaults and which-key in Emacs

[Eli Zaretskii]

> From: Jeremy Bryant <jb@jeremybryant.net>
> Cc: incal@dataswamp.org, emacs-devel@gnu.org
> Date: Sat, 03 Feb 2024 14:07:19 +0000
> 
> > I think the idea was to have an interactive feature, whereby a user is
> > asked questions regarding his/her preferences and needs, and the
> > related features are then enabled.
> >
> > A related idea was to come up with mostly-independent groups of
> > settings that are suitable for some general usage pattern.  For
> > example, someone who needs to develop Python programs might want
> > certain optional features enabled.
> >
> > Having init files like you suggest once again places the burden on the
> > users to read the comments and decide what to do about them.  I think
> > this is not the optimal solution.
> 
> I understand.  How should this be implemented, would this be a new file
> in the Emacs tree, or part of an existing file.
> I can volunteer to work on an early prototype.

I think a separate file is the best, thanks.

> Good.  As part of a discoverability feature, perhaps we could link to
> this node in more places, eg in C-h C-h itself

We could do that, but there's always the discoverability of "C-h C-h"
itself...

Re: discoverability, better defaults and which-key in Emacs

[Jeremy Bryant]

Eli,

Eli Zaretskii <eliz@gnu.org> writes:
>> I understand.  How should this be implemented, would this be a new file
>> in the Emacs tree, or part of an existing file.
>> I can volunteer to work on an early prototype.
>
> I think a separate file is the best, thanks.

OK, noted

>
>> Good.  As part of a discoverability feature, perhaps we could link to
>> this node in more places, eg in C-h C-h itself
>
> We could do that, but there's always the discoverability of "C-h C-h"
> itself...

From emacs -q, the first line is "Get help" which lands in "C-h C-h"

THe info node @Help is indeed very useful, but it takes several hops
from emacs -q to even get to it (perhaps via the whole manual)
I would suggest it would be helpful to insert a reference to @Help in a
much more obvious way, perhaps at the top of C-h C-h

- Would this be useful as a patch now?
- Should this be reserved as part of a 'discoverability' functionality or setting?

Re: discoverability, better defaults and which-key in Emacs

[Eli Zaretskii]

> From: Jeremy Bryant <jb@jeremybryant.net>
> Cc: incal@dataswamp.org, emacs-devel@gnu.org
> Date: Sun, 04 Feb 2024 22:18:48 +0000
> 
> >From emacs -q, the first line is "Get help" which lands in "C-h C-h"
> 
> THe info node @Help is indeed very useful, but it takes several hops
> from emacs -q to even get to it (perhaps via the whole manual)
> I would suggest it would be helpful to insert a reference to @Help in a
> much more obvious way, perhaps at the top of C-h C-h
> 
> - Would this be useful as a patch now?

I don't think so.  It might actually confuse because people who type
"C-h C-h" usually want quick and concise help.

> - Should this be reserved as part of a 'discoverability' functionality or setting?

The former, I think (IIUC what you mean by that).

Re: discoverability, better defaults and which-key in Emacs

[Jeremy Bryant]

Eli,

>> >> Here is a suggestion - include which-key in core and potentially enable
>> >> by for new users.
>> >
>> > How do we detect "new users"?
>> 
>> Good question, how about a user entry on the splashscreen?
>
> I don't think I understand, please elaborate.  Do you mean we will ask
> users to say, up front, that they consider themselves "new users",
> each time they start a new Emacs session?

Perhaps something like a persistent 'new user or discoverability'
flag.
This would be toggled by the user, and could be suggested by Emacs based
on heuristics such as
- Absence of init file (.emacs)
- First launch of Emacs, maybe a reminder later

>
>> > Another idea is to add a feature whereby, after some delay after the
>> > user types an incomplete key sequence, the buffer usually popped by
>> > C-h or '?' pops up automatically.  This would be a smaller change in
>> > the UX, which might therefore be more easily acceptable even by
>> > not-so-new users.
>> 
>> Interesting, which buffer and part of the code is this?
>> (it seems to appear in *Help*)
>
> Yes, it appears in *Help*, and is produced by describe-prefix-bindings
> (via prefix-help-command).

Thank you for the suggestion, I will look at this part of the code.

Moving which-key ELPA package into core - Re: discoverability, better defaults and which-key in Emacs

[Jeremy Bryant]

>
>> > If we include which-key, but do not enable it by default, would that
>> > be good enough?
>> 
>> Yes.
>> How can I help with this?
>> 
>> Move the .el files from the ELPA package into lisp/ ?
>> Manual entry- ?
>
> Something like that.  Philip and Stefan will be able to describe the
> details.
>

Philip, Stefan, kindly provide some guidance on what work is needed?

Re: Moving which-key ELPA package into core - Re: discoverability, better defaults and which-key in Emacs

[Stefan Monnier]

>>> Move the .el files from the ELPA package into lisp/ ?
>>> Manual entry- ?
>> Something like that.  Philip and Stefan will be able to describe the
>> details.
> Philip, Stefan, kindly provide some guidance on what work is needed?

There's no predefined way to do it.  The details depend on what you/we
care about (e.g. do we want to keep updating the GNU ELPA `which-key`
package in the future?  If so, do we want to do that by having
a separate upstream from which we "pull" both into `elpa.git` and
`emacs.git` or do we prefer to generate the GNU ELPA package directly
out of the `emacs.git` code? ...).

And most of it can be figured out along the way (i.e. fixed after the
fact), so I'd say to "just do it" and fix the problems you see as they
come up.


        Stefan

Re: Moving which-key ELPA package into core - Re: discoverability, better defaults and which-key in Emacs

[Jeremy Bryant]

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

>>>> Move the .el files from the ELPA package into lisp/ ?
>>>> Manual entry- ?
>>> Something like that.  Philip and Stefan will be able to describe the
>>> details.
>> Philip, Stefan, kindly provide some guidance on what work is needed?
>
> There's no predefined way to do it.  The details depend on what you/we
> care about (e.g. do we want to keep updating the GNU ELPA `which-key`
> package in the future?  If so, do we want to do that by having
> a separate upstream from which we "pull" both into `elpa.git` and
> `emacs.git` or do we prefer to generate the GNU ELPA package directly
> out of the `emacs.git` code? ...).
>
> And most of it can be figured out along the way (i.e. fixed after the
> fact), so I'd say to "just do it" and fix the problems you see as they
> come up.
>
>
>         Stefan

Thank you, based on this, I have submitted a patch as bug #68929

If, as appears in the original email, the package is no longer
maintained upstream, it could be maintained in emacs.git

Re: Moving which-key ELPA package into core - Re: discoverability, better defaults and which-key in Emacs

[Stefan Monnier]

> Thank you, based on this, I have submitted a patch as bug #68929
>
> If, as appears in the original email, the package is no longer
> maintained upstream, it could be maintained in emacs.git

Sounds good to me,


        Stefan

Re: discoverability, better defaults and which-key in Emacs

[orzodk]

Eli Zaretskii <eliz@gnu.org> writes:

>> From: Jeremy Bryant <jb@jeremybryant.net>
>> Date: Wed, 31 Jan 2024 23:23:29 +0000
>> 
>> A recent theme of discussion has been improving discoverability of Emacs
>> features, and in a related way, 'better defaults'.
>> 
>> Here is a suggestion - include which-key in core and potentially enable
>> by for new users.
>
> How do we detect "new users"?

As a new user, I ran through help-with-tutorial early on. Maybe adding a
note or suggestion somewhere there is good enough.

Re: discoverability, better defaults and which-key in Emacs

[Jeremy Bryant]

>>
>> How do we detect "new users"?
>
> As a new user, I ran through help-with-tutorial early on. Maybe adding a
> note or suggestion somewhere there is good enough.

Do you mean the TUTORIAL accessible through C-h t?

Re: discoverability, better defaults and which-key in Emacs

[orzodk]

Jeremy Bryant <jb@jeremybryant.net> writes:

>>>
>>> How do we detect "new users"?
>>
>> As a new user, I ran through help-with-tutorial early on. Maybe adding a
>> note or suggestion somewhere there is good enough.
>
> Do you mean the TUTORIAL accessible through C-h t?

Yes. C-h t is bound to the help-with-tutorial function by default.

Re: discoverability, better defaults and which-key in Emacs

[Eli Zaretskii]

> From: orzodk <orzodk@fastmail.com>
> Cc: Jeremy Bryant <jb@jeremybryant.net>,  justin@burkett.cc,
>   emacs-devel@gnu.org
> Date: Thu, 01 Feb 2024 14:17:12 -0700
> 
> Eli Zaretskii <eliz@gnu.org> writes:
> 
> >> Here is a suggestion - include which-key in core and potentially enable
> >> by for new users.
> >
> > How do we detect "new users"?
> 
> As a new user, I ran through help-with-tutorial early on. Maybe adding a
> note or suggestion somewhere there is good enough.

That's unreliable.  Users read the tutorial a small number of times,
and a note buried inside it somewhere will go unnoticed or will be
forgotten.  And what about new users who bypass the tutorial
completely?

In any case, the suggestion to which I responded was to _enable_
which-keys for such users, not just to tell them the feature exists.
If we are going to enable which-keys for some class of users, it is
IMO very important to be able to identify them with almost no false
positives, because otherwise the enabled feature might annoy users who
don't expect these popups.

Re: discoverability, better defaults and which-key in Emacs

[Howard Melman]

Eli Zaretskii <eliz@gnu.org> writes:

>> Here is a suggestion - include which-key in core and potentially enable
>> by for new users.
>
> How do we detect "new users"?

I wonder if a mechanism like disabling could be used?

According to the elisp manual:

"Disabling is used for commands which might be confusing to
beginning users, to prevent them from using the commands by
accident."

Maybe a different property could exist for commands or modes
that are enabled by default for beginners and when used
could prompt to disable them if the user wants?

-- 

Howard

Re: discoverability, better defaults and which-key in Emacs

[Eli Zaretskii]

> From: Howard Melman <hmelman@gmail.com>
> Date: Fri, 02 Feb 2024 11:00:30 -0500
> 
> 
> Eli Zaretskii <eliz@gnu.org> writes:
> 
> >> Here is a suggestion - include which-key in core and potentially enable
> >> by for new users.
> >
> > How do we detect "new users"?
> 
> I wonder if a mechanism like disabling could be used?
> 
> According to the elisp manual:
> 
> "Disabling is used for commands which might be confusing to
> beginning users, to prevent them from using the commands by
> accident."
> 
> Maybe a different property could exist for commands or modes
> that are enabled by default for beginners and when used
> could prompt to disable them if the user wants?

Since we are talking about _enabling_ the feature, the above would
mean that veteran users will need to be asked whether to _disable_ it.
Wouldn't that be an annoyance?

Re: discoverability, better defaults and which-key in Emacs

[tomas]

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

On Fri, Feb 02, 2024 at 09:24:55PM +0200, Eli Zaretskii wrote:

[...]

> Since we are talking about _enabling_ the feature, the above would
> mean that veteran users will need to be asked whether to _disable_ it.
> Wouldn't that be an annoyance?

For this one it would, yes. An unexpected popup can ruin my day.

So I'd really, really like to know that it is actually going to
help someone, then I'd be willing to go the extra mile and disable
it for me.

Cheers & thanks
-- 
t

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 195 bytes --]

Re: discoverability, better defaults and which-key in Emacs

[Howard Melman]

<tomas@tuxteam.de> writes:

> On Fri, Feb 02, 2024 at 09:24:55PM +0200, Eli Zaretskii wrote:
>
>> Since we are talking about _enabling_ the feature, the
>> above would mean that veteran users will need to be asked
>> whether to _disable_ it.  Wouldn't that be an annoyance?
>
> For this one it would, yes. An unexpected popup can ruin
> my day.

If, like disabling works, it would write to the init and it
would be a one-time annoyance, I don't think it's a big
deal.

If this debuted with a handful of beginner features
configured as such, the NEWS could mention it and tell
vererans to put a small block of code in their init to turn
off things they don't want.  Veterans are more likely to
read NEWS than newbies.

> So I'd really, really like to know that it is actually
> going to help someone, then I'd be willing to go the extra
> mile and disable it for me.

A lot of newbies find which-key very useful.  I'm a long
time user and often find it useful.  Especially for
"newfangled" prefixes like M-g, M-s, C-x x, etc. :)

I don't know what other beginner features might qualify,
that would have to be evaluated carefully, but for a few,
this idea occurred to me as a way to have it enabled for
newbies using a small variation of a mechanism that exists
for a similar purpose.

-- 

Howard

Re: discoverability, better defaults and which-key in Emacs

[Emanuel Berg]

Howard Melman wrote:

> A lot of newbies find which-key very useful. I'm a long time
> user and often find it useful. Especially for "newfangled"
> prefixes like M-g, M-s, C-x x, etc. :)
>
> I don't know what other beginner features might qualify [...]

I don't like the division between beginners and veterans
necessarily but here is such a feature, possibly.

[ Note the exotic interface BTW with interactive recursion. ]

;;; -*- lexical-binding: t -*-
;;
;; this file:
;;   https://dataswamp.org/~incal/emacs-init/show-command.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

(provide 'show-command)

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

Re: discoverability, better defaults and which-key in Emacs

[Eli Zaretskii]

> From: Howard Melman <hmelman@gmail.com>
> Date: Fri, 02 Feb 2024 15:16:29 -0500
> 
> <tomas@tuxteam.de> writes:
> 
> > On Fri, Feb 02, 2024 at 09:24:55PM +0200, Eli Zaretskii wrote:
> >
> >> Since we are talking about _enabling_ the feature, the
> >> above would mean that veteran users will need to be asked
> >> whether to _disable_ it.  Wouldn't that be an annoyance?
> >
> > For this one it would, yes. An unexpected popup can ruin
> > my day.
> 
> If, like disabling works, it would write to the init and it
> would be a one-time annoyance, I don't think it's a big
> deal.

I tend to think it's a big deal.

But maybe we could look at the result of

  (get 'narrow-to-region 'disabled)

to deduce that if that is nil, we are dealing with a user who is not
new, even if the key-bindings popup is not disabled.  If which-key is
also turned off in "emacs -Q", perhaps that would be good enough?

And I still think that automatically popping up the *Help* buffer
produced by describe-prefix-bindings is simpler and more coherent with
the rest of Emacs than what which-key does.  We could still import
which-key as an optional feature, of course, even if the automatic
popup of describe-prefix-bindings is implemented.

RE: [External] : Re: discoverability, better defaults and which-key in Emacs

[Drew Adams]

Not to distract, but FYI library `keysee.el' is
an alternative to which-key.  Less known, some
differences, maybe worth checking out.

In particular, it lets you sort key-completion
candidates in different ways interactively: 

 - By key name alphabetically, prefix keys first

 - By key name alphabetically, local keys first

 - By command name alphabetically

 - Off (no sorting)

You can cycle among them during completion using
`C-,` (default of option `sorti-sort-cycle-key').

(You can cycle among key choices with `TAB', per
standard option `completion-cycle-threshold'.) 

Two global minor modes:

 - `kc-mode': on-demand completion with `S-TAB'
   (default of option `kc-completion-keys')

 - `kc-auto-mode': completion after idle delay
   (also turns on/off `kc-mode', for on-demand)

Both provide (1) top-level completion (on-demand:
`S-TAB'), which shows you the keys available in
the current context, and (2) completion after a
prefix key.

For top-level completion, choose the keymaps in
which to bind `S-TAB' for key completion, using
option `kc-keymaps-for-key-completion'.

keysee.el uses sortie.el, which provides general
interactive sorting of completion candidates
(usable for any completion).
___

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

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

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

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

Re: [External] : Re: discoverability, better defaults and which-key in Emacs

[Jeremy Bryant]

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

> Not to distract, but FYI library `keysee.el' is
> an alternative to which-key.  Less known, some
> differences, maybe worth checking out.

Interesting
It seems you are author?
Would you suggest this as a candidate for core or ELPA?

Re: [External] : Re: discoverability, better defaults and which-key in Emacs

[Emanuel Berg]

Jeremy Bryant wrote:

>> Not to distract, but FYI library `keysee.el' is an
>> alternative to which-key. Less known, some differences,
>> maybe worth checking out.
>
> Interesting
> It seems you are author?
> Would you suggest this as a candidate for core or ELPA?

Note that if he put his stuff in GNU ELPA, he would still be
allowed to mention it on this list and have it on the
EmacsWiki. With a reference to the ELPA package, could
be beneficial.

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

Re: [External] : Re: discoverability, better defaults and which-key in Emacs

[Emanuel Berg]

>>> Not to distract, but FYI library `keysee.el' is an
>>> alternative to which-key. Less known, some differences,
>>> maybe worth checking out.
>>
>> Interesting It seems you are author? Would you suggest this
>> as a candidate for core or ELPA?
>
> Note that if he put his stuff in GNU ELPA, he would still be
> allowed to mention it on this list and have it on the
> EmacsWiki

"allowed", encouraged.

If y'all just read what I think, not what I type.

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

RE: [External] : Re: discoverability, better defaults and which-key in Emacs

[Drew Adams]

> > Not to distract, but FYI library `keysee.el' is
> > an alternative to which-key.  Less known, some
> > differences, maybe worth checking out.
> 
> Interesting
> It seems you are author?
> Would you suggest this as a candidate for core or ELPA?

Doesn't matter to me.  Just posted the
info as an FYI.  Keysee does things
differently from which-key, but there
are many similarities.

Probably no reason to provide both as
part of Emacs.  But perhaps some of the
keysee features are of interest.

I think maybe which-key has by now
implemented some of them (e.g. on-demand,
in addition to automatic? top-level, in
addition to post-prefix?), but I'm no
expert on this.

I mentioned on-the-fly sorting.

That, plus ability to also match against
command names (or combinations of key
and command names) are a couple features
that I think which-key might lack.

Re: [External] : Re: discoverability, better defaults and which-key in Emacs

[Emanuel Berg]

Drew Adams wrote:

>>> Not to distract, but FYI library `keysee.el' is an
>>> alternative to which-key. Less known, some differences,
>>> maybe worth checking out.
>> 
>> Interesting
>> It seems you are author?
>> Would you suggest this as a candidate for core or ELPA?
>
> Doesn't matter to me

It matters to other people if you want them to use your
software, they are much more unlikely to read your post here
or find it randomly on the EmacsWiki and install it manually,
than if it is a repository package ready to be installed using
an interface for that purpose that they already know.

But for the record I'm probably even worse than you in this
respect, I have 196 files of Elisp, 10 980 sloc, and only made
a single package for GNU ELPA of all of that. And never added
anything to the EmacsWiki :$

Not saying all of that is useful to anyone else or even me, of
course, but I think maybe I could and should make two or three
more packages for the repos of the stuff I'm most happy with.
[Just difficult to figure out what that is, exactly? I don't
even know what parts I myself use since I just use it without
thinking by now.]

And I think it is a good idea for you as well, so other people
can benefit from what you have created.

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

Re: [External] : Re: discoverability, better defaults and which-key in Emacs

[Divya Ranjan]

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

> Not to distract, but FYI library `keysee.el' is
> an alternative to which-key.  Less known, some
> differences, maybe worth checking out.

The dependency on `sortie.el` is actually cumbersome, that said
`keysee.el` implements a totally non-intrusive mini-buffer completion
for keybinding suggestions.

I remember using `which-key` and implementing golden-ratio to my
windows, things messed up because `which-key` suggestions are in a
proper window, thus potentially intrusive. One can fix this, as a lot of
people do but if this is to be integrated into core Emacs one needs to
take care of that.

Honestly, I believe if we can just add it as a part of the customizable
UI then it'd be great. Just like we have `ido-completion`, or the
ability to have menu items on the GUI, we can add a keybinding
completion system and put it on the manual. People should discover it
from Emacs Manual, as they discover other things such as customizing the
UI. Making such features immediately visible to the user is a complex
problem to solve, which can't be solved right away. But a feature like
this _can_ be implemented and should be alongside the discussion on
discoverability and what 'defaults' Emacs should be shipped with.

Regards,

Divya

RE: [External] : Re: discoverability, better defaults and which-key in Emacs

[Drew Adams]

> > Not to distract, but FYI library `keysee.el' is
> > an alternative to which-key.  Less known, some
> > differences, maybe worth checking out.
> 
> The dependency on `sortie.el` is actually cumbersome,

Sortie is completely general - independent
of keysee (which depends on it).  Sortie
can be used to interactively sort candidates
for any kind of completion.

I think this sorting is important enough for
KeySee that it should require Sortie, not
make its use optional.

Of course, if Emacs already had Sortie or an
equivalent then no explicit requiring would
be needed by KeySee. ;-)

> `keysee.el` implements a totally non-intrusive
> mini-buffer completion for keybinding suggestions.
> 
> I remember using `which-key` and implementing
> golden-ratio to my windows, things messed up
> because `which-key` suggestions are in a
> proper window, thus potentially intrusive.
> One can fix this, as a lot of people do but if
> this is to be integrated into core Emacs one
> needs to take care of that.

That's indeed another difference.  I'm
likely less aware of all the differences
because I don't use which-key. ;-)

(I don't use KeySee either, in fact.  I
use Icicles.  KeySee is actually a
reduced-functionality version of Icicles
key completion.)

The main difference from which-key is
no doubt that KeySee completes against
key _names_ (and their command names, as
I mentioned), and not keystrokes
themselves.

This means that you type text to complete
key names, instead of hitting those keys
themselves.

[As a shortcut, `M-q <keystroke>' inserts
the name of <keystroke>, so you can get
almost the same effect as which-key, when
you want that.  It would be possible/easy
to even obviate needing to hit `RET', but
I haven't added that option (except in
Icicles).]

KeySee is thus a bit less just-hit-keys
and a bit more of a discover-and-explore
feature.

In particular, this means you can, any
time, fully explore the entire domain of
keys available at that time (current
context).

You can always, for example, _backtrack_,
that is, go back up from wherever you are,
down inside a sequence of prefix keys.
E.g., after getting down into `C-x 4' you
can go back up to completing just `C-x'.

And then you can go back down again, or
down another prefix key's branch (e.g.
`C-x 8'), etc.

You go up by using the always-available
(except at top level) special completion
`..', that is, you type `..' to go back
up from completing a prefix key.

The domain of "keys" available includes
the forest of menu-bar menus.  So you can
use KeySee to explore those as well.  And
a separate command, `kc-complete-menu-bar'
does _only_ that: complete menu-bar menus.

> Honestly, I believe if we can just add it
> as a part of the customizable UI then it'd
> be great. Just like we have `ido-completion`,
> or the ability to have menu items on the GUI,
> we can add a keybinding completion system
> and put it on the manual. People should
> discover it from Emacs Manual, as they
> discover other things such as customizing
> the UI. Making such features immediately
> visible to the user is a complex problem to
> solve, which can't be solved right away.
> But a feature like this _can_ be implemented
> and should be alongside the discussion on
> discoverability and what 'defaults' Emacs
> should be shipped with.

The use of KeySee features is, and should be,
optional.  You turn them on/off using minor
modes.

As for inclusion of KeySee & Sortie in Emacs,
I should say that I don't particularly want
to develop/maintain them in/for Emacs.  If
someone wants to do that, they can do so.
They're tiny libraries.

Re: discoverability, better defaults and which-key in Emacs

[Howard Melman]

Eli Zaretskii <eliz@gnu.org> writes:

> But maybe we could look at the result of
>
>   (get 'narrow-to-region 'disabled)
>
> to deduce that if that is nil, we are dealing with a user who is not
> new, even if the key-bindings popup is not disabled.  If which-key is
> also turned off in "emacs -Q", perhaps that would be good enough?

I don't have a strong opinion but that sounds
viable. Linking it to narrow-to-region seem unrelated,
though I see the point.

> And I still think that automatically popping up the *Help* buffer
> produced by describe-prefix-bindings is simpler and more coherent with
> the rest of Emacs than what which-key does.  We could still import
> which-key as an optional feature, of course, even if the automatic
> popup of describe-prefix-bindings is implemented.

Again, I don't have a strong opinion.  Automatically popping
up a display of bindings is useful.  Bonus points for being
able to customize the sorting (e.g., by key or command) globally,
per prefix or on-the-fly.  which-key also leverages some
"Custom String Replacement Options" that make the display
more useful.

-- 

Howard