Bug 131647 - Usage of <screen> needs clarification
Usage of <screen> needs clarification
Status: CLOSED CURRENTRELEASE
Product: Fedora Documentation
Classification: Fedora
Component: docs-requests (Show other bugs)
devel
All Linux
medium Severity medium
: ---
: ---
Assigned To: Tammy Fox
Tammy Fox
http://fedora.redhat.com/participate/...
: FutureFeature
Depends On:
Blocks: fdp-docguide-traqr
  Show dependency treegraph
 
Reported: 2004-09-02 16:27 EDT by Paul W. Frields
Modified: 2009-07-07 00:08 EDT (History)
2 users (show)

See Also:
Fixed In Version:
Doc Type: Enhancement
Doc Text:
Story Points: ---
Clone Of:
Environment:
Last Closed: 2004-09-12 22:23:46 EDT
Type: ---
Regression: ---
Mount Type: ---
Documentation: ---
CRM:
Verified Versions:
Category: ---
oVirt Team: ---
RHEL 7.3 requirements from Atomic Host:
Cloudforms Team: ---


Attachments (Terms of Use)
Patch to clarify usage of screen tags (7.17 KB, patch)
2004-09-02 16:39 EDT, Paul W. Frields
no flags Details | Diff

  None (edit)
Description Paul W. Frields 2004-09-02 16:27:28 EDT
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 16:39:12 EDT
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.
Comment 2 Paul W. Frields 2004-09-02 16:49:52 EDT
Whoopsie, WRT that last bit, instead of:

  &amp;lt;foobar&amp;gt; 

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!
Comment 3 Karsten Wade 2004-09-03 16:41:52 EDT
[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!
Comment 4 Paul W. Frields 2004-09-03 17:09:30 EDT
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 18:19:12 EDT
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 10:20:41 EDT
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-12 22:23:46 EDT
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.

Comment 8 eric@christensenplace.us 2009-07-07 00:08:38 EDT
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.