screenshot instructions

[Karsten Wade]

On Wed, 2004-09-01 at 00:09, Dashamir Hoxha wrote:
> On Tuesday 31 August 2004 06:46 pm, Tammy Fox wrote:
> > The instructions for taking screenshots has been posted:
> > http://fedora.redhat.com/participate/documentation-guide/s1-screenshots.htm
> 
> > Omit the username and machine information, and separate 
> > what the user types  from sample command output. Also, 
> > in screen tags, what the user types should be in userinput tags, 
> > and what the user is shown as output should be in computeroutput
> > tags.
> 
> 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.

Both of these are correct, but the second one is just so much easier to
manage:

<classname>com.redhat.BigObject</classname>.<methodname>ObjectGrabber</methodname>.<function>grab()</function>

<classname>com.redhat.BigObject.ObjectGrabber.grab()</classname>

> * The text inputed by the users, other that commands, e.g. in
>   interactive programs, is placed inside a <userinput> element.
> 
> What do you think? Does it become too complicated?

I would drop the addition of <prompt> and <command>, which essentially
leaves us at the same place. :(  And we need to settle the matter of
indenting tags.

Tough consensus to reach, apparently.  So much of this is up to style
and represents various levels of "correct".

- Karsten
-- 
Karsten Wade, RHCE, Tech Writer
a lemon is just a melon in disguise
http://people.redhat.com/kwade/
gpg fingerprint: 2680 DBFD D968 3141 0115  5F1B D992 0E06 AD0E 0C41