From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.org!not-for-mail From: Alan Mackenzie Newsgroups: gmane.emacs.devel Subject: Rant: key sequences aren't specified in the elisp manual. Date: Thu, 17 Nov 2005 22:29:40 +0000 (GMT) Message-ID: NNTP-Posting-Host: main.gmane.org Mime-Version: 1.0 Content-Type: TEXT/PLAIN; charset=US-ASCII X-Trace: sea.gmane.org 1132266439 18044 80.91.229.2 (17 Nov 2005 22:27:19 GMT) X-Complaints-To: usenet@sea.gmane.org NNTP-Posting-Date: Thu, 17 Nov 2005 22:27:19 +0000 (UTC) Original-X-From: emacs-devel-bounces+ged-emacs-devel=m.gmane.org@gnu.org Thu Nov 17 23:27:12 2005 Return-path: Original-Received: from lists.gnu.org ([199.232.76.165]) by ciao.gmane.org with esmtp (Exim 4.43) id 1EcsBu-0003Gx-US for ged-emacs-devel@m.gmane.org; Thu, 17 Nov 2005 23:25:15 +0100 Original-Received: from localhost ([127.0.0.1] helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.43) id 1EcsBu-0002Yv-E5 for ged-emacs-devel@m.gmane.org; Thu, 17 Nov 2005 17:25:14 -0500 Original-Received: from mailman by lists.gnu.org with tmda-scanned (Exim 4.43) id 1EcsBl-0002Yf-IE for emacs-devel@gnu.org; Thu, 17 Nov 2005 17:25:05 -0500 Original-Received: from exim by lists.gnu.org with spam-scanned (Exim 4.43) id 1EcsBk-0002YS-5I for emacs-devel@gnu.org; Thu, 17 Nov 2005 17:25:04 -0500 Original-Received: from [199.232.76.173] (helo=monty-python.gnu.org) by lists.gnu.org with esmtp (Exim 4.43) id 1EcsBj-0002YP-Sl for emacs-devel@gnu.org; Thu, 17 Nov 2005 17:25:04 -0500 Original-Received: from [193.149.49.134] (helo=acm.acm) by monty-python.gnu.org with esmtp (Exim 4.34) id 1EcsBi-0004mS-M5 for emacs-devel@gnu.org; Thu, 17 Nov 2005 17:25:03 -0500 Original-Received: from localhost (root@localhost) by acm.acm (8.8.8/8.8.8) with SMTP id WAA00375 for ; Thu, 17 Nov 2005 22:29:41 GMT X-Sender: root@acm.acm Original-To: emacs-devel@gnu.org X-BeenThere: emacs-devel@gnu.org X-Mailman-Version: 2.1.5 Precedence: list List-Id: "Emacs development discussions." List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Original-Sender: emacs-devel-bounces+ged-emacs-devel=m.gmane.org@gnu.org Errors-To: emacs-devel-bounces+ged-emacs-devel=m.gmane.org@gnu.org Xref: news.gmane.org gmane.emacs.devel:46179 Archived-At: Hi, Emacs! I've just spent ~ 2 hours trying to figure out from the elisp manual the various ways of binding the key sequence "control-C control-backspace". This is written in such an abstruse and unclear way in the elisp manual (page "Changing Key Bindings") that it's probably easier to try every vaguely plausible combination than to try to figure it out from the manual. In fact, I figured out "[?\C-c \C-backspace]" by just such experimentation. Trouble is, this is rejected by XEmacs, and I want the specification to be portable. So I would like a list of all the ways Emacs can do it, so that I can try them one by one in XEmacs. Surely, surely, surely, there should be a clear description of these things in the elisp manual? For a start, why is there not a "@section Specifying Key Sequences" under the @chapter "Keymaps"? I arrive at "Keymaps", look at the menu, and try to guess which section describes key sequences. "Changing Key Bindings" looks to be the only candidate. I go into "Changing Key Bindings". How to specify a key sequence is all jumbled up with the functions to do this. Nowhere does it say "you can specify a keysequence with a string". No, it kicks off with "In writing the key sequence to rebind, it is good to use the special escape sequences for control and meta characters". Is it plainly obvious that you can use a string, and the place where the string is described is "Character Type", and that Ctrl, Meta, etc. are actually parts of characters, rather than being control actions attached to them somehow? If it is so obvious then I'm too stupid to be writing Emacs Lisp, because it's anything but obvious to me. Nowhere does it say "you can specify a keysequence with a vector". No, its first mention of a vector is "You can also use this escape syntax in vectors, as well as others that aren't allowed in strings; one example is `[?\C-\H-x home]'". So on encountering this, I immediately start searching for the place which DOES say "you can ... with a vector", and come back to the current page 20 minutes later in a rage, because it's specified nowhere. Where is the list of symbols like `home' that one can use in vectors? Would it be too much to expect them either to be listed, or to have an @xref to the page where they are listed? I am confused as to whether "backspace" is called "backspace", "del", "BS", "delete", and whether it has to be in lower case, upper case, or it doesn't matter. Again, what I would like to see is a "@section Specifying Key Sequences", whose meat would look like something like this: ######################################################################### @cindex Key Sequences You can specify Key Sequences in any of the following ways: @table @bullet @item A string ......., for example @code{"\C-x5\C-g"}. You can't specify control or function keys in a string. Use a vector or ..... for this. @item A vector ....... To apply modifiers to keys, ....... For a complete list of named keys, @ref{....}. For example @code{[C-S-up]}. @item The @code{kbd} function ...... @item Mouse clicks ...... @item ........ ....... @item ........ ....... @end table Normally, we recommend you to use ........, but when ...., .... is easier. ######################################################################### I don't have a sufficient overview of key binding to flesh out this text myself. Yours in frustration, -- Alan Mackenzie (Munich, Germany)