GNU bug report logs - #69786
[PATCH] docs: mention the keymap to add keybindings to for term-mode

Previous Next

To add a comment to this bug, you must first unarchive it, by sending
a message to control AT debbugs.gnu.org, with unarchive 69786 in the body.
You can then email your comments to 69786 AT debbugs.gnu.org in the normal way.

Toggle the display of automated, internal messages from the tracker.

Message #5 received at submit <at> debbugs.gnu.org (full text, mbox):

From: Konstantin Kharlamov <Hi-Angel <at> yandex.ru>
To: bug-gnu-emacs <at> gnu.org
Subject: [PATCH] docs: mention the keymap to add keybindings to for term-mode
Date: Thu, 14 Mar 2024 02:39:23 +0300

[Message part 1 (text/plain, inline)]

I've spent quite some time today trying to somehow override keybindings
for term-mode. While time was spent mostly due to some local mistakes,
one problem I also noticed is that term-mode has `term-mode-map` —
pretty much like any other major mode foo typically have `foo-mode-
map`. However, adding keybindings into it has no effect whatsoever.
Instead term-mode has an additional `term-raw-map`, which is the actual
location where one has to put custom bindings.

It is completely non-intuitive (and I also for some reason didn't get
the answer on emacs.stackexchange for the same problem when I was
trying to google it), so let's document that nuisance.

[1.patch (text/x-patch, attachment)]

Message #8 received at 69786 <at> debbugs.gnu.org (full text, mbox):

From: Eli Zaretskii <eliz <at> gnu.org>
To: Konstantin Kharlamov <Hi-Angel <at> yandex.ru>
Cc: 69786 <at> debbugs.gnu.org
Subject: Re: bug#69786: [PATCH] docs: mention the keymap to add keybindings to
 for term-mode
Date: Thu, 14 Mar 2024 07:11:05 +0200

> From: Konstantin Kharlamov <Hi-Angel <at> yandex.ru>
> Date: Thu, 14 Mar 2024 02:39:23 +0300
> 
> I've spent quite some time today trying to somehow override keybindings
> for term-mode. While time was spent mostly due to some local mistakes,
> one problem I also noticed is that term-mode has `term-mode-map` —
> pretty much like any other major mode foo typically have `foo-mode-
> map`. However, adding keybindings into it has no effect whatsoever.
> Instead term-mode has an additional `term-raw-map`, which is the actual
> location where one has to put custom bindings.
> 
> It is completely non-intuitive (and I also for some reason didn't get
> the answer on emacs.stackexchange for the same problem when I was
> trying to google it), so let's document that nuisance.

Thanks, but the Emacs user manual is not the right place for this kind
of information.  Instead, this should be mentioned in the doc string
of term-mode.

Btw, your understanding of this is at least inaccurate if not
incorrect: whether custom key bindings should be added to
term-mode-map or term-raw-map depends on whether you want them for the
line mode or for the raw mode.  The documentation should say so.

Message #11 received at 69786 <at> debbugs.gnu.org (full text, mbox):

From: Konstantin Kharlamov <Hi-Angel <at> yandex.ru>
To: Eli Zaretskii <eliz <at> gnu.org>
Cc: 69786 <at> debbugs.gnu.org
Subject: Re: bug#69786: [PATCH] docs: mention the keymap to add keybindings
 to for term-mode
Date: Thu, 14 Mar 2024 10:20:22 +0300

On Thu, 2024-03-14 at 07:11 +0200, Eli Zaretskii wrote:
> > From: Konstantin Kharlamov <Hi-Angel <at> yandex.ru>
> > Date: Thu, 14 Mar 2024 02:39:23 +0300
> > 
> > I've spent quite some time today trying to somehow override
> > keybindings
> > for term-mode. While time was spent mostly due to some local
> > mistakes,
> > one problem I also noticed is that term-mode has `term-mode-map` —
> > pretty much like any other major mode foo typically have `foo-mode-
> > map`. However, adding keybindings into it has no effect whatsoever.
> > Instead term-mode has an additional `term-raw-map`, which is the
> > actual
> > location where one has to put custom bindings.
> > 
> > It is completely non-intuitive (and I also for some reason didn't
> > get
> > the answer on emacs.stackexchange for the same problem when I was
> > trying to google it), so let's document that nuisance.
> 
> Thanks, but the Emacs user manual is not the right place for this
> kind
> of information.

Why not?

> Instead, this should be mentioned in the doc string
> of term-mode.

