0

Suppose, that I am writing an Emacs mode for some language. I am creating a corresponding keymap to bind various keys. I want to provide some kind of help/documentation function. I can bind it (within the mode keymap) to C-h ., similar to what eglot does. The intention is for this action to be inside of the help-map, familiar to the user.

However, the user could have remapped help-map to some other key, thus breaking the intention. So, it would make sense that I should have bound my function (within the mode keymap) to <help-map> ., not C-h ..

However, I have never seen modes do that. Is that an unreasonable idea? Why? How does one avoid breaking the intention in that case?

Note that while I'm describing a specific situation where probably a better keybinding can be found, the question is itself general. E.g. it might be about mode-specific-map as opposed to help-map.

0

2 Answers 2

1

The question is a bit unclear.

  • If you want to make sure the command is bound to C-h . (for example) then bind it to C-h ..
  • If, on the other hand, you want to make sure the command is on keymap help-map (for example), so that whatever prefix keys help-map is ever bound to the command will also have those prefix keys, then bind it to a key in help-map.

Likewise, for any other keymap. Do you want your command grouped with the commands on the keymap, regardless of what keys that map is bound to? Or do you want your command to have (only) a particular prefix key?

Those different intentions are realized in those two different ways. There's nothing more to it.

6
  • You are right, I missed some context. When you are writing a mode, from what I understand, you are supposed to create a corresponding keymap and store all the keybindings related to your mode in that keymap. That means that you can't bind to help-map, because you have your own, mode-related, keymap.
    – Artem Yu
    Jan 5 at 15:05
  • (1) Please put all relevant info clarifying your question into the question itself. Comments aren't searchable, and they can be deleted at any time. (2) You can, in your new mode, bind any keys to any keymaps you want. And you can bind a mode-specific keymap to any keymap you want. Please be specific (in your question) about what the problem is that you want to resolve.
    – Drew
    Jan 5 at 19:14
  • (1) I believe that I have added all the context from the comment to the question description as well, but please do tell if it doesn't seem complete. (2) "you can bind a mode-specific keymap to any keymap" I've never seen anyone do it, so I'm asking if there's a good reason not to do it or vice versa.
    – Artem Yu
    Jan 5 at 22:34
  • For #2: Bookmark+ has multiple examples of this. Here's one: define-key bookmark-map "c" bmkp-set-map). Here's another (different kind): (set-keymap-parent bookmark-bmenu-mode-map special-mode-map). No good reason not to put a keymap on another keymap, or to inherit a keymap from another keymap.
    – Drew
    Jan 5 at 23:57
  • 1
    It's up to you. If your question is a "how" one or a "can I" one, then you have your answer. If your question is a moral one ("bad taste"), you're on your own. IMHO, it's fine to add bindings to an existing keymap, provided you tell users of your library that it does that. Use of your library is optional, after all. Even better, and my recommendation, is to create the bindings within a minor mode or some other command or a user option you define. Then it's even clearer that it's a user's choice whether to bind the keys/keymap (or whatever).
    – Drew
    Jan 6 at 4:18
1

If you are writing a mode for a language then I assume it's gonna be a major-mode. I am not sure what is your exact goal, but generally, documentation, including that for the major-mode map, can be found under C-h m. So just document your mode well when defining the mode. Users then can find its documentation under C-h m. Eglot is (uses) a minor-mode, hence the documentation can not be found under C-h m.

If you would like to have some 'additional' documentation functionality, you could consider binding C-h m to a prefix command (see the answer to your other question), and bind your different 'help functions' there.

EDIT in response to your comment

I did not look at eglot keybindings, but C-h . is bound to display-local-help, I guess eglot makes use of that functionality.

It is definitely reasonable to use 'relative' keybindings. I would say you can 'regard' the maps as sections in a menu (and they are used as such in the menu-bar). However, generally, it is preferable to create dedicated prefixes (and also put help functions there, although major modes are documented via C-h m). Minor modes are often used to configure a certain set of keybindings, you can put them anywhere you want (after considering the conventions. You can check out evil or Spacemacs, but generally they don't touch core Emacs keybindings (like e.g. C-h).

Of course, if your mode is for private use only, then you can place the keybindings anywhere you prefer. If you would like to make the package publicly available, you should try hard to avoid keybindings conflicting with keybindings of other packages.

END EDIT

1
  • C-h m is an absolute keybinding. However, we might want it to be relative, e.g. <help> m. My question is: is it a bad idea to use relative keybindings in mode-specific keymaps. It seems that my questions is very ill-formulated, so I'll probably just delete it to avoid further confusion
    – Artem Yu
    Jan 5 at 23:19

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service and acknowledge you have read our privacy policy.

Not the answer you're looking for? Browse other questions tagged or ask your own question.