screenshot instructions

[Paul W. Frields]

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