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

[Eli Zaretskii <eliz@gnu.org>]

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