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

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

[Konstantin Kharlamov]

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

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.

[-- Attachment #2: 1.patch --]
[-- Type: text/x-patch, Size: 1060 bytes --]

From f0cf72a973caf5063a4a1cab4fcc0bd73d0d7976 Mon Sep 17 00:00:00 2001
From: Konstantin Kharlamov <Hi-Angel@yandex.ru>
Date: Thu, 14 Mar 2024 02:33:06 +0300
Subject: [PATCH] docs: mention the keymap to add keybindings to for term-mode

A user typically expects a keymap for mode `foo` to be called
`foo-mode-map`.  term-mode has `term-mode-map` too, but for
user-defined bindings to have effect they have to be put to
`term-raw-map` instead.  So let's mention that.

* doc/emacs/misc.texi (Term mode): mention the keymap to add
keybindings to for term-mode
---
 doc/emacs/misc.texi | 4 ++++
 1 file changed, 4 insertions(+)

diff --git a/doc/emacs/misc.texi b/doc/emacs/misc.texi
index 7eb28f56826..471cd2eed1a 100644
--- a/doc/emacs/misc.texi
+++ b/doc/emacs/misc.texi
@@ -1651,6 +1651,10 @@ Term Mode
 interface is similar to the @code{more} program.
 @end table
 
+@cindex keymap in Term mode
+  To add custom keybindings to the Term mode use @code{term-raw-map}
+keymap.
+
 @node Remote Host
 @subsection Remote Host Shell
 @cindex remote host
-- 
2.44.0

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

[Eli Zaretskii]

> From: Konstantin Kharlamov <Hi-Angel@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.

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

[Konstantin Kharlamov]

On Thu, 2024-03-14 at 07:11 +0200, Eli Zaretskii wrote:
> > From: Konstantin Kharlamov <Hi-Angel@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.

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

[Konstantin Kharlamov]

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@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.

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

[Eli Zaretskii]

> From: Konstantin Kharlamov <Hi-Angel@yandex.ru>
> Cc: 69786@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.)

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

[Eli Zaretskii]

> From: Konstantin Kharlamov <Hi-Angel@yandex.ru>
> Cc: 69786@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.

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

[Konstantin Kharlamov]

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 😊

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

[Eli Zaretskii]

> From: Konstantin Kharlamov <Hi-Angel@yandex.ru>
> Cc: 69786@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.

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

[Konstantin Kharlamov]

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

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.

[-- Attachment #2: 1.patch --]
[-- Type: text/x-patch, Size: 1966 bytes --]

From 8f5d861fcc91d590d5e7370b1eb1e79e6e69f62d Mon Sep 17 00:00:00 2001
From: Konstantin Kharlamov <Hi-Angel@yandex.ru>
Date: Sat, 16 Mar 2024 13:24:34 +0300
Subject: [PATCH] term-mode: mention the keymap to add keybindings to

A user typically expects a keymap for mode `foo` to be called
`foo-mode-map`.  term-mode has `term-mode-map` too, but for
user-defined bindings to have effect they have to be put to
`term-raw-map` instead.  So let's mention that.

* lisp/term.el (term-mode) (term-mode-map) (term-raw-map): mention the
keymap to add keybindings to for term-mode
---
 lisp/term.el | 11 +++++++++--
 1 file changed, 9 insertions(+), 2 deletions(-)

diff --git a/lisp/term.el b/lisp/term.el
index 2ce0c2b5e79..9c890e80379 100644
--- a/lisp/term.el
+++ b/lisp/term.el
@@ -658,7 +658,8 @@ term-mode-map
         ["Forward Output Group" term-next-prompt t]
         ["Kill Current Output Group" term-kill-output t]))
     map)
-  "Keymap for Term mode.")
+  "Keymap for \"line mode\" in Term mode.  For custom keybindings purposes
+please note there is also `term-raw-map'")
 
 (defvar term-escape-char nil
   "Escape character for char sub-mode of term mode.
@@ -961,7 +962,9 @@ term-raw-map
       (dotimes (key 21)
         (keymap-set map (format "<f%d>" key) #'term-send-function-key)))
     map)
-  "Keyboard map for sending characters directly to the inferior process.")
+  "Keyboard map for sending characters directly to the inferior process.
+For custom keybindings purposes please note there is also
+`term-mode-map'")
 
 (easy-menu-define term-terminal-menu
   (list term-mode-map term-raw-map term-pager-break-map)
@@ -1122,6 +1125,10 @@ term-mode
 and the variable `term-prompt-regexp' to the appropriate regular
 expression.
 
+If you define custom keybindings, make sure to assign them to the
+correct keymap (or to both): use `term-raw-map' in raw mode and
+`term-mode-map' in line mode.
+
 Commands in raw mode:
 
 \\{term-raw-map}
-- 
2.44.0

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

[Eli Zaretskii]

> From: Konstantin Kharlamov <Hi-Angel@yandex.ru>
> Cc: 69786@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.

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

[Konstantin Kharlamov]

On Sat, 2024-03-16 at 13:31 +0200, Eli Zaretskii wrote:
> > From: Konstantin Kharlamov <Hi-Angel@yandex.ru>
> > Cc: 69786@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.