-----BEGIN PGP SIGNED MESSAGE----- Hash: SHA1
Hello all,
I've come upon another scenario where I'm unsure what the best tagging practice would be.
In general, if a user is instructed to perform a key combo we use the keycombo and keycap tags:
Press <keycombo> <keycap>Ctrl</keycap> <keycap>Alt</keycap> <keycap>Del</keycap> </keycombo> to initiate a reboot.
or, in the case of a key sequence, something like:
Press <keycap>Esc</keycap>, <keycap>.</keycap> to recall the last argument of the last command in <command>bash</command>
When the user is being asked to type in text, we use userinput:
Enter the text <userinput>I like penguins!</userinput> into text document.
The issue is that we're now marking up documentation that deals with using vi and things are becoming a bit more ambiguous. What about an instruction like:
To save and quit, press :wq while in command mode
Technically, since :wq is a set of keypresses, rather than arbitrary text that the user is entering, it seems that it should be marked up as
<keypress>:</keypress>, <keypress>w</keypress>, <keypress>q</keypress>
...but that is awfully klunky. We've instead been opting for
<userinput>:wq</userinput>
even though that is arguably incorrect.
The FDP docs guide doesn't really address situations like this (multi-key sequences) directly, so is there an informal standard we should know about before settling on one or the other?
- --Brad
Uttered Brad Smith brads@redhat.com, spake thus:
The FDP docs guide doesn't really address situations like this (multi-key sequences) directly, so is there an informal standard we should know about before settling on one or the other?
My rule of thumb is that printable characters are shown as simply a string.
Sequences with non-printing characters are exploded as you demonstrate.
No need to obfusticate the obvious. If you can read it, it's a string; if not it's separate characters.
Now, if you are thinking about chords, such as Ctl-Alt-Del, then you've just seen my rendering ;-)
Cheers
-----BEGIN PGP SIGNED MESSAGE----- Hash: SHA1
Tommy Reynolds wrote:
Uttered Brad Smith brads@redhat.com, spake thus:
The FDP docs guide doesn't really address situations like this (multi-key sequences) directly, so is there an informal standard we should know about before settling on one or the other?
My rule of thumb is that printable characters are shown as simply a string.
You mean without any markup at all? I'm not sure about that. After all, everything else (commands, user input, key combos) are tagged in such a way that they will be visually differentiated from the rest of the text. I think it would look inconsistent if only these instructions were treated as regular text so, for our purposes, I think we definitely need to tag it with something, I'm just unsure what.
Thank you for the input, - --Brad
Uttered Brad Smith brads@redhat.com, spake thus:
I think it would look inconsistent if only these instructions were treated as regular text so, for our purposes, I think we definitely need to tag it with something, I'm just unsure what.
Well, <userinput>:wq</userinput>, of course. <keycode> and <keycap> are not "key strokes", they are silkscreen labels and ROM values.
Just my $0.02e+48 on it.
Cheers
-----BEGIN PGP SIGNED MESSAGE----- Hash: SHA1
Tommy Reynolds wrote:
Uttered Brad Smith brads@redhat.com, spake thus:
I think it would look inconsistent if only these instructions were treated as regular text so, for our purposes, I think we definitely need to tag it with something, I'm just unsure what.
Well, <userinput>:wq</userinput>, of course. <keycode> and <keycap> are not "key strokes", they are silkscreen labels and ROM values.
Just my $0.02e+48 on it.
Cheers
Ok, so a good way of codifying this would be:
For typed-in characters, use <userinput>. Nonprintable characters should be wrapped in <keycap> eg:
Enter: <userinput>Heading 1 <keycap>Tab<keycap> Heading 2 <keycap>Enter</keycap></userinput> into a text document to begin a simple table.
Sounds good. I'll add this to our style guide.
Thanks again for helping clarify this, - --Brad
On Wed, 2005-11-23 at 16:12 -0500, Brad Smith wrote:
Tommy Reynolds wrote:
Uttered Brad Smith brads@redhat.com, spake thus:
I think it would look inconsistent if only these instructions were treated as regular text so, for our purposes, I think we definitely need to tag it with something, I'm just unsure what.
Well, <userinput>:wq</userinput>, of course. <keycode> and <keycap> are not "key strokes", they are silkscreen labels and ROM values.
Ok, so a good way of codifying this would be:
For typed-in characters, use <userinput>. Nonprintable characters should be wrapped in <keycap> eg:
Enter: <userinput>Heading 1 <keycap>Tab<keycap> Heading 2 <keycap>Enter</keycap></userinput> into a text document to begin a simple table.
I'm not sure if I got Tommy's meaning right, but I think what he was getting at didn't have to do with the difference between printable and nonprintable characters, but rather the difference between something the user types and sees echoed on the screen (like ":wq" in the vi example), as opposed to Ctrl+Alt+Del. The former would be a <userinput>, while the latter would be a <keycombo>. At least that's how I took it.
And if that's not what he meant, well, the above is what I think makes sense semantically and procedurally. In Emacs, for example (hush, Tommy) ;-) -- you might turn on a mode by using a combination of these physical actions, like M-x rpm-specfile-mode, which would be:
<keycombo> <keycap>Meta</keycap> <!-- Alt if you only care about non-PCs --> <keycap>x</keycap> </keycombo> <userinput>rpm-specfile-mode</userinput>
Uttered "Paul W. Frields" stickster@gmail.com, spake thus:
I'm not sure if I got Tommy's meaning right, but I think what he was getting at didn't have to do with the difference between printable and nonprintable characters, but rather the difference between something the user types and sees echoed on the screen (like ":wq" in the vi example), as opposed to Ctrl+Alt+Del.
Er, Paul, if you can see the echo: it's printable!
More formally, I would reserve keycaps, et. al., to mark-up "function keys": F1 and friends, as well as Ctl+Alt+Del, including the you-would-never-type-this-character-in-typing-class category that emacs loves so well.
Attend me. It matters not that VI treats ":wq" specially in some instances. What is important is that it's a readable sequence. All VI commands follow the general form of either "<reps><action><destination>" like "4cw" or a logical process like "wq". Massively <keycap>'ing them destroys the semantics. On the other hand, the emacs key binding of "Ctl-C Ctl-F foo \n" is not readable and should be <keycap>'ed because there are two logical "function" keys introducing the sequence. If only emacs had the kind of keyboard it needed, there would be a special function key whose labels was "Funky Emacs Function".
See the difference? A key or keys treated as a virtual function key should be <keycap>'ed; anything else is just <userinput>. Reserve the <keycap> family to convey the notion of a function key.
And it just so happens that most logical function key combos are non-printing...
That any better?
On Wed, 2005-11-23 at 19:30 -0600, Tommy Reynolds wrote:
Uttered "Paul W. Frields" stickster@gmail.com, spake thus:
I'm not sure if I got Tommy's meaning right, but I think what he was getting at didn't have to do with the difference between printable and nonprintable characters, but rather the difference between something the user types and sees echoed on the screen (like ":wq" in the vi example), as opposed to Ctrl+Alt+Del.
Er, Paul, if you can see the echo: it's printable!
Ah, but in Emacs the special function keys *are* echoed to the screen. Which, now that I think about it, makes the explanation below a better fit with how I think the markup should go.
More formally, I would reserve keycaps, et. al., to mark-up "function keys": F1 and friends, as well as Ctl+Alt+Del, including the you-would-never-type-this-character-in-typing-class category that emacs loves so well.
Attend me. It matters not that VI treats ":wq" specially in some instances. What is important is that it's a readable sequence. All VI commands follow the general form of either "<reps><action><destination>" like "4cw" or a logical process like "wq". Massively <keycap>'ing them destroys the semantics. On the other hand, the emacs key binding of "Ctl-C Ctl-F foo \n" is not readable and should be <keycap>'ed because there are two logical "function" keys introducing the sequence. If only emacs had the kind of keyboard it needed, there would be a special function key whose labels was "Funky Emacs Function".
I'll nobly resist rising to your baiting remarks, sir! ;-D
See the difference? A key or keys treated as a virtual function key should be <keycap>'ed; anything else is just <userinput>. Reserve the <keycap> family to convey the notion of a function key.
And it just so happens that most logical function key combos are non-printing...
That any better?
I think you better said the thing that I meant, so yes!
docs@lists.stg.fedoraproject.org
-
Brad Smith -
Paul W. Frields -
Tommy Reynolds