As a long-time Emacs user, I'd have never looked at major mode
documentation.  That's because you'd expect it describe what the mode
is for, however typically if you start using a major mode, you already
know that.  As a matter of fact, the mode name alone is often enough to
describe its purpose.

I see that major mode docs may sometimes also describe keybindings, but
since it has to be explicitly added by the mode developer (which
implies the docs may or may not be there), neither I'd look at it for
that purpose.  Instead I'd typically execute `C-h m` which is
guaranteed to pop up a buffer with all keybindings.

> Btw, your understanding of this is at least inaccurate if not
> incorrect: whether custom key bindings should be added to
> term-mode-map or term-raw-map depends on whether you want them for
> the
> line mode or for the raw mode.  The documentation should say so.

Oh, thank you, I should fix that then.

Message #14 received at 69786 <at> debbugs.gnu.org (full text, mbox):

From: Konstantin Kharlamov <Hi-Angel <at> yandex.ru>
To: Eli Zaretskii <eliz <at> gnu.org>
Cc: 69786 <at> debbugs.gnu.org
Subject: Re: bug#69786: [PATCH] docs: mention the keymap to add keybindings
 to for term-mode
Date: Thu, 14 Mar 2024 10:23:32 +0300

On Thu, 2024-03-14 at 10:20 +0300, Konstantin Kharlamov wrote:
> On Thu, 2024-03-14 at 07:11 +0200, Eli Zaretskii wrote:
> > > From: Konstantin Kharlamov <Hi-Angel <at> yandex.ru>
> > > Date: Thu, 14 Mar 2024 02:39:23 +0300
> > > 
> > > I've spent quite some time today trying to somehow override
> > > keybindings
> > > for term-mode. While time was spent mostly due to some local
> > > mistakes,
> > > one problem I also noticed is that term-mode has `term-mode-map`
> > > —
> > > pretty much like any other major mode foo typically have `foo-
> > > mode-
> > > map`. However, adding keybindings into it has no effect
> > > whatsoever.
> > > Instead term-mode has an additional `term-raw-map`, which is the
> > > actual
> > > location where one has to put custom bindings.
> > > 
> > > It is completely non-intuitive (and I also for some reason didn't
> > > get
> > > the answer on emacs.stackexchange for the same problem when I was
> > > trying to google it), so let's document that nuisance.
> > 
> > Thanks, but the Emacs user manual is not the right place for this
> > kind
> > of information.
> 
> Why not?
> 
> > Instead, this should be mentioned in the doc string
> > of term-mode.
> 
> As a long-time Emacs user, I'd have never looked at major mode
> documentation.  That's because you'd expect it describe what the mode
> is for, however typically if you start using a major mode, you
> already
> know that.  As a matter of fact, the mode name alone is often enough
> to
> describe its purpose.
> 
> I see that major mode docs may sometimes also describe keybindings,
> but
> since it has to be explicitly added by the mode developer (which
> implies the docs may or may not be there), neither I'd look at it for
> that purpose.  Instead I'd typically execute `C-h m` which is
> guaranteed to pop up a buffer with all keybindings.

…with that said, if we have to put that to the mode documentation and
not to the manual, I think a more appropriate place might be docs for
`term-mode-map` and `term-raw-map` accordingly.  This is a place where
I would have looked after finding out that my custom keyindings do not
work.

Message #17 received at 69786 <at> debbugs.gnu.org (full text, mbox):

From: Eli Zaretskii <eliz <at> gnu.org>
To: Konstantin Kharlamov <Hi-Angel <at> yandex.ru>
Cc: 69786 <at> debbugs.gnu.org
Subject: Re: bug#69786: [PATCH] docs: mention the keymap to add keybindings
 to for term-mode
Date: Thu, 14 Mar 2024 09:33:38 +0200

> From: Konstantin Kharlamov <Hi-Angel <at> yandex.ru>
> Cc: 69786 <at> debbugs.gnu.org
> Date: Thu, 14 Mar 2024 10:20:22 +0300
> 
> On Thu, 2024-03-14 at 07:11 +0200, Eli Zaretskii wrote:
> > > It is completely non-intuitive (and I also for some reason didn't
> > > get
> > > the answer on emacs.stackexchange for the same problem when I was
> > > trying to google it), so let's document that nuisance.
> > 
> > Thanks, but the Emacs user manual is not the right place for this
> > kind
> > of information.
> 
> Why not?

Because this is information on the level of customization via Lisp
programming, not the level of _using_ Emacs.  One can use a mode
without having any idea how its map is called.

