OASIS Mailing List ArchivesView the OASIS mailing list archive below
or browse/search using MarkMail.

 


Help: OASIS Mailing Lists Help | MarkMail Help

docbook message

[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]


Subject: DOCBOOK: Re: marking up keycaps according to their semantics


-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA1

/ Tobias Reif <tobiasreif@pinkjuice.com> was heard to say:
| "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>

Uhm, I agree that's not right. This would make more sense:

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

But the truth of the matter is, I'm not sure this information is worth
marking up in this level of detail. I'd probably use something much simpler.

Dave is confusing the ability to do something with the requirement
that one do it that way. But nevermind.

| \KeySeq{\Control{h} \Control{f}}
|
| This (to my mind) a lot easier to read and type. But more importantly,

Yes, but it's not easy to turn that into a structure that can be
manipulated with general purpose tools. Terseness of markup is
explicitly NOT a goal of XML.

| 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.

Yeah, if all you want is macro substitution, all you need is, uhm,
macro substitution.

What if you want to do something more interesting, like test your
source to make sure the quick reference includes all the keyboard
commands actually used. Or make sure that the accessibility guidelines
are met by pairing semantic gestures with the mouse with keyboard
commands. Or any of a thousand other things that would be impossible
with macro substitutions.

| 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.

Well, I think I'd be tempted to recognize <keycap>Ctrl</keycap> and
translate it directly into another language without adding more markup
to make it more "semantic".

                                        Be seeing you,
                                          norm

- -- 
Norman Walsh <ndw@nwalsh.com>      | Everything we love, no doubt, will
http://www.oasis-open.org/docbook/ | pass away, perhaps tomorrow,
Chair, DocBook Technical Committee | perhaps a thousand years hence.
                                   | Neither it nor our love for it is
                                   | any the less valuable for that
                                   | reason.--John Passmore
-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1.0.6 (GNU/Linux)
Comment: Processed by Mailcrypt 3.5.7 <http://mailcrypt.sourceforge.net/>

iD8DBQE+ZS2HOyltUcwYWjsRAtmKAKCip1YrNwzR3kIoKvRkKJEvMbV8+wCfW4ZJ
xNqNIlyZkQLXauVnrjkvuJk=
=YvR6
-----END PGP SIGNATURE-----




[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]