Note: This is a beta release of Red Hat Bugzilla 5.0. The data contained within is a snapshot of the live data so any changes you make will not be reflected in the production Bugzilla. Also email is disabled so feel free to test any aspect of the site that you want. File any problems you find or give feedback here.
Bug 131647 - Usage of <screen> needs clarification
Summary: Usage of <screen> needs clarification
Alias: None
Product: Fedora Documentation
Classification: Fedora
Component: docs-requests
Version: devel
Hardware: All
OS: Linux
Target Milestone: ---
Assignee: Tammy Fox
QA Contact: Tammy Fox
Depends On:
Blocks: fdp-docguide-traqr
TreeView+ depends on / blocked
Reported: 2004-09-02 20:27 UTC by Paul W. Frields
Modified: 2009-07-07 04:08 UTC (History)
2 users (show)

Fixed In Version:
Doc Type: Enhancement
Doc Text:
Clone Of:
Last Closed: 2004-09-13 02:23:46 UTC

Attachments (Terms of Use)
Patch to clarify usage of screen tags (deleted)
2004-09-02 20:39 UTC, Paul W. Frields
no flags Details | Diff

Description Paul W. Frields 2004-09-02 20:27:28 UTC
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.

Comment 1 Paul W. Frields 2004-09-02 20:39:12 UTC
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:


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.

Comment 2 Paul W. Frields 2004-09-02 20:49:52 UTC
Whoopsie, WRT that last bit, instead of:


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


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

Comment 3 Karsten Wade 2004-09-03 20:41:52 UTC
[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.

Small typo on line 186 of the patch:


Otherwise, the entire write-up looks great!

Comment 4 Paul W. Frields 2004-09-03 21:09:30 UTC
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. ;-)

Comment 5 Paul W. Frields 2004-09-03 22:19:12 UTC
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?

Comment 6 Tammy Fox 2004-09-07 14:20:41 UTC
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.

Comment 7 Tammy Fox 2004-09-13 02:23:46 UTC
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

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.

Comment 8 2009-07-07 04:08:38 UTC
Ticket moved to allow products to be removed from BZ.

Note You need to log in before you can comment on or make changes to this bug.