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

[Eli Zaretskii]

> Date: Mon, 28 Apr 2014 08:25:46 -0700 (PDT)
> From: Drew Adams <drew.adams@oracle.com>
> Cc: 17362@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.