Re: Delegating user-reserved key binding space definition to users

[Eli Zaretskii]

> From: Psionic K <psionik@positron.solutions>
> Date: Mon, 28 Nov 2022 23:22:24 -0600
> Cc: Ihor Radchenko <yantar92@posteo.net>,
>  Emacs developers <emacs-devel@gnu.org>
> 
> ;; The user will specify concept / abstract commands -> key sequences
> (setq-custom concept-sequences '((user-next ?\M-n) (user-prev ?\M-p)))
> ;; The package will specify concepts / abstract commands -> concrete commands
> ;; So, something like a magit section mode intended to be derived from, the 
> package author writes:
> (setq-local concept-commands '((user-next #'magit-section-next) (user-prev 
> #'magit-section-prev)))
> ;; And then the package tells the implementation to consume the declarations, 
> which might occur after the
> mode hook to let the user intervene
> (emacs-function-setup-concept-keymap)
> 
> `emacs-function-setup-concept-keymap' would be an implementation that ties 
> the user's declaration of
> sequence -> concept mappings together with the package's concept -> command 
> mappings.  The result is
> that the local map should contain some command remap shadows corresponding to 
> what the user and the
> package declared.
> 
> I neglected overloading in my example, but basically a user might be okay 
> with several concepts being able
> to map to one key and the package might be okay with mapping the same command 
> to one of several
> concepts.
> 
> IMO these declarations one-to-many declarations should only be used with two 
> specific conventions:  
> 
> 1 Package authors specify a list of increasingly more generic concepts, 
> ending with `user-generic' which
>  would just mean "any key that the user has bestowed upon packages by 
> default.".  An example of more
>  abstract definitions would be a declaration like (#'magit-section-next 
> (user-next user-navigation)).   The
>  implementation could try to map to user-next and if that's not available, 
> use an available sequence from
>  user-navigation.
> 2 The user's convention for one-to-many mappings is different.  They might 
> want to map a generic concept
>  onto several key sequences in order, so they might declare something like 
> '(user-navigation (?\M-p ?\M-n
>  ?\M-f ?\M-b)).  If a package declares a user-next, user-prev, and two more 
> user-navigation commands,
>  the implementation will give them all keymap elements.
> 
> > I get the impression that your
> > SOME-INFO includes info for several commands.
> 
> Yes.  The reason commands should not handle this declaration is because the 
> implementation would have
> to discover the commands, and this would be fragile if the user starts 
> replacing commands or wants to
> specify commands that the package has no idea about.
> 
> I'm also preoccupied with automating the user-driven re-mapping of commands 
> to key sequences when
> those commands express an extremely similar idea, such as "next".  I see this 
> as a prerequisite for what I
> think you want.  I don't think I agree with what I think you want, and this 
> could be messing with my
> interpretation, but it is a prerequisite still.
> 
> We have lots of convention, lots of similarity in mode keymaps, but we it's 
> ad-hoc, and we just need to make
> it official so that the conventions are useful and user's can change one 
> declaration to move, for example,
> C-g.

I think this discussion started from the wrong starting point, and that's
why the common understanding is difficult and misunderstandings abundant:
there's no reason to believe you and Stefan (and myself, and others who
read this) have the same goals and the same issues in mind.

The basic problem here is that we don't have a clear commonly-shared idea of
what we want to support with these features.

My suggestion is to start from clarifying these requirements.  A good method
of understanding requirements is to describe typical use-cases and their
variations, as you probably know.  With that in mind, would you or someone
else please describe such use-cases?  Specifically:

  . what does the user specify?
  . what should happen with key bindings to various commands as result of
    the user specifications?

For instance, with your example:

> ;; The user will specify concept / abstract commands -> key sequences
> (setq-custom concept-sequences '((user-next ?\M-n) (user-prev ?\M-p)))
> ;; The package will specify concepts / abstract commands -> concrete commands
> ;; So, something like a magit section mode intended to be derived from, the 
> package author writes:
> (setq-local concept-commands '((user-next #'magit-section-next) (user-prev 
> #'magit-section-prev)))
> ;; And then the package tells the implementation to consume the declarations, 
> which might occur after the
> mode hook to let the user intervene
> (emacs-function-setup-concept-keymap)

I have no idea what will be the binding of magit-section-next.  And, since
you only gave a single command as an example, I have no idea how is what you
propose better than just saying

  (local-set-key ?\M-n #'magit-section-next)

I understand what Stefan says about "letters" (probably meaning that 'n'
should be used in "next-FOO" commands and 'p' in "prev-FOO"), but I don't
understand what you are saying, because you didn't tell enough about your
eventual goal, in practical terms.