10:59 a.m.
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
5:51 p.m.
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>
?
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
On 17 Sep 2014, at 1:55 am, Petr Bokoc <pbokoc(a)redhat.com>
wrote:
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(a)lists.fedoraproject.org
To unsubscribe:
https://admin.fedoraproject.org/mailman/listinfo/docs
10:04 a.m.
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
On 17 Sep 2014, at 1:55 am, Petr Bokoc <pbokoc(a)redhat.com
<mailto:pbokoc@redhat.com>> wrote:
> 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(a)lists.fedoraproject.org <mailto:docs@lists.fedoraproject.org>
> To unsubscribe:
> https://admin.fedoraproject.org/mailman/listinfo/docs
1:30 p.m.
On Tue, Sep 16, 2014 at 6:51 PM, Laura Bailey <lbailey(a)redhat.com> wrote:
What are the benefits of tagging like this, rather than something
like:
<screen># yum install foo</screen>
Just off the top of my head, the one thing that comes to mind is that we
can choose to style the prompt differently, so that the end user knows that
they don't have to type the # or $. Say, put it in a different color, or
something like that.
--
Jared Smith
3510
days inactive
3511
days old
3 comments
3 participants
participants (3)
-
Jared K. Smith -
Laura Bailey -
Petr Bokoc