Include which-key.el in the Emacs distribution

Include which-key.el in the Emacs distribution

[Stefan Kangas]

Dear all,

`which-key' is a package that unobtrusively shows you the available
keybindings at the bottom of the screen upon typing a prefix command
(after a configurable delay).  It is an excellent alternative and
complement to the default help.  See the screenshot here:

    https://raw.githubusercontent.com/justbur/emacs-which-key/master/img/which-key-bottom.png

`which-key' is in GNU ELPA, and was upgraded yesterday:

    https://elpa.gnu.org/packages/which-key.html

I propose to include `which-key' in the default Emacs distribution.
I expect that it will be extremely useful for beginning users, but it also
helps advanced users to quickly look up and discover keybindings.  In my
experience, that is true even in modes you already know deeply.

I've proposed this before, and have not seen any objections so far.
So I'd like to ask here again, to see if people have any concerns or
pointers for how to go about it in practice.

Any comments?

Best regards,
Stefan Kangas

PS. I personally think it should be enabled by default, but we would
    probably do better to first include it as an option for people to
    get more experience with it.

Re: Include which-key.el in the Emacs distribution

[Ergus]

I can't support this more effusively!!

+10 from my side.

What I don't understand is why the version in elpa is very old (and says
obsolete) compared to the one in melpa.


On Tue, Sep 08, 2020 at 01:54:45PM +0000, Stefan Kangas wrote:
>Dear all,
>
>`which-key' is a package that unobtrusively shows you the available
>keybindings at the bottom of the screen upon typing a prefix command
>(after a configurable delay).  It is an excellent alternative and
>complement to the default help.  See the screenshot here:
>
>    https://raw.githubusercontent.com/justbur/emacs-which-key/master/img/which-key-bottom.png
>
>`which-key' is in GNU ELPA, and was upgraded yesterday:
>
>    https://elpa.gnu.org/packages/which-key.html
>
>I propose to include `which-key' in the default Emacs distribution.
>I expect that it will be extremely useful for beginning users, but it also
>helps advanced users to quickly look up and discover keybindings.  In my
>experience, that is true even in modes you already know deeply.
>
>I've proposed this before, and have not seen any objections so far.
>So I'd like to ask here again, to see if people have any concerns or
>pointers for how to go about it in practice.
>
>Any comments?
>
>Best regards,
>Stefan Kangas
>
>PS. I personally think it should be enabled by default, but we would
>    probably do better to first include it as an option for people to
>    get more experience with it.
>

Re: Include which-key.el in the Emacs distribution

[Stefan Kangas]

Ergus <spacibba@aol.com> writes:

> What I don't understand is why the version in elpa is very old (and says
> obsolete) compared to the one in melpa.

This is because MELPA-stable uses the git tag (that says version 3.4.0),
while GNU ELPA uses the "Version" header in the .el file (that says
3.3.2).

Re: Include which-key.el in the Emacs distribution

[Yuan Fu]

> On Sep 8, 2020, at 10:01 AM, Ergus <spacibba@aol.com> wrote:
> 
> I can't support this more effusively!!
> 
> +10 from my side.


 +1 from me. Which-key could be helpful.

Yuan

Re: Include which-key.el in the Emacs distribution

[Justin Burkett]

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

Hi Everyone,

I'm the author of which-key. For what it's worth, I have no doubt that the
package could be improved. I do have one idea off the top of my head for
how it could be more tightly integrated with emacs.

As far as the amount of output is concerned, it is possible to filter out
keys and customize the output to some degree. You can also limit the size
of the window and control sorting. Of course, emacs does actually have that
many bindings, and that may not be apparent to people unless they are
written out. The original idea was that there would be a significant delay,
so that you wouldn't see the window until you were "stuck".

In any event, I don't have a strong opinion on whether this should happen,
but I have time here and there to help.

Justin

On Tue, Sep 8, 2020 at 1:29 PM Yuan Fu <casouri@gmail.com> wrote:

>
>
> > On Sep 8, 2020, at 10:01 AM, Ergus <spacibba@aol.com> wrote:
> >
> > I can't support this more effusively!!
> >
> > +10 from my side.
>
>
>  +1 from me. Which-key could be helpful.
>
> Yuan
>

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

Re: Include which-key.el in the Emacs distribution

[Stefan Kangas]

Justin Burkett <justin@burkett.cc> writes:

> In any event, I don't have a strong opinion on whether this should happen,
> but I have time here and there to help.

Thank you, that is encouraging news.  Your help will be much
appreciated.

The suggestion to make this the default seems to have gotten some
attention, but was perhaps a bit premature.  In any case, I do think
adding this package to the Emacs distribution would already be very
useful in itself.

BTW, I would propose to update the Version header to match (or be higher
than) the latest git tag 3.4.0.  Then we could update ELPA with that new
release.

