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
