From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.org!not-for-mail From: Eli Zaretskii Newsgroups: gmane.emacs.bugs Subject: bug#17362: 24.4.50; inconsistent key notation: `ESC' vs `' Date: Tue, 29 Apr 2014 18:17:28 +0300 Message-ID: <83fvkwmagn.fsf@gnu.org> References: <47b1a857-a5d6-4e5a-b8f6-f96f9e201c89@default> Reply-To: Eli Zaretskii NNTP-Posting-Host: plane.gmane.org X-Trace: ger.gmane.org 1398784706 21739 80.91.229.3 (29 Apr 2014 15:18:26 GMT) X-Complaints-To: usenet@ger.gmane.org NNTP-Posting-Date: Tue, 29 Apr 2014 15:18:26 +0000 (UTC) Cc: 17362-done@debbugs.gnu.org To: Drew Adams Original-X-From: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane.org@gnu.org Tue Apr 29 17:18:20 2014 Return-path: Envelope-to: geb-bug-gnu-emacs@m.gmane.org Original-Received: from lists.gnu.org ([208.118.235.17]) by plane.gmane.org with esmtp (Exim 4.69) (envelope-from ) id 1Wf9nX-0008GM-P5 for geb-bug-gnu-emacs@m.gmane.org; Tue, 29 Apr 2014 17:18:19 +0200 Original-Received: from localhost ([::1]:50601 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1Wf9nX-0007Dk-8z for geb-bug-gnu-emacs@m.gmane.org; Tue, 29 Apr 2014 11:18:19 -0400 Original-Received: from eggs.gnu.org ([2001:4830:134:3::10]:42982) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1Wf9nN-0006zn-CX for bug-gnu-emacs@gnu.org; Tue, 29 Apr 2014 11:18:14 -0400 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1Wf9nH-00080P-EY for bug-gnu-emacs@gnu.org; Tue, 29 Apr 2014 11:18:09 -0400 Original-Received: from debbugs.gnu.org ([140.186.70.43]:56093) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1Wf9nH-00080K-AV for bug-gnu-emacs@gnu.org; Tue, 29 Apr 2014 11:18:03 -0400 Original-Received: from Debian-debbugs by debbugs.gnu.org with local (Exim 4.80) (envelope-from ) id 1Wf9nG-0004bF-JA for bug-gnu-emacs@gnu.org; Tue, 29 Apr 2014 11:18:02 -0400 Resent-From: Eli Zaretskii Original-Sender: "Debbugs-submit" Resent-To: bug-gnu-emacs@gnu.org Resent-Date: Tue, 29 Apr 2014 15:18:01 +0000 Resent-Message-ID: Resent-Sender: help-debbugs@gnu.org X-GNU-PR-Message: cc-closed 17362 X-GNU-PR-Package: emacs X-GNU-PR-Keywords: Mail-Followup-To: 17362@debbugs.gnu.org, eliz@gnu.org, drew.adams@oracle.com Original-Received: via spool by 17362-done@debbugs.gnu.org id=D17362.139878465017619 (code D ref 17362); Tue, 29 Apr 2014 15:18:01 +0000 Original-Received: (at 17362-done) by debbugs.gnu.org; 29 Apr 2014 15:17:30 +0000 Original-Received: from localhost ([127.0.0.1]:45210 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.80) (envelope-from ) id 1Wf9mj-0004a6-NC for submit@debbugs.gnu.org; Tue, 29 Apr 2014 11:17:30 -0400 Original-Received: from mtaout22.012.net.il ([80.179.55.172]:61589) by debbugs.gnu.org with esmtp (Exim 4.80) (envelope-from ) id 1Wf9mh-0004Zn-P5 for 17362-done@debbugs.gnu.org; Tue, 29 Apr 2014 11:17:28 -0400 Original-Received: from conversion-daemon.a-mtaout22.012.net.il by a-mtaout22.012.net.il (HyperSendmail v2007.08) id <0N4S00L00SP0TC00@a-mtaout22.012.net.il> for 17362-done@debbugs.gnu.org; Tue, 29 Apr 2014 18:17:20 +0300 (IDT) Original-Received: from HOME-C4E4A596F7 ([87.69.4.28]) by a-mtaout22.012.net.il (HyperSendmail v2007.08) with ESMTPA id <0N4S00LCST4WT420@a-mtaout22.012.net.il>; Tue, 29 Apr 2014 18:17:20 +0300 (IDT) In-reply-to: X-012-Sender: halo1@inter.net.il X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.15 Precedence: list X-detected-operating-system: by eggs.gnu.org: GNU/Linux 3.x X-Received-From: 140.186.70.43 X-BeenThere: bug-gnu-emacs@gnu.org List-Id: "Bug reports for GNU Emacs, the Swiss army knife of text editors" List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane.org@gnu.org Original-Sender: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane.org@gnu.org Xref: news.gmane.org gmane.emacs.bugs:88430 Archived-At: > Date: Mon, 28 Apr 2014 08:25:46 -0700 (PDT) > From: Drew Adams > Cc: 17362@debbugs.gnu.org > > > > Emacs manual: contrast node `Menu Bar' with node `Quitting'. The former > > > writes `ESC ESC ESC'; the latter writes ` '. > > > > > > IMO, the former is preferable. (Note that (kbd "ESC") and (kbd "") > > > both act the same, however.) > > > > I'd also prefer "ESC" over "" but then other strings like > > "", "", "" or "" should also be changed > > accordingly. > > Yes, FWIW, IMO they should be. But this bug will be fixed if things are > made consistent either way. I made it consistent in the way described below. > Oh, and BTW there are also inconsistencies for those others, including in > nodes: `CUA Bindings', `Misc File Ops', `File Conveniences', `Filesets', > `Speedbar', `Bidirectional Editing', `Other C Commands', `Image Dired', > `Printing Package', `MS-DOS Printing', `Help Mode', `Rectangles', `Special > Isearch', `Regexp Search', `Keyboard Macro Step-Edit', `Marks vs Flags', > `Counting Days', `General Calendar', `HTML Mode', `Windows Keyboard'. Did this as well. > [A related bug?: `' in nodes `Hungry Delete', `MS-DOS Keyboard', > and `Glossary'. Is `' what is meant here? Likewise, you can > find occurrences of `' instead of `'.] And this. Most of the places where I found a need to change the manual, I decided that using @key (which produces "" in Info) was TRT. I know that Drew and Dani don't like this, but this is how Texinfo manuals in general and the Emacs manual in particular are written since day one. My changes are committed as emacs-24 branch revisions 117028 and 117032. For the record, here are the guidelines I used to fix this stuff consistently (if there's a good place to document that, please point it out): . Use @key whenever keyboard input references a key whose label or name is longer than 1 characters, like "TAB" or "Delete". This is to avoid confusion between pressing a single key and literally typing "T A B" (3 keys) or "D e l e t e" (6 keys). . In all other cases, keyboard input typed by the user should be in @kbd. When a key sequence includes both kinds of input, use @kbd on the outside and @key inside, as in @kbd{M-x foo @key{RET}}. (It is harmless to say @kbd{@key{RET}}, but in that case @kbd is redundant, as it doesn't have any useful effect. . Key names inside @key should be capitalized as follows: - If a key has a label, its name should follow the usual capitalization of the label, as in @key{Alt} or @key{PageUp}. - If a key does not have a label, its name should be in all caps, as in @key{TAB} or @key{META}. - There are 2 exceptions to the last 2 rules, both for historical reasons: * @key{BACKSPACE}, although many keyboards have a "Backspace" label on it. * @key{ESC}, which is labeled "Esc". . When the text talks about control characters, such as ^L or ^J, do _not_ use @key (as in @key{Ctrl-L}), to avoid confusing them with keystrokes. Instead, use @samp.