Re: rcirc manual

["Robert J. Chassell" <bob@rattlesnake.com>]

   >     @key{TAB} is typeset to show an image of a key on a keyboard.  I
   >     think it is not the right markup in this case, because this manual
   >     does not talk about keys, it talks about typing a TAB.

        Use the `@kbd' command for characters of input to be typed by
        users. ...

        Use the `@key' command for the conventional name for a key on
        a keyboard ...

   Bob, I know what the Texinfo manual says about this issue, I just
   think it's not 100% clear what it means in practice.  For example, you
   could use either @kbd{M-@key{x}} or @kbd{M-x} (since `x' ``describes a
   key by name''), but the Texinfo manual doesn't touch this dilemma.

My keyboard has a key labelled "Tab" but conventionally, its input can
be sent either by pressing that key or by pressing C-i.  So it seems
to be that in the question of the rcirc manual, @kbd{TAB} makes most
sense.

   ... @key is appropriate when talking about keys on the keyboard,
   like in the Emacs manual chapter which explains the
   Backspace/Delete/DEL issue ...

Yes, I agree.

   I think the effect of @key is not what you want; in particular
   @kbd{M-@key{x}} looks ugly.

I just tested the example, @kbd{C-x @key{ESC}}, in Texinfo.  (No one
that I know would write @kbd{M-@key{x}}.  Instead, he or she would
write either @kbd{M-x} or @key{M-x}.)  For @kbd{C-x @key{ESC}}, both
the Info and the DVI outputs look fine to me.  I particularly like
this output since it tells me, perhaps wrongly, that I am supposed to
press the <ESC> key and not C-[.

   ... if the text is something like "press the TAB key", then
   @key{TAB} is the right markup, but if the text says "you can use
   TAB for completion", I'd use @kbd{TAB}.

Yes.  I agree.  Of course, everyone must check lest someone say "press
the TAB key" when he or she really means "you can use TAB ...", but
that is a different issue.

-- 
    Robert J. Chassell                         
    bob@rattlesnake.com                         GnuPG Key ID: 004B4AC8
    http://www.rattlesnake.com                  http://www.teak.cc