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.