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 😊