Bug 131647

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 &lt; and &gt; need to be authored as &amp;lt; and &amp;gt; to
correctly carry into the output which shows what the author should be typing.

Whoopsie, WRT that last bit, instead of:

  <foobar> 

It would have been less confusing if I had used the more conventional:

  <command>&lt;foobar&gt;</command>

Maybe the bug owner can fix that part for me. Thanks!

[snip ...]
When using the <command>&lt;screen&gt;</command> tag, you must set
everything within that screen, including the
<command>&lt;screen&gt;</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.