On Wed, 2004-09-01 at 06:58, Karsten Wade wrote: > > I would suggest something like this: > > > > * Everything inside a <screen> tag is assumed by default as > > computeroutput, unless otherwise stated. > > Do you mean by "assumed by default as computeroutput" to mean, whenever > you use a <screen/> block, you will be surrounding a <computeroutput/> > block unless otherwise stated? > > This is how it stands right now, aiui. > > > * The prompt should be denoted like this: <prompt>bash#</prompt> > > or <prompt>bash$</prompt> (depending on whether it is the root > > or any user). > > The current usage is to not include a prompt. Refer to the Note at the > bottom of this page: > > http://fedora.redhat.com/participate/documentation-guide/s1-xml-tags-prompt.html > > Personally, I agree with this from an aesthetic viewpoint. > > Unless the point is to display the prompt for discussion, it is long and > clutters the view, confusing the reader with a big block of text that > may not even describe what they are looking at. > > The document convention we use of having long blocks of input and output > in <screen/> tags is sufficient to clue-in the reader that this is input > or output. > > > * Commands are placed inside a <command> element. > > It seems redundant to put a <command> tag inside of a <userinput> tag > ... yes, it's technically allowed, and yes, I think we should mark up > all text to a fine degree so it is useful for the most types of output, > but there is a point where it is ridiculous. My vote is that: - <Screen> should be used for any interaction with the computer, be it input or output. - <Userinput> should be used inside <screen> for what a user is expected to type. No prompt should be shown. - <Computeroutput> should be used inside <screen> for what the user views, whether it is a response to a command or the contents of a file. - No additional <command>, <filename> or other tags inside <*put> other than <replaceable>, where it applies and would aid comprehension or the text demands it. - The optimal way of differentiating <userinput> from <computeroutput> is to separate the <screen> sections in which they appear with narrative text. Tammy used an example of this in another thread, so the code would look like this. Note that I'm using what I think was Karsten's latest recommendation for formatting in <screen>, i.e. nest the tags instead of stacking, and flush left the actual content only. <para> Run <command>foobar</command> with the following syntax: </para> <screen> <userinput> foobar -v -f myfile </userinput> </screen> <para> You should see the following output: </para> <screen> <computeroutput> Finished processing, run time 0.035s </computeroutput> </screen> This seems flexible enough to me -- easy to write, easy to edit, easy to read and maintain. I think the Documentation Guide itself, in Section 6.22, advocates using a lot of nested tags, more than I think are useful (see Note at bottom of page): http://fedora.redhat.com/participate/documentation-guide/s1-xml-tags-screen.html Once we get some consensus here, we should &BZ; the results to make Sec. 6.22 agree with our decisions (including indentation). By the way, I think the sections on <userinput> and <computeroutput> should have a <xref> to Sec. 6.22 as well to indicate that people don't really need to use them in normal <para> contexts. -- Paul W. Frields, RHCE
