GNU bug report logs - #17362
24.4.50; inconsistent key notation: `ESC' vs `<ESC>'

Previous Next

Full log

View this message in rfc822 format

From: help-debbugs <at> gnu.org (GNU bug Tracking System)
To: Drew Adams <drew.adams <at> oracle.com>
Subject: bug#17362: closed (Re: bug#17362: 24.4.50; inconsistent key
 notation: `ESC' vs `<ESC>')
Date: Tue, 29 Apr 2014 15:18:03 +0000

[Message part 1 (text/plain, inline)]

Your bug report

#17362: 24.4.50; inconsistent key notation: `ESC' vs `<ESC>'

which was filed against the emacs package, has been closed.

The explanation is attached below, along with your original report.
If you require more details, please reply to 17362 <at> debbugs.gnu.org.

-- 
17362: http://debbugs.gnu.org/cgi/bugreport.cgi?bug=17362
GNU Bug Tracking System
Contact help-debbugs <at> gnu.org with problems

[Message part 2 (message/rfc822, inline)]

From: Eli Zaretskii <eliz <at> gnu.org>
To: Drew Adams <drew.adams <at> oracle.com>
Cc: 17362-done <at> debbugs.gnu.org, dmoncayo <at> gmail.com
Subject: Re: bug#17362: 24.4.50; inconsistent key notation: `ESC' vs `<ESC>'
Date: Tue, 29 Apr 2014 18:17:28 +0300

> Date: Mon, 28 Apr 2014 08:25:46 -0700 (PDT)
> From: Drew Adams <drew.adams <at> oracle.com>
> Cc: 17362 <at> debbugs.gnu.org
> 
> > > Emacs manual: contrast node `Menu Bar' with node `Quitting'.  The former
> > > writes `ESC ESC ESC'; the latter writes `<ESC> <ESC> <ESC>'.
> > >
> > > IMO, the former is preferable.  (Note that (kbd "ESC") and (kbd "<ESC>")
> > > both act the same, however.)
> > 
> > I'd also prefer "ESC" over "<ESC>" but then other strings like
> > "<TAB>", "<SPC>", "<RET>" or "<DEL>" 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?: `<DELETE>' in nodes `Hungry Delete', `MS-DOS Keyboard',
> and `Glossary'.  Is `<delete>' what is meant here?  Likewise, you can
> find occurrences of `<BACKSPACE>' instead of `<backspace>'.]

And this.

Most of the places where I found a need to change the manual, I
decided that using @key (which produces "<FOO>" 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.

[Message part 3 (message/rfc822, inline)]

From: Drew Adams <drew.adams <at> oracle.com>
To: bug-gnu-emacs <at> gnu.org
Subject: 24.4.50; inconsistent key notation: `ESC' vs `<ESC>'
Date: Mon, 28 Apr 2014 07:29:34 -0700 (PDT)

Emacs manual: contrast node `Menu Bar' with node `Quitting'.  The former
writes `ESC ESC ESC'; the latter writes `<ESC> <ESC> <ESC>'.

IMO, the former is preferable.  (Note that (kbd "ESC") and (kbd "<ESC>")
both act the same, however.)



In GNU Emacs 24.4.50.1 (i686-pc-mingw32)
 of 2014-04-21 on ODIEONE
Bzr revision: 117005 dancol <at> dancol.org-20140421180019-po4wdeg7gqvvlh5d
Windowing system distributor `Microsoft Corp.', version 6.1.7601
Configured using:
 `configure --prefix=/c/Devel/emacs/snapshot/trunk
 --enable-checking=yes,glyphs 'CFLAGS=-O0 -g3'
 LDFLAGS=-Lc:/Devel/emacs/lib 'CPPFLAGS=-DGC_MCHECK=1
 -Ic:/Devel/emacs/include''

Previous Next

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