> > Instead, this should be mentioned in the doc string
> > of term-mode.
> 
> As a long-time Emacs user, I'd have never looked at major mode
> documentation.  That's because you'd expect it describe what the mode
> is for, however typically if you start using a major mode, you already
> know that.  As a matter of fact, the mode name alone is often enough to
> describe its purpose.

If you ignore doc strings in Emacs, you are making a mistake, IMO.  I
believe many/most users do consult the doc strings, and I urge you to
teach yourself to look there, not just in the manuals.  The manuals
don't (and cannot) cover all the public variables and functions,
whereas the doc strings can and do.

> I see that major mode docs may sometimes also describe keybindings

I wasn't talking about the key bindings, I was talking about the
specific quirk of this mode: that it has several distinct keymaps
instead of just one.  This is somewhat unusual, and thus deserves to
be called out in the doc string of the mode, since the maps belong to
the mode.  (Each of the maps has its own doc string that explains its
purpose, but that is not enough because those doc strings are not
easily discoverable.  Mentioning the maps in the doc string of the
mode will close the gap.)

Message #20 received at 69786 <at> debbugs.gnu.org (full text, mbox):

From: Eli Zaretskii <eliz <at> gnu.org>
To: Konstantin Kharlamov <Hi-Angel <at> yandex.ru>
Cc: 69786 <at> debbugs.gnu.org
Subject: Re: bug#69786: [PATCH] docs: mention the keymap to add keybindings
 to for term-mode
Date: Thu, 14 Mar 2024 09:34:51 +0200

> From: Konstantin Kharlamov <Hi-Angel <at> yandex.ru>
> Cc: 69786 <at> debbugs.gnu.org
> Date: Thu, 14 Mar 2024 10:23:32 +0300
> 
> …with that said, if we have to put that to the mode documentation and
> not to the manual, I think a more appropriate place might be docs for
> `term-mode-map` and `term-raw-map` accordingly.  This is a place where
> I would have looked after finding out that my custom keyindings do not
> work.

We can do that as well, sure.  But that alone is not enough because
the information will then be less discoverable.

Message #23 received at 69786 <at> debbugs.gnu.org (full text, mbox):

From: Konstantin Kharlamov <Hi-Angel <at> yandex.ru>
To: Eli Zaretskii <eliz <at> gnu.org>
Cc: 69786 <at> debbugs.gnu.org
Subject: Re: bug#69786: [PATCH] docs: mention the keymap to add keybindings
 to for term-mode
Date: Thu, 14 Mar 2024 10:53:50 +0300

On Thu, 2024-03-14 at 09:33 +0200, Eli Zaretskii wrote:
> 
> If you ignore doc strings in Emacs, you are making a mistake, IMO.  I
> believe many/most users do consult the doc strings, and I urge you to
> teach yourself to look there, not just in the manuals.  The manuals
> don't (and cannot) cover all the public variables and functions,
> whereas the doc strings can and do.

I don't "ignore doc strings in Emacs", that is impossible to do because
you have to consult at least function docs to customize, fix problems,
etc 😊  Instead I ignore specifically major mode documentation and I'd
be surprised if too many other people read it.  You see, documentation
should be intuitive.  A user asks a question "how to do X", the answer
intuitively should be "search docs for X".  If you ask "why my
customizations to term-mode-map do not work?", the answer would be
"look at term-mode-map docs, perhaps it mentions something".

Similarly, by intuition, if I ask myself "what docs do I expect the
`term-mode` to have", I'd reply "General information about the mode,
i.e. that it launches a terminal and maybe a reference to shell and
eshell alternatives".  I'd not expect my problem with the not working
keybindings to be mentioned in term-mode doc-string (even if it is
actually there).

> > I see that major mode docs may sometimes also describe keybindings
> 
> I wasn't talking about the key bindings, I was talking about the
> specific quirk of this mode: that it has several distinct keymaps
> instead of just one.  This is somewhat unusual, and thus deserves to
> be called out in the doc string of the mode, since the maps belong to
> the mode.  (Each of the maps has its own doc string that explains its
> purpose, but that is not enough because those doc strings are not
> easily discoverable.  Mentioning the maps in the doc string of the
> mode will close the gap.)

Okay then, I'll add docs to the `term-mode` if you think it might be
useful for someone and (re: the other email) to `term-mode-map` and
`term-raw-map` variables 😊

Message #26 received at 69786 <at> debbugs.gnu.org (full text, mbox):