I take it that the copyright assignments from contributors are all in
order?

Best regards,
Stefan Kangas

Re: Include which-key.el in the Emacs distribution

[Alfred M. Szmidt]

   PS. I personally think it should be enabled by default, but we would
       probably do better to first include it as an option for people to
       get more experience with it.

Could the output be improved though?  The current output is VERY
verbose, and quite bare and unexplanatory.  On my terminal it takes up
9 lines when just hitting C-x.  It also dislikes any type of prefix
command and hides the output from those.  E.g, C-h, M-o etc, where it
eats the message from the original command.

Instead why not if you press C-x in the echo area a short list of
commands could be produced that you can scroll through, similar to
which-key but not as talkative.  It could say,

  C-x 		(f - edit file, o - other window, ...)

The prefix commands C-x 4, C-x r etc could also produces such
messages.  Like Emacs does for M-o.  This list could be curated.

Maybe that would be a nice middle ground, not to talkative, helps the
new user and won't annoy the old farts too much?

Re: Include which-key.el in the Emacs distribution

[Eli Zaretskii]

> From: ams@gnu.org (Alfred M. Szmidt)
> Date: Tue, 08 Sep 2020 12:22:30 -0400
> Cc: justin@burkett.cc, emacs-devel@gnu.org
> 
>    PS. I personally think it should be enabled by default, but we would
>        probably do better to first include it as an option for people to
>        get more experience with it.
> 
> Could the output be improved though?  The current output is VERY
> verbose, and quite bare and unexplanatory.  On my terminal it takes up
> 9 lines when just hitting C-x.  It also dislikes any type of prefix
> command and hides the output from those.  E.g, C-h, M-o etc, where it
> eats the message from the original command.

Btw, did you figure out how to scroll to the next page?  In
particular, after typing "C-h" that shows the first page of Help
commands?

Re: Include which-key.el in the Emacs distribution

[Amin Bandali]

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

Eli Zaretskii writes:

>> From: ams@gnu.org (Alfred M. Szmidt)
>> Date: Tue, 08 Sep 2020 12:22:30 -0400
>> Cc: justin@burkett.cc, emacs-devel@gnu.org
>> 
>>    PS. I personally think it should be enabled by default, but we would
>>        probably do better to first include it as an option for people to
>>        get more experience with it.
>> 
>> Could the output be improved though?  The current output is VERY
>> verbose, and quite bare and unexplanatory.  On my terminal it takes up
>> 9 lines when just hitting C-x.  It also dislikes any type of prefix
>> command and hides the output from those.  E.g, C-h, M-o etc, where it
>> eats the message from the original command.
>

The height can be adjusted using `which-key-side-window-max-height' or
`which-key-frame-max-height', depending on which `which-key-popup-type'
you use.

>
> Btw, did you figure out how to scroll to the next page?  In
> particular, after typing "C-h" that shows the first page of Help
> commands?

Pagination is done by hitting C-h C-n and C-h C-p, or C-h n and C-h p
when the which-key popup is active.

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

Re: Include which-key.el in the Emacs distribution

[Alfred M. Szmidt]

   > Btw, did you figure out how to scroll to the next page?  In
   > particular, after typing "C-h" that shows the first page of Help
   > commands?

   Pagination is done by hitting C-h C-n and C-h C-p, or C-h n and C-h p
   when the which-key popup is active.

That was Eli's point -- it doesn't work with C-h -- please try it.

  C-h
  ;; Shows first "C-h (Type ? for further options)-", then after a secondthe
  ;; which-key pop-up occurs.
  C-h
  ;; Now the C-h help help buffer will be shown.
  C-n
  ;; Now you're viewing the NEWS file.

I.e., you cannot paginate through the commands if you are issuing C-h
and have which-key-mode on.
  
  

Re: Include which-key.el in the Emacs distribution

[Justin Burkett]

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

>
> That was Eli's point -- it doesn't work with C-h -- please try it.
>
>   C-h
>   ;; Shows first "C-h (Type ? for further options)-", then after a
> secondthe
>   ;; which-key pop-up occurs.
>   C-h
>   ;; Now the C-h help help buffer will be shown.
>   C-n
>   ;; Now you're viewing the NEWS file.
>
> I.e., you cannot paginate through the commands if you are issuing C-h
> and have which-key-mode on.


You also can't invoke describe-prefix-bindings from C-h in vanilla emacs.
The reason is the same. which-key is just intercepting the help-char to do
the pagination.

On Tue, Sep 8, 2020 at 1:51 PM Alfred M. Szmidt <ams@gnu.org> wrote:

