GNU bug report logs - #4472
23.1; Emacs manual not too helpful about binding keys

Previous Next

To add a comment to this bug, you must first unarchive it, by sending
a message to control AT debbugs.gnu.org, with unarchive 4472 in the body.
You can then email your comments to 4472 AT debbugs.gnu.org in the normal way.

Toggle the display of automated, internal messages from the tracker.

Message #5 received at submit <at> emacsbugs.donarmstrong.com (full text, mbox):

From: "Drew Adams" <drew.adams <at> oracle.com>
To: <bug-gnu-emacs <at> gnu.org>
Subject: 23.1; Emacs manual not too helpful about binding keys
Date: Thu, 17 Sep 2009 15:51:39 -0700

I find the Emacs manual not to be very helpful about how to bind key
sequences.  I couldn't even find the form (kbd...) in the manual, and
I thought that was what we are now recommending in general (no?).
 
I tried using `i' in the manual to find information about how to bind
keys, but it wasn't very helpful. I looked for `binding', and the only
index entry was for node Commands. I tried `i key TAB' and saw lots
that looks similar (rebinding, binding,...). Not too clear to me.
 
I finally found node Init Rebinding (weird name, BTW). It had examples
of using strings such as "\C-z" and vectors such as [?\C-=] and
[C-mouse-1], but it had nothing about `kbd' or the form [(control
mouse-1)].
 
I didn't find a node that explained the various formats and their
different uses and limitations. I didn't find any general format
recommendations. I didn't find any link in Init Rebinding to another
node that might explain such things - the only link there sends you to
a node explaining details about keyboard encodings and binding
non-ASCII keys.
 
Where is the introductory, top-level explanation about recommended
ways to bind keys? Surely that's something that even lots of
non-expert users do. The Key Bindings node (from node Customization)
sends you immediately into the depths of understanding keymaps - no
introduction there about binding keys AFAICT.
 
I did find information about `kbd' in the Elisp manual, and even some
text that stresses its convenience and portability. But that
information is missing from the Emacs manual AFAICT. IIUC, this is
info that is quite important for most users. There are often questions
at help-gnu-emacs about how to bind keys, and the answer there is
typically: "Use kbd". If this is a FAQ, then the answer belongs in the
Emacs manual, no?
 
I this kind of info belongs in the Emacs manual and I hope that
someone can find the time to add it (or move it) there.

In GNU Emacs 23.1.1 (i386-mingw-nt5.1.2600)
 of 2009-07-29 on SOFT-MJASON
Windowing system distributor `Microsoft Corp.', version 5.1.2600
configured using `configure --with-gcc (4.4)'

Message #10 received at 4472 <at> emacsbugs.donarmstrong.com (full text, mbox):

From: Chong Yidong <cyd <at> stupidchicken.com>
To: "Drew Adams" <drew.adams <at> oracle.com>
Cc: 4472 <at> debbugs.gnu.org
Subject: Re: 23.1; Emacs manual not too helpful about binding keys
Date: Fri, 18 Sep 2009 19:11:10 -0400

> I couldn't even find the form (kbd...) in the manual, and I thought
> that was what we are now recommending in general (no?).

From the manual:

     There are several ways to write a key binding using Lisp.  The
  simplest is to use the `kbd' macro, which converts a textual
  representation of a key sequence--similar to how we have written key
  sequences in this manual--into a form that can be passed as an argument
  to `global-set-key'.  For example, here's how to bind `C-z' to `shell'
  (*note Interactive Shell::):

       (global-set-key (kbd "C-z") 'shell)

etc., etc.

Message #15 received at 4472 <at> emacsbugs.donarmstrong.com (full text, mbox):

From: "Drew Adams" <drew.adams <at> oracle.com>
To: "'Chong Yidong'" <cyd <at> stupidchicken.com>
Cc: <4472 <at> debbugs.gnu.org>
Subject: RE: 23.1; Emacs manual not too helpful about binding keys
Date: Fri, 18 Sep 2009 16:27:44 -0700

> > I couldn't even find the form (kbd...) in the manual, and I thought
> > that was what we are now recommending in general (no?).
> 
> From the manual:
> 
...

My bad about that. Much of what I wrote in the bug report is still true, but the
part about kbd is no longer true (good).

I copied the text I has sent as a mail to emacs-devel in August of 2008 (to
which I got no reply), and at that time what I said about kbd etc. was indeed
true (for CVS Emacs).

Please read the whole bug report, and filter out whatever has been fixed since
then.

Message #20 received at 4472-done <at> emacsbugs.donarmstrong.com (full text, mbox):

From: Chong Yidong <cyd <at> stupidchicken.com>
To: "Drew Adams" <drew.adams <at> oracle.com>
Cc: <4472-done <at> debbugs.gnu.org>
Subject: Re: 23.1; Emacs manual not too helpful about binding keys
Date: Sat, 19 Sep 2009 17:28:54 -0400

"Drew Adams" <drew.adams <at> oracle.com> writes:

> Please read the whole bug report, and filter out whatever has been fixed since
> then.

I've checked in some changes which should clarify things.

Previous Next

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