DOCBOOK: marking up keycaps according to their semantics

[Tobias Reif <tobiasreif at pinkjuice dot com>]

Hi

"Pragmatic Programmer" [1] Dave Thomas writes on his blog [2]:

"[...]
Here's how the FAQ recommends you mark up the Emacs key sequence C-h C-f 
(control H, followed by control F, which normally displays help on a 
function).

<keycombo action="seq">
  <keycombo action="simul">
    <keycap>C</keycap>
    <keycap>h</keycap>
  </keycombo>
  <keycombo action="simul">
    <keycap>C</keycap>
    <keycap>f</keycap>
  </keycombo>
</keycombo>

Whoa! Some markup! And at first sight, pretty logical: a keyboard 
combination consisting of a sequence of two simultaneous key presses, 
the first a 'C' and an 'h', the second a 'C' and an 'f'.

Except, this isn't logical markup at all. It is some remarkably verbose 
hybrid. It totally fails to convey the most important fact about the 
keys you press, namely that you are pressing control and h, followed by 
control and f. Instead, it simply encapsulates the Emacs convention of 
showing an uppercase 'C' to mean control.

And why is this bad? Because I want true logical markup. In LaTeX, I'd 
define some macros to let me write

\KeySeq{\Control{h} \Control{f}}

This (to my mind) a lot easier to read and type. But more importantly, 
it gives me the flexibility I need. Perhaps in online documentation I 
want to use the 'C-h' convention. No problem, I just write the macro 
appropriately and every control sequence is documented accordingly. If a 
publication says that their standard for control keys is "^h ^f", then a 
single change to the macro updates the whole document. And if I want to 
use fancy pictures of keys, my macros can do that too.
[...]"

I agree that there should be a way to markup the control key as control key.
If we choose what's printed on the key, then that would be Strg for 
German keyboeards, Ctrl for english ones, etc.
role="control-ley" doesn't cut it either; it would work with one set of 
transformation tools, but not with a different set.

Tobi

[1] http://www.pragmaticprogrammer.com/
[2] http://pragprog.com/pragdave/
[3] http://pragprog.com/pragdave/Bitches/LogicalMarkup.rdoc,v

--
http://www.pinkjuice.com/