>    > Btw, did you figure out how to scroll to the next page?  In
>    > particular, after typing "C-h" that shows the first page of Help
>    > commands?
>
>    Pagination is done by hitting C-h C-n and C-h C-p, or C-h n and C-h p
>    when the which-key popup is active.
>
> That was Eli's point -- it doesn't work with C-h -- please try it.
>
>   C-h
>   ;; Shows first "C-h (Type ? for further options)-", then after a
> secondthe
>   ;; which-key pop-up occurs.
>   C-h
>   ;; Now the C-h help help buffer will be shown.
>   C-n
>   ;; Now you're viewing the NEWS file.
>
> I.e., you cannot paginate through the commands if you are issuing C-h
> and have which-key-mode on.
>
>
>

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

Re: Include which-key.el in the Emacs distribution

[Eli Zaretskii]

> From: Justin Burkett <justin@burkett.cc>
> Date: Tue, 8 Sep 2020 13:54:08 -0400
> Cc: Amin Bandali <bandali@gnu.org>, Eli Zaretskii <eliz@gnu.org>, Stefan Kangas <stefan@marxist.se>, 
> 	emacs-devel <emacs-devel@gnu.org>
> 
>  I.e., you cannot paginate through the commands if you are issuing C-h
>  and have which-key-mode on.
> 
> You also can't invoke describe-prefix-bindings from C-h in vanilla
> emacs.

I don't see the relevance, sorry.  When I type "C-h" with
which-key-mode on, I see a paging hint at the bottom line, and that
hint simply doesn't work (and nothing else I tried does).  By
contrast, the vanilla "C-h" doesn't say anything about
describe-prefix-bindings, so the problem will rarely if ever happen.

IMO, this UI needs to be improved, certainly if we want to turn this
mode on by default.  For starters, how about using the usual Emacs
scrolling keys for showing the next/previous page?

Re: Include which-key.el in the Emacs distribution

[Justin Burkett]

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

> I don't see the relevance, sorry.  When I type "C-h" with
> which-key-mode on, I see a paging hint at the bottom line, and that
> hint simply doesn't work (and nothing else I tried does).  By
> contrast, the vanilla "C-h" doesn't say anything about
> describe-prefix-bindings, so the problem will rarely if ever happen.
>

Ah, if it's just about the hint, then yes, that should be hidden in that
case.

IMO, this UI needs to be improved, certainly if we want to turn this
> mode on by default.  For starters, how about using the usual Emacs
> scrolling keys for showing the next/previous page?
>

I wasn't advocating for it to be on by default, but yes, the UI could
probably be improved. It's a difficult problem (at least for me), because I
wanted which-key to be passive and not interfere with how emacs processes
key sequences. That's why I used the help-char escape mechanism to do the
paging. As far as the default keys, that's an easy change of course.

On Tue, Sep 8, 2020 at 2:06 PM Eli Zaretskii <eliz@gnu.org> wrote:

> > From: Justin Burkett <justin@burkett.cc>
> > Date: Tue, 8 Sep 2020 13:54:08 -0400
> > Cc: Amin Bandali <bandali@gnu.org>, Eli Zaretskii <eliz@gnu.org>,
> Stefan Kangas <stefan@marxist.se>,
> >       emacs-devel <emacs-devel@gnu.org>
> >
> >  I.e., you cannot paginate through the commands if you are issuing C-h
> >  and have which-key-mode on.
> >
> > You also can't invoke describe-prefix-bindings from C-h in vanilla
> > emacs.
>
> I don't see the relevance, sorry.  When I type "C-h" with
> which-key-mode on, I see a paging hint at the bottom line, and that
> hint simply doesn't work (and nothing else I tried does).  By
> contrast, the vanilla "C-h" doesn't say anything about
> describe-prefix-bindings, so the problem will rarely if ever happen.
>
> IMO, this UI needs to be improved, certainly if we want to turn this
> mode on by default.  For starters, how about using the usual Emacs
> scrolling keys for showing the next/previous page?
>

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

Re: Include which-key.el in the Emacs distribution

[Stefan Kangas]

Justin Burkett <justin@burkett.cc> writes:

>> When I type "C-h" with which-key-mode on, I see a paging hint at the
>> bottom line, and that hint simply doesn't work (and nothing else I
>> tried does).
>
> Ah, if it's just about the hint, then yes, that should be hidden in that
> case.

Thanks, I see that you already did that:

https://github.com/justbur/emacs-which-key/commit/a70fc16adcf604f2cb8061d77813354da018c541

> I wasn't advocating for it to be on by default, but yes, the UI could
> probably be improved. It's a difficult problem (at least for me), because I
> wanted which-key to be passive and not interfere with how emacs processes
> key sequences. That's why I used the help-char escape mechanism to do the
> paging. As far as the default keys, that's an easy change of course.

Does it make sense to support all three of n/p, C-n/C-p and C-v/M-v?
While updating the minibuffer help text to promote the more standard key
bindings C-v/M-v?

Re: Include which-key.el in the Emacs distribution

