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

Previous Next

Full log

Message #17 received at 69786 <at> debbugs.gnu.org (full text, mbox):

From: Eli Zaretskii <eliz <at> gnu.org>
To: Konstantin Kharlamov <Hi-Angel <at> yandex.ru>
Cc: 69786 <at> debbugs.gnu.org
Subject: Re: bug#69786: [PATCH] docs: mention the keymap to add keybindings
 to for term-mode
Date: Thu, 14 Mar 2024 09:33:38 +0200

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

Previous Next

GNU bug tracking system
Copyright (C) 1999 Darren O. Benham, 1997,2003 nCipher Corporation Ltd, 1994-97 Ian Jackson.