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
