Re: Writing tip: the oft-forgotten <prompt> tag

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