On 09/17/2014 12:51 AM, Laura Bailey
wrote:
Including the prompt (#/$) is useful, but I'm not convinced
tagging it is -- this just seems like extra XML for no real
utility to me. What are the benefits of tagging like this,
rather than something like:
<screen># yum install foo</screen>
?
That's a good point. The <prompt> tag itself doesn't add much
- it just makes me feel better. I'd like everyone contributing to
the Installation Guide to use the tag, but for other guides, I only
care about the prompt itself and I'm fine with leaving the tag/not
tag question up to the guide author(s).
If we could alter the styles so that things marked with
<prompt> were not copied when a user highlighted and
copied commands from the doc to a terminal, that might be
different. :)
Cheers,
Laura Bailey
Senior Technical Writer
Red Hat Customer Content Services BNE
Hi everyone,
We just had a bit of a discussion on IRC and I've been
asked to share this with you all:
The <prompt> tag[1] is awesome, especially in
procedures. When you're telling the reader to run a sequence
of commands, you can prefix each command with the correct
prompt; the user will then know if the command requires root
privileges or not, and you don't have to say "run this as
root" all the time.
For example:
1. Install the foo package:
<screen>
<prompt>#</prompt> <command>yum
install foo</command>
</screen>
2. Make sure the foo package is installed:
<screen>
<prompt>$</prompt> <command>rpm -q
foo</command>
</screen>
This way, the user knows that you need root privileges
for the first command, because it's prefixed with #, and
they don't need to be root for the second one, because the
prompt is $. (However, in some simple procedures explaining
very basic stuff to beginners it's still useful to include a
step that says "Switch to root: $ su -".)
Make sure to put a space between the prompt and the
actual command - otherwise it just looks bad when rendered.
Also make sure to use the prompts *everywhere*, because if
you only use it for commands that need root and omit it for
ones that don't, it ends up being confusing (and looking
bad). And finally, don't use this when you mention a command
inline (in a <para>) - only in <screen> or
<programlisting>.
Please try to keep this in mind when writing. I'm doing
this everywhere in the Installation Guide, and it would be
great if we all did the same.
Cheers,
Petr
[1] http://www.docbook.org/tdg/en/html/prompt.html
--
docs mailing list
docs@xxxxxxxxxxxxxxxxxxxxxxx
To unsubscribe:
https://admin.fedoraproject.org/mailman/listinfo/docs
|
--
docs mailing list
docs@xxxxxxxxxxxxxxxxxxxxxxx
To unsubscribe:
https://admin.fedoraproject.org/mailman/listinfo/docs
