screenshot instructions
Karsten Wade
kwade at redhat.com
Wed Sep 1 10:58:45 UTC 2004
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
More information about the fedora-docs-list
mailing list