Re: Emacs manual: correct @code to @kbd

[Stephen J. Turnbull]

Aaron S. Hawley writes:
 > On Mon, Jun 8, 2009 at 11:01 PM, Eli Zaretskii<address@hidden> wrote:
 > >
 > > However, some of your corrections are wrong.  For example, this:
 > >
 > >> --- doc/emacs/custom.texi     4 Jun 2009 03:13:28 -0000       1.22
 > >> +++ doc/emacs/custom.texi     8 Jun 2009 18:49:57 -0000
 > >> @@ -1706,7 +1706,7 @@
 > >> address@hidden example
 > >>
 > >>    When the key sequence includes function keys or mouse button events,
 > >> -or address@hidden characters such as @code{C-=} or @code{H-a},
 > >> +or address@hidden characters such as @kbd{C-=} or @kbd{H-a},
 > >
 > > Since this talks about _characters_, not keystrokes, @kdb is
 > > inappropriate here, I think.
 > 
 > Maybe, but the @code isn't appropriate since neither characters nor
 > "key sequence" are source code.

This is the old discussion (cf. http://www.jwz.org/doc/lemacs.html,
ignore the politics and focus on the discussion of how the Lemacs
event model broke "calc" between Jamie and Dave Gillespie) of whether
input characters are characters or events.  Emacs takes the position
that they are characters and encodes non-character events differently.

My personal take is that @kbd means "console input", and the spelling
is a legacy of the time when console input was restricted to typing on
the keyboard.  Cf. the usage of "key sequence" above.  @kbd then may
be used to mark any literal keystroke (including chords).  There's a
special convention that keystrokes that resolve to characters may be
replaced by the characters in order to make documentation shorter and
more readable.

So I like @kbd above.  The word "characters" is wrong.  Actually it's
probably an abbreviation of "keyboard input that corresponds to
non-ASCII characters", but that's still wrong in a Unicode world,
`C-=' and `H-a' are not characters.  (Granted, in Emacs Lisp
characters and integers are the same type in the implementation, but
you do have `char-int-p'.)