From: Eli Zaretskii <eliz <at> gnu.org>
To: Konstantin Kharlamov <Hi-Angel <at> yandex.ru>
Cc: 69786 <at> debbugs.gnu.org
Subject: Re: bug#69786: [PATCH] docs: mention the keymap to add keybindings
 to for term-mode
Date: Thu, 14 Mar 2024 13:09:25 +0200

> From: Konstantin Kharlamov <Hi-Angel <at> yandex.ru>
> Cc: 69786 <at> debbugs.gnu.org
> Date: Thu, 14 Mar 2024 10:53:50 +0300
> 
> On Thu, 2024-03-14 at 09:33 +0200, Eli Zaretskii wrote:
> > 
> > If you ignore doc strings in Emacs, you are making a mistake, IMO.  I
> > believe many/most users do consult the doc strings, and I urge you to
> > teach yourself to look there, not just in the manuals.  The manuals
> > don't (and cannot) cover all the public variables and functions,
> > whereas the doc strings can and do.
> 
> I don't "ignore doc strings in Emacs", that is impossible to do because
> you have to consult at least function docs to customize, fix problems,
> etc 😊  Instead I ignore specifically major mode documentation and I'd
> be surprised if too many other people read it.  You see, documentation
> should be intuitive.  A user asks a question "how to do X", the answer
> intuitively should be "search docs for X".  If you ask "why my
> customizations to term-mode-map do not work?", the answer would be
> "look at term-mode-map docs, perhaps it mentions something".

FWIW, I generally find the documentation strings of modes very useful.

> Similarly, by intuition, if I ask myself "what docs do I expect the
> `term-mode` to have", I'd reply "General information about the mode,
> i.e. that it launches a terminal and maybe a reference to shell and
> eshell alternatives".  I'd not expect my problem with the not working
> keybindings to be mentioned in term-mode doc-string (even if it is
> actually there).

The doc string of a mode should, for example, mention the mode hook
and other important variables.  And if there are some unusual things
going on with its keymaps, then yes, that should also be mentioned.

> > > I see that major mode docs may sometimes also describe keybindings
> > 
> > I wasn't talking about the key bindings, I was talking about the
> > specific quirk of this mode: that it has several distinct keymaps
> > instead of just one.  This is somewhat unusual, and thus deserves to
> > be called out in the doc string of the mode, since the maps belong to
> > the mode.  (Each of the maps has its own doc string that explains its
> > purpose, but that is not enough because those doc strings are not
> > easily discoverable.  Mentioning the maps in the doc string of the
> > mode will close the gap.)
> 
> Okay then, I'll add docs to the `term-mode` if you think it might be
> useful for someone and (re: the other email) to `term-mode-map` and
> `term-raw-map` variables 😊

Thanks.

Message #29 received at 69786 <at> debbugs.gnu.org (full text, mbox):

From: Konstantin Kharlamov <Hi-Angel <at> yandex.ru>
To: Eli Zaretskii <eliz <at> gnu.org>
Cc: 69786 <at> debbugs.gnu.org
Subject: Re: bug#69786: [PATCH] docs: mention the keymap to add keybindings
 to for term-mode
Date: Sat, 16 Mar 2024 13:36:20 +0300

[Message part 1 (text/plain, inline)]

On Thu, 2024-03-14 at 13:09 +0200, Eli Zaretskii wrote:
> 
> > Okay then, I'll add docs to the `term-mode` if you think it might
> > be
> > useful for someone and (re: the other email) to `term-mode-map` and
> > `term-raw-map` variables 😊
> 
> Thanks.

Done, please see if it's okay now.

While at it, could you please remind me how to use `C-x 4 a` to get a
log of changes to be copied to the commit? I'm trying to use it but
always seem to get random results: sometimes I get "COMMIT_MSG" file,
other times I get a `* lisp/term.el (term-mode-map):` line even though
the `term.el` has also `term-mode` and `term-raw-map` modified… I
presume I might need some special setup for this to work, right? Like,
Idk, having the changes in the git-stash or something like that…? I
dunno, I'm just making things up.

[1.patch (text/x-patch, attachment)]

Message #34 received at 69786-done <at> debbugs.gnu.org (full text, mbox):

From: Eli Zaretskii <eliz <at> gnu.org>
To: Konstantin Kharlamov <Hi-Angel <at> yandex.ru>
Cc: 69786-done <at> debbugs.gnu.org
Subject: Re: bug#69786: [PATCH] docs: mention the keymap to add keybindings
 to for term-mode
Date: Sat, 16 Mar 2024 13:31:20 +0200

> From: Konstantin Kharlamov <Hi-Angel <at> yandex.ru>
> Cc: 69786 <at> debbugs.gnu.org
> Date: Sat, 16 Mar 2024 13:36:20 +0300
> 
> On Thu, 2024-03-14 at 13:09 +0200, Eli Zaretskii wrote:
> > 
> > > Okay then, I'll add docs to the `term-mode` if you think it might
> > > be
> > > useful for someone and (re: the other email) to `term-mode-map` and
> > > `term-raw-map` variables 😊
> > 
> > Thanks.
> 
> Done, please see if it's okay now.

Thanks, installed on the emacs-29 branch, and closing the bug.

Please in the future try to remember mentioning the bug number (if
known) in the commit log message, and also quote symbols `like this'
or 'like this', but not `like this`.

> While at it, could you please remind me how to use `C-x 4 a` to get a
> log of changes to be copied to the commit? I'm trying to use it but
> always seem to get random results: sometimes I get "COMMIT_MSG" file,
> other times I get a `* lisp/term.el (term-mode-map):` line even though
> the `term.el` has also `term-mode` and `term-raw-map` modified… I
> presume I might need some special setup for this to work, right? Like,
> Idk, having the changes in the git-stash or something like that…? I
> dunno, I'm just making things up.

You need to have point in the body of the function/variable when you
type "C-x 4 a".  I think that's the cause of the problems you
describe.

Message #37 received at 69786-done <at> debbugs.gnu.org (full text, mbox):

From: Konstantin Kharlamov <Hi-Angel <at> yandex.ru>
To: Eli Zaretskii <eliz <at> gnu.org>
Cc: 69786-done <at> debbugs.gnu.org
Subject: Re: bug#69786: [PATCH] docs: mention the keymap to add keybindings
 to for term-mode
Date: Sat, 16 Mar 2024 16:20:49 +0300

On Sat, 2024-03-16 at 13:31 +0200, Eli Zaretskii wrote:
> > From: Konstantin Kharlamov <Hi-Angel <at> yandex.ru>
> > Cc: 69786 <at> debbugs.gnu.org
> > Date: Sat, 16 Mar 2024 13:36:20 +0300
> >
> > On Thu, 2024-03-14 at 13:09 +0200, Eli Zaretskii wrote:
> > >
> > > > Okay then, I'll add docs to the `term-mode` if you think it
> > > > might
> > > > be
> > > > useful for someone and (re: the other email) to `term-mode-map`
> > > > and
> > > > `term-raw-map` variables 😊
> > >
> > > Thanks.
> >
> > Done, please see if it's okay now.
>
> Thanks, installed on the emacs-29 branch, and closing the bug.

Thank you!

> Please in the future try to remember mentioning the bug number (if
> known) in the commit log message, and also quote symbols `like this'
> or 'like this', but not `like this`.

Ah, sorry about that, point taken.  I thought the `' style of quoting is only of
importance in doc-strings (where I have them correct).  I had them different in
commit message though, I see.

I just wrote a config to replace the quote if I'm editing a commit inside Emacs repo,
so hopefully that won't a problem in the future.  😊 Sharing the code for posterity:

    (use-package smartparens-config
      …
      (defun sp-emacs-style-backtick (_ _ _)
        "Text-mode is used for editing the commit messages. Emacs has style where
    a backtick ends with a sungular quote, so let's check if current dir is
    part of Emacs repo, in which case replace the pair that SP inserted."
        (save-excursion
          (when (string-match-p "\\bemacs\\b" default-directory)
            (delete-char 1)
            (insert "'"))))

      (sp-local-pair 'text-mode "`" nil :post-handlers '(:add sp-emacs-style-backtick))
      )


> > While at it, could you please remind me how to use `C-x 4 a` to get
> > a
> > log of changes to be copied to the commit? I'm trying to use it but
> > always seem to get random results: sometimes I get "COMMIT_MSG"
> > file,
> > other times I get a `* lisp/term.el (term-mode-map):` line even
> > though
> > the `term.el` has also `term-mode` and `term-raw-map` modified… I
> > presume I might need some special setup for this to work, right?
> > Like,
> > Idk, having the changes in the git-stash or something like that…? I
> > dunno, I'm just making things up.
>
> You need to have point in the body of the function/variable when you
> type "C-x 4 a".  I think that's the cause of the problems you
> describe.

Oh, that's unfortunate, I thought it's gathering all changed functions and not just
the one at point.

Previous Next

GNU bug tracking system
Copyright (C) 1999 Darren O. Benham, 1997,2003 nCipher Corporation Ltd, 1994-97 Ian Jackson.