Currently section 6.22 of the Documentation Guide sets out guidelines for <screen> which are a bit confusing for new writers and editors. In addition, current usage renders extra vertical whitespace in documents (both HTML and PDF). Recent conversation on fedora-docs-list has clarified usage of inline tags within <screen> to prevent such problems. The guide currently uses examples such as: (Example #1) .----- | <screen> | <computeroutput> | This is what the computer displays when you | follow the instructions. | </computeroutput> | </screen> '----- There's nothing technically "wrong" with Ex. #1, but <screen> is a block element, and all whitespace inside it is significant. Therefore, the linefeeds after <computeroutput> and </computeroutput> will result in extra whitespace before and after the substantial output. In a larger tutorial this can make for a lot more scrolling (or dead trees). Since <computeroutput>, <userinput>, <command>, <replaceable>, and other such tags are inline tags, they should probably appear that way, as they do within <para> tag sets. Currently in the Guide they appear in a nested format both in examples and throughout the actual Guide source. For most usage, using inline tags may be overkill, especially when the context is provided by the outside narrative, as in the following example: (Example #2) .----- | <para> | You should see the following output: | <para> | | <screen> | This is what the computer displays when you | follow the instructions. | </screen> '----- Other styles might be acceptable but we have to be careful with the whitespace issue: (Example #3) .----- | <para> | Change the following line in the configuration file: | </para> | | <screen> | VARNAME1=<userinput>NewValue1</userinput> | VARNAME2=<userinput>NewValue2</userinput> | </screen> '----- The Documentation Guide should state that: (1) Using Example #2 is best when possible; that is, no inline tags are required when the context gives the proper sense to the <screen> section. This will allow authors to spend less time worrying about rendering problems. As long as they flush left, things should generally work out OK. (2) Usage of inline tags is allowable as long as it doesn't get ridiculous. The included examples have been revised to fit the most common usage. We can add more here if desired.
Created attachment 103403 [details] Patch to clarify usage of screen tags I think this agrees with all the current wisdom, especially Karsten's latest summation at: <http://www.redhat.com/archives/fedora-docs-list/2004-September/msg00018.html> I think, by the way, I also fixed the initial example which won't work as displayed. The < and > need to be authored as &lt; and &gt; to correctly carry into the output which shows what the author should be typing.
Whoopsie, WRT that last bit, instead of: &lt;foobar&gt; It would have been less confusing if I had used the more conventional: <command><foobar></command> Maybe the bug owner can fix that part for me. Thanks!
[snip ...] When using the <command><screen></command> tag, you must set everything within that screen, including the <command><screen></command> tags themselves, to flush left. This must be done so that when it is converted to HTML, it will not have extra blank space in front of it inside the gray background. [snip ...] This isn't necessary. With this toolchain, I found that putting the content on the far left worked fine. I thought we established this in the long thread on fedora-docs-list. I agree the content is safest when flush left, to cover all cases. The <screen/> container can safely be indented, as far as my tests have consistently shown. http://people.redhat.com/kwade/fedora-docs/process-docs/xmlto-whitespace-test.html Small typo on line 186 of the patch: GRAHPICAL -> GRAPHICAL Otherwise, the entire write-up looks great!
You're right. I didn't touch that sentence but probably should have. As an aside, I usually flush-left the <screen> just for readability; they make better "landmarks" while I'm thumbing my way through a document, since occasionally one-line contents can look like wrapped lines from a standard paragraph. I'm glad everything else looks good. And I *will* remember to ispell one of these days. ;-)
Whoops, I've just discovered that there *IS* a point to flushing <screen> tags left, but only the final one. Any whitespace before the closing </screen> tag is also rendered in output, meaning you still get blank vertical space *after* the emphasized content. It actually looks even goofier that way, when it's not balanced by extraneous whitespace before the content. Given that it's probably easier for anyone to remember to flush both <screen> and </screen> left, instead of just the latter, I think we should stick with that particular rule as currently written. Do you agree?
I agree. Flushing everything from the beginning screen tag through the end tag makes it easier to read, prevents whitespace, and is easier to remember than just flushing the last one.
I fixed the misspelling Karsten found as well as the following before committing it to CVS and posting version 0.2.5 to the website: 1. You shouldn't have stacked headers -- there needs to be some text between the screen section title and the General Usage section title. Since the other tag explanation sections don't have a General Usage section, I just removed that header to fix the problem and to be consistent. 2. Words in section titles should captialized, not just the first. I fixed this for the Using Inline Tags with screen title. 3. I added a link to the section on the replaceable tag set to show how to use the replaceable tags. 4. I added a note about not including the prompt when showing commands in screen tags. 5. I changed the replaceable example to replaceables in the name of an RPM file instead of the ISBN of a boxed product.
Ticket moved to allow products to be removed from BZ.