Re: DOCBOOK: marking up keycaps according to their semantics

[Bob Stayton <bobs@sco.com>]

Let me see if I understand you.  You are suggesting that
the DTD be changed so that keycap can have a way of
identifying certain keys that have functions that go
beyond entering a character.  You want to capture the
semantic concept of a Ctrl key, so that it can be expressed
by the stylesheets in many ways rather than as a literal
key name, right? So for Emacs doc, a stylesheet would
render it as "C", while another stylesheet would
say "Ctrl". In other languages it could be
translated by the gentext files.

This would seem to apply to just a few keys, like
Alt, Esc, Shift, and Ctrl at least.  Maybe Enter as well?
Or should it be for all the named keys, including Insert,
Home, etc.?

Were you thinking of an enumerated list of values
for an attribute on keycap?

Bob Stayton                                 400 Encinal Street
Publications Architect                      Santa Cruz, CA  95060
Technical Publications                      voice: (831) 427-7796
The SCO Group                               fax:   (831) 429-1887
                                            email: bobs@sco.com

On Sun, Mar 02, 2003 at 09:30:45PM +0100, Tobias Reif wrote:
> 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/
> 

-- 

Bob Stayton                                 400 Encinal Street
Publications Architect                      Santa Cruz, CA  95060
Technical Publications                      voice: (831) 427-7796
The SCO Group                               fax:   (831) 429-1887
                                            email: bobs@sco.com