[Alfred M. Szmidt]

    That was Eli's point -- it doesn't work with C-h -- please try it.

      C-h
      ;; Shows first "C-h (Type ? for further options)-", then after a secondthe
      ;; which-key pop-up occurs.
      C-h
      ;; Now the C-h help help buffer will be shown.
      C-n
      ;; Now you're viewing the NEWS file.

    I.e., you cannot paginate through the commands if you are issuing C-h
    and have which-key-mode on.

   You also can't invoke describe-prefix-bindings from C-h in vanilla
   emacs. The reason is the same. which-key is just intercepting the
   help-char to do the pagination.

As a user the background reasons for why something is not possible are
not interesting.  which-key tells me to use C-h to visit the next
page; that does not work if you've just hit C-h once already -- it
invokes help-for-help (C-h C-h), which is not what the user is being
told to expect.

Re: Include which-key.el in the Emacs distribution

[Eli Zaretskii]

> From: Amin Bandali <bandali@gnu.org>
> Cc: ams@gnu.org (Alfred M. Szmidt),  stefan@marxist.se,  justin@burkett.cc,
>   emacs-devel@gnu.org
> Date: Tue, 08 Sep 2020 13:37:27 -0400
> 
> > Btw, did you figure out how to scroll to the next page?  In
> > particular, after typing "C-h" that shows the first page of Help
> > commands?
> 
> Pagination is done by hitting C-h C-n and C-h C-p, or C-h n and C-h p
> when the which-key popup is active.

Did you actually try that after typing C-h?

And even after other prefix keys, like C-x, these paging commands are
highly unintuitive, certainly for an Emacs user, and are not easily
discoverable (are they documented in the README or in some other
place?).

This package "needs work", IMHO.

Re: Include which-key.el in the Emacs distribution

[Amin Bandali]

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

Eli Zaretskii writes:

>> From: Amin Bandali <bandali@gnu.org>
>> Cc: ams@gnu.org (Alfred M. Szmidt),  stefan@marxist.se,  justin@burkett.cc,
>>   emacs-devel@gnu.org
>> Date: Tue, 08 Sep 2020 13:37:27 -0400
>> 
>> > Btw, did you figure out how to scroll to the next page?  In
>> > particular, after typing "C-h" that shows the first page of Help
>> > commands?
>> 
>> Pagination is done by hitting C-h C-n and C-h C-p, or C-h n and C-h p
>> when the which-key popup is active.
>
> Did you actually try that after typing C-h?
>

Oh, my bad; I think I misread/misunderstood your question.  I had indeed
not tried with C-h, but with other prefixes like C-x and C-c.  With
those prefixes, C-h C-n et al. work fine, but it seems that for C-h it
does not.  Sorry for the misunderstanding.

>
> And even after other prefix keys, like C-x, these paging commands are
> highly unintuitive, certainly for an Emacs user, and are not easily
> discoverable (are they documented in the README or in some other
> place?).
>
> This package "needs work", IMHO.
>

I agree, the user interface could be better.  I'm just generally happy
to see which-key discussed on emacs-devel for inclusion in GNU Emacs
itself and possibly being enabled out of the box (perhaps as part of one
of the new layers/modules/themes idea of Stefan and others).

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

Re: Include which-key.el in the Emacs distribution

[Caio Henrique]

Personally I find it a bit intrusive, so I use it very rarely (maybe once
every one or two months) and I manually load it in those rare occasions
when I want to use it. 
If it were enabled by default, I wouldn't mind having to add a line in
my config to disable it.

Caio Henrique

Re: Include which-key.el in the Emacs distribution

[Stefan Monnier]

> I propose to include `which-key' in the default Emacs distribution.

I think it would be most useful to enable it by default.
But for that it needs to be polished enough that it's still bearable for
those users who don't like it (e.g. the guy with his 1MB .emacs file
that has to use a `emacs -Q` when testing something, or when using
Emacs on someone else's computer/account).


        Stefan

Re: Include which-key.el in the Emacs distribution

[Ergus]

Now I am the one becoming conservative here.

I really love which-key but enabling it by default for everyone could be
a bit premature. Maybe adding a very easy to find option in the toolbar
could be a better first step?

So the ones (like me) who love it can improve it until it becomes ready
to be default without the complains if the other who doesn't.



On Tue, Sep 08, 2020 at 03:19:45PM -0400, Stefan Monnier wrote:
>> I propose to include `which-key' in the default Emacs distribution.
>
>I think it would be most useful to enable it by default.
>But for that it needs to be polished enough that it's still bearable for
>those users who don't like it (e.g. the guy with his 1MB .emacs file
>that has to use a `emacs -Q` when testing something, or when using
>Emacs on someone else's computer/account).
>
>
>        Stefan
>
>

Re: Include which-key.el in the Emacs distribution

[Stefan Kangas]

Ergus <spacibba@aol.com> writes:

> I really love which-key but enabling it by default for everyone could be
> a bit premature. Maybe adding a very easy to find option in the toolbar
> could be a better first step?
>
> So the ones (like me) who love it can improve it until it becomes ready
> to be default without the complains if the other who doesn't.

Yes, we should definitely make any necessary improvements before
considering to make it the default.  I believe that's what Stefan M was
also arguing, so I see no disagreement on that point.

Re: Include which-key.el in the Emacs distribution

[Corwin Brust]

On Tue, Sep 8, 2020 at 3:41 PM Stefan Kangas <stefan@marxist.se> wrote:
>
> Ergus <spacibba@aol.com> writes:
>
> > I really love which-key but enabling it by default for everyone could be
> > a bit premature. Maybe adding a very easy to find option in the toolbar
> > could be a better first step?
> >
> > So the ones (like me) who love it can improve it until it becomes ready
> > to be default without the complains if the other who doesn't.
>
> Yes, we should definitely make any necessary improvements before
> considering to make it the default.  I believe that's what Stefan M was
> also arguing, so I see no disagreement on that point.
>

Hi all.  Having `which-key' available in core remains popular, at least on IRC.

Now that it is available from GNU Elpa I wonder what is left to do and
if there appears hope of including it with Emacs 29.

Does anyone "here" have thoughts on how this may be coming along/what
else is needed?

Re: Include which-key.el in the Emacs distribution

[Philip Kaludercic]

Corwin Brust <corwin@bru.st> writes:

> On Tue, Sep 8, 2020 at 3:41 PM Stefan Kangas <stefan@marxist.se> wrote:
>>
>> Ergus <spacibba@aol.com> writes:
>>
>> > I really love which-key but enabling it by default for everyone could be
>> > a bit premature. Maybe adding a very easy to find option in the toolbar
>> > could be a better first step?
>> >
>> > So the ones (like me) who love it can improve it until it becomes ready
>> > to be default without the complains if the other who doesn't.
>>
>> Yes, we should definitely make any necessary improvements before
>> considering to make it the default.  I believe that's what Stefan M was
>> also arguing, so I see no disagreement on that point.
>>
>
> Hi all.  Having `which-key' available in core remains popular, at least on IRC.
>
> Now that it is available from GNU Elpa I wonder what is left to do and
> if there appears hope of including it with Emacs 29.

My first question is why it should be added to the core, given that it
can be installed with a single command OOTB?  My impression from using
(and seeing other people use) which-key would have me say that the UX it
provides goes contrary to the "style" that core functionality uses
traditionally (what other cases are there where not doing something
modifies the window configuration, the closes commonly used
functionality would be eldoc that displays information in the
minibuffer).

What I would be more interested in is to add optional support for C-h to
continue a command prefix, so that if I want to know what keys a keymap
provides, I can request it immediately without waiting for the idle
timer to trigger a often too small popup window, without loosing the
partial input.

-- 
	Philip Kaludercic

Re: Include which-key.el in the Emacs distribution

[Pankaj Jangid]

Philip Kaludercic <philipk@posteo.net> writes:

> What I would be more interested in is to add optional support for C-h to
> continue a command prefix, so that if I want to know what keys a keymap
> provides, I can request it immediately without waiting for the idle
> timer to trigger a often too small popup window, without loosing the
> partial input.

I’ve enabled default settings of which-key. And that is good enough, at
least for me, so that it pops up on those rare occasions when my muscle
memory is not able to recall something.

But "Manual Activation" feature is available in "which-key". Following
section of README file explains it briefly:

#+begin_src emacs-lisp
;; 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)

;; This will prevent which-key from showing automatically, and allow
;; you to use C-h in the middle of a key sequence to show the which-key
;; buffer and keep it open for the remainder of the key sequence.
#+end_src

RE: [External] : Re: Include which-key.el in the Emacs distribution

[Drew Adams]

> What I would be more interested in is to add optional
> support for C-h to continue a command prefix, so that
> if I want to know what keys a keymap provides, I can
> request it immediately without waiting for the idle
> timer to trigger a often too small popup window,
> without loosing the partial input.

I know that you know that `C-h' after a prefix
key shows you the possible continuations.  I
think your request is to not "lose" what you've
typed so far.

Library `keysee.el' can help with this.  It can
either show you possible continuations after a
delay, automatically, or show you them only on
demand, when you hit key `S-TAB' (by default).

You can also use `S-TAB' at top level, to see
all possible keys available in the current
context.

You can also complete menu-bar menus.

Completion candidates are pairs: key name,
followed by a (configurable) separator,
followed by the associated command name.

Completion is normal, so you can use keys to
edit minibuffer content.  This is a difference
from `which-key', where the keys you type just
continue the prefix key directly.  With Key See,
keys you type act normally in the minibuffer.

This means you can match against the key name
or the command name, or against both.

If you do want to have a key you type continue
the key sequence instead of editing minibuffer
content, precede it with `M-q'.  That inserts
its name, for completion.

You can also sort the completion candidates in
these ways (by default - you can add sorts):

 * By key name alphabetically, prefix keys first
 * By key name alphabetically, local keys first
 * By command name alphabetically

Sorting applies to both display and cycling (per
option `completion-cycle-threshold ').  You can
change the current sort order on the fly anytime,
using `C-,' (by default).  A prefix arg (e.g.
`C-u C-,') reverses the current sort order.

The completion styles used are those defined by
option `kc-completion-styles', so they can be
different from what you prefer for general use
(option `completion-styles').

Key See essentially extracts some of what
Icicles key completion provides, as a separate
library.  `keysee.el' requires `sortie.el',
which is what provides for completion sorting. 

If you complete to another prefix key (e.g.
you complete `C-x' to `C-x 4'), the candidates
are changed to those of that key (e.g. `C-x 4').

Whenever you are not at top level (candidates
are those of a prefix key), `..' is available
as a special candidate.  It takes you up a
level, essentially undoing the use of a prefix
key.

This means you can use Key See to navigate up
and down the complete current key hierarchy -
all possible keys (including menu-bar menus).

The on-demand completion behavior is provided
by minor mode `kc-mode'.  The automatic,
timer-based completion is provided by minor
mode `kc-auto-mode'.  It includes on-demand
behavior, so you can still use `S-TAB' at top
level.  To complete only menu-bar menus, you
can use command `kc-complete-menu-bar'.
___

Key See description:

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

Key See code:

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

Sortie description:

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

Sortie code:

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

Re: Include which-key.el in the Emacs distribution

[Tim Cross]

Philip Kaludercic <philipk@posteo.net> writes:

> Corwin Brust <corwin@bru.st> writes:
>
>> On Tue, Sep 8, 2020 at 3:41 PM Stefan Kangas <stefan@marxist.se> wrote:
>>>
>>> Ergus <spacibba@aol.com> writes:
>>>
>>> > I really love which-key but enabling it by default for everyone could be
>>> > a bit premature. Maybe adding a very easy to find option in the toolbar
>>> > could be a better first step?
>>> >
>>> > So the ones (like me) who love it can improve it until it becomes ready
>>> > to be default without the complains if the other who doesn't.
>>>
>>> Yes, we should definitely make any necessary improvements before
>>> considering to make it the default.  I believe that's what Stefan M was
>>> also arguing, so I see no disagreement on that point.
>>>
>>
>> Hi all.  Having `which-key' available in core remains popular, at least on IRC.
>>
>> Now that it is available from GNU Elpa I wonder what is left to do and
>> if there appears hope of including it with Emacs 29.
>
> My first question is why it should be added to the core, given that it
> can be installed with a single command OOTB?  My impression from using
> (and seeing other people use) which-key would have me say that the UX it
> provides goes contrary to the "style" that core functionality uses
> traditionally (what other cases are there where not doing something
> modifies the window configuration, the closes commonly used
> functionality would be eldoc that displays information in the
> minibuffer).
>
> What I would be more interested in is to add optional support for C-h to
> continue a command prefix, so that if I want to know what keys a keymap
> provides, I can request it immediately without waiting for the idle
> timer to trigger a often too small popup window, without loosing the
> partial input.

Sounds like you would find Embark better than which-key.

While Embark takes more effort to configure, it gives you very similar
functionality as which-key, but provides a lot more and can provide
powerful integration/enhancements for completion frameworks like vertico
or selectrum. 

Re: Include which-key.el in the Emacs distribution

[Stephen Leake]

Corwin Brust <corwin@bru.st> writes:

> On Tue, Sep 8, 2020 at 3:41 PM Stefan Kangas <stefan@marxist.se> wrote:
>>
>> Ergus <spacibba@aol.com> writes:
>>
>> > I really love which-key but enabling it by default for everyone could be
>> > a bit premature. Maybe adding a very easy to find option in the toolbar
>> > could be a better first step?
>> >
>> > So the ones (like me) who love it can improve it until it becomes ready
>> > to be default without the complains if the other who doesn't.
>>
>> Yes, we should definitely make any necessary improvements before
>> considering to make it the default.  I believe that's what Stefan M was
>> also arguing, so I see no disagreement on that point.
>>
>
> Hi all.  Having `which-key' available in core remains popular, at least on IRC.
>
> Now that it is available from GNU Elpa I wonder what is left to do and
> if there appears hope of including it with Emacs 29.
>
> Does anyone "here" have thoughts on how this may be coming along/what
> else is needed?

I started on a branch to implement bundling elpa packages in the emacs
release; see feature/bundle-elpa, file admin/notes/elpa, and this email
thread on emacs-devel:
https://lists.gnu.org/archive/html/emacs-devel/2021-01/msg01017.html

I gave up when no one responded to my requests for comments.

There is also a branch feature/core-elpa-by-copy.

-- 
-- Stephe

Re: Include which-key.el in the Emacs distribution

[Corwin Brust]

On Sun, Feb 13, 2022 at 11:59 AM Stephen Leake
<stephen_leake@stephe-leake.org> wrote:
>
> Corwin Brust <corwin@bru.st> writes:
>
> > On Tue, Sep 8, 2020 at 3:41 PM Stefan Kangas <stefan@marxist.se> wrote:
> >>
> >> Ergus <spacibba@aol.com> writes:
> >>
> >> > I really love which-key but enabling it by default for everyone could be
> >> > a bit premature. Maybe adding a very easy to find option in the toolbar
> >> > could be a better first step?
> >> >
> >> > So the ones (like me) who love it can improve it until it becomes ready
> >> > to be default without the complains if the other who doesn't.
> >>
> >> Yes, we should definitely make any necessary improvements before
> >> considering to make it the default.  I believe that's what Stefan M was
> >> also arguing, so I see no disagreement on that point.
> >>
> >
> > Hi all.  Having `which-key' available in core remains popular, at least on IRC.
> >
> > Now that it is available from GNU Elpa I wonder what is left to do and
> > if there appears hope of including it with Emacs 29.
> >
> > Does anyone "here" have thoughts on how this may be coming along/what
> > else is needed?
>
> I started on a branch to implement bundling elpa packages in the emacs
> release; see feature/bundle-elpa, file admin/notes/elpa, and this email
> thread on emacs-devel:
> https://lists.gnu.org/archive/html/emacs-devel/2021-01/msg01017.html

Does solving this block the possibility to include which-key, in your view?

I know, at least, ERC is maintained via GNU ELPA but bundled in each
Emacs release.  Would it make sense to look into how that's being
done, perhaps as an interim step?

>
> I gave up when no one responded to my requests for comments.
>
> There is also a branch feature/core-elpa-by-copy.

I'll take a look at these branches and read the thread you mentioned.
I'm not very familiar with the "plumbing" for the ELPAs but perhaps I
can gean so understand from what you've done already.

Thanks for the reply.
>
> --
> -- Stephe



-- 
Corwin
612-217-1742
612-695-4276 (signal)
corwin@bru.st

Re: Include which-key.el in the Emacs distribution

[Stephen Leake]

Corwin Brust <corwin@bru.st> writes:

> On Sun, Feb 13, 2022 at 11:59 AM Stephen Leake
> <stephen_leake@stephe-leake.org> wrote:
>>
>> Corwin Brust <corwin@bru.st> writes:
>>
>> > Hi all.  Having `which-key' available in core remains popular, at least on IRC.
>> >
>> > Now that it is available from GNU Elpa I wonder what is left to do and
>> > if there appears hope of including it with Emacs 29.
>> >
>> > Does anyone "here" have thoughts on how this may be coming along/what
>> > else is needed?
>>
>> I started on a branch to implement bundling elpa packages in the emacs
>> release; see feature/bundle-elpa, file admin/notes/elpa, and this email
>> thread on emacs-devel:
>> https://lists.gnu.org/archive/html/emacs-devel/2021-01/msg01017.html
>
> Does solving this block the possibility to include which-key, in your
> view?

The goal is to have a mechanism to easily include any ELPA package with
the Emacs release. The above is one approach to that.

> I know, at least, ERC is maintained via GNU ELPA but bundled in each
> Emacs release.  Would it make sense to look into how that's being
> done, perhaps as an interim step?

That's easy; there is a lisp/erc directory in the master emacs git
repository. Apparently someone syncs the code between there and ELPA.
There are several other packages that use that approach; which-key could
as well.

There are also "core" ELPA packages; the code resides in the emacs
master repository, but the ELPA server also packages it. I think the
only examples of those are single-file, but it should work for
multi-file as well.

-- 
-- Stephe

Re: Include which-key.el in the Emacs distribution

[Stefan Monnier]

> That's easy; there is a lisp/erc directory in the master emacs git
> repository. Apparently someone syncs the code between there and ELPA.

Not really: the GNU ELPA packages are generated from code kept in the
`elpa.git` repository, but it can also use the code in Emacs itself
(i.e. in the `master` branch of the `emacs.git` repository), which is
what happens for ERC, Python, and a few more, whose "upstream" is
Emacs's own repository.

> There are also "core" ELPA packages; the code resides in the emacs
> master repository, but the ELPA server also packages it. I think the
> only examples of those are single-file, but it should work for
> multi-file as well.

It's not limited to single-file packages.
The ERC package is one of those.


        Stefan

Re: Include which-key.el in the Emacs distribution

[Justin Burkett]

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

I don't have anything to say about the process of moving it into the core,
but it's fine with me if you all decide to do that. I don't have much time
these days to contribute, however.

Justin

On Sun, Feb 13, 2022 at 9:47 PM Stefan Monnier <monnier@iro.umontreal.ca>
wrote:

> > That's easy; there is a lisp/erc directory in the master emacs git
> > repository. Apparently someone syncs the code between there and ELPA.
>
> Not really: the GNU ELPA packages are generated from code kept in the
> `elpa.git` repository, but it can also use the code in Emacs itself
> (i.e. in the `master` branch of the `emacs.git` repository), which is
> what happens for ERC, Python, and a few more, whose "upstream" is
> Emacs's own repository.
>
> > There are also "core" ELPA packages; the code resides in the emacs
> > master repository, but the ELPA server also packages it. I think the
> > only examples of those are single-file, but it should work for
> > multi-file as well.
>
> It's not limited to single-file packages.
> The ERC package is one of those.
>
>
>         Stefan
>
>

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

Re: Include which-key.el in the Emacs distribution

[Corwin Brust]

I'd be happy to help if a "warm body" to "do stuff" is what's needed.

On Sun, Feb 13, 2022 at 9:09 PM Justin Burkett <justin@burkett.cc> wrote:
>
> I don't have anything to say about the process of moving it into the core, but it's fine with me if you all decide to do that. I don't have much time these days to contribute, however.
>
> Justin
>
> On Sun, Feb 13, 2022 at 9:47 PM Stefan Monnier <monnier@iro.umontreal.ca> wrote:
>>
>> > That's easy; there is a lisp/erc directory in the master emacs git
>> > repository. Apparently someone syncs the code between there and ELPA.
>>
>> Not really: the GNU ELPA packages are generated from code kept in the
>> `elpa.git` repository, but it can also use the code in Emacs itself
>> (i.e. in the `master` branch of the `emacs.git` repository), which is
>> what happens for ERC, Python, and a few more, whose "upstream" is
>> Emacs's own repository.
>>
>> > There are also "core" ELPA packages; the code resides in the emacs
>> > master repository, but the ELPA server also packages it. I think the
>> > only examples of those are single-file, but it should work for
>> > multi-file as well.
>>
>> It's not limited to single-file packages.
>> The ERC package is one of those.
>>
>>
>>         Stefan
>>

RE: Include which-key.el in the Emacs distribution

[Drew Adams]

>    PS. I personally think it should be enabled by default, but we would
>        probably do better to first include it as an option for people to
>        get more experience with it.
> 
> Could the output be improved though?  The current output is VERY
> verbose, and quite bare and unexplanatory.  On my terminal it takes up
> 9 lines when just hitting C-x.  It also dislikes any type of prefix
> command and hides the output from those.  E.g, C-h, M-o etc, where it
> eats the message from the original command.
> 
> Instead why not if you press C-x in the echo area a short list of
> commands could be produced that you can scroll through, similar to
> which-key but not as talkative.  It could say,
> 
>   C-x 		(f - edit file, o - other window, ...)
> 
> The prefix commands C-x 4, C-x r etc could also produces such
> messages.  Like Emacs does for M-o.  This list could be curated.
> 
> Maybe that would be a nice middle ground, not to talkative, helps the
> new user and won't annoy the old farts too much?

See also `keysee.el':

No problem with prefix keys/commands (C-h, M-o, etc.).
No problem showing available keys at top level.
No problem navigating back up the key hierarchy - up,
 down, all around.
No problem with menu-bar menus (up, down, all around).
You can match keys, commands, or both.
You can sort matches on the fly:
 * By key name alphabetically, prefix keys first
 * By key name alphabetically, local keys first
 * By command name alphabetically

It does, however, show all matches in *Completions*,
(as opposed to just a few matches in the echo area).

If you have a way of limiting the window height of
*Completions* then that would help reduce the visual
overload you complain about.

But maybe what you really want for that is something
that decides which are the most important keys to
show.  Sorting *Completions* according to such
"importance" (and showing it in a short window)
would help with that.  One easy way to automatically
define such "importance" could be to sort keys by
their recent frequency.

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

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


(FWIW: If you use Icicles then you have what
keysee.el offers plus much more, including control
over *Completions* display, sort orders etc.

https://www.emacswiki.org/emacs/Icicles_-_Key_Completion)

RE: Include which-key.el in the Emacs distribution

[Drew Adams]

> to scroll to the next page?  In particular, after typing
> "C-h" that shows the first page of Help commands?

FWIW, this is not a problem for keysee.el.  Scrolling
*Completions* is as usual (TAB), including after C-h.