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.