Bug 128903 - Suggestions for example-tutorial
Suggestions for example-tutorial
Status: CLOSED DEFERRED
Product: Fedora Documentation
Classification: Fedora
Component: example-tutorial (Show other bugs)
devel
All Linux
medium Severity medium
: ---
: ---
Assigned To: Karsten Wade
Tammy Fox
:
Depends On:
Blocks:
  Show dependency treegraph
 
Reported: 2004-07-30 19:27 EDT by Paul W. Frields
Modified: 2009-08-12 12:02 EDT (History)
2 users (show)

See Also:
Fixed In Version:
Doc Type: Bug Fix
Doc Text:
Story Points: ---
Clone Of:
Environment:
Last Closed: 2009-08-12 12:02:13 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 for extra example-tutorial explanations (2.11 KB, patch)
2004-07-30 20:05 EDT, Paul W. Frields
no flags Details | Diff
Patch to add extra examples to example-tutorial (1.82 KB, patch)
2004-08-02 13:52 EDT, Paul W. Frields
no flags Details | Diff
Some more additions and hints, version bump, notes about screen tags (2.77 KB, patch)
2004-08-20 23:57 EDT, Paul W. Frields
no flags Details | Diff

  None (edit)
Description Paul W. Frields 2004-07-30 19:27:49 EDT
Description of problem:
The example-tutorial is missing some additional sections that would be
helpful, as well as entity references re: Karsten Wade's recent e-mail
to the fedora-docs-list (see
http://redhat.com/archives/fedora-docs-list/2004-July/msg00046.html).

Version-Release number of selected component (if applicable):
0.1 (2003-07-07)

How reproducible:
Every time.

Steps to Reproduce:
N/A
  
Actual results:
Tutorial is missing some sections that would make contribution easier
for newcomers.

Expected results:
A slightly larger tutorial with more examples.

Additional info:
Patch will be included next.
Comment 1 Paul W. Frields 2004-07-30 20:05:37 EDT
Created attachment 102330 [details]
Patch for extra example-tutorial explanations

This patch includes examples of:

- Including a middle initial in <author>
- Using <screen>, <userinput>, <computeroutput>, <replaceable> in examples
(should *definitely* be added since usage will be pervasive)
Comment 2 Gregory Leblanc 2004-08-02 13:26:48 EDT
There appears to be a bunch of gratuitious removal of whitespace here,
which may make the document inconsistent.  

The section talking about the use of the <screen> tag uses <command>
markup around two XML tags.  The correct markup for these is
<sgmltag>.  It seems that I had to add the parameter
format="linespecific" to my <screen> tags in order to get output to
work properly, though perhaps that was just a bug in the stylesheets I
was using at the time.
Comment 3 Paul W. Frields 2004-08-02 13:36:36 EDT
The whitespace problem is my fault entirely. I'll fix that. As for the
use of <command>, I was simply following the many examples used in the
current Documentation Guide that Tammy wrote. Maybe she can chime in
here when she accepts this bug, and make a determination. In the
meantime, it's at least consistent with the existing authorities at FDP.
Comment 4 Paul W. Frields 2004-08-02 13:37:56 EDT
Oops, I forgot to add, have you checked out the fedora-docs stuff yet
as written in the Docs Guide? I'm no DocBook/XML expert, but my
understanding is that you should be using the Docs Project official
setup for testing any FDP material for now.
Comment 5 Paul W. Frields 2004-08-02 13:50:42 EDT
Comment on attachment 102330 [details]
Patch for extra example-tutorial explanations

Do not use this patch... I inadvertently removed a bunch of whitespace, as
Gregory pointed out. Next patch fixes the problem.
Comment 6 Paul W. Frields 2004-08-02 13:52:28 EDT
Created attachment 102364 [details]
Patch to add extra examples to example-tutorial

Adds:
- example for putting middle initial in <author> or <editor>
- example for using <screen> in detailing user commands and computer output -
<screen>, <replaceable>, <command>, <userinput>, <computeroutput>
Comment 7 Paul W. Frields 2004-08-20 23:57:52 EDT
Created attachment 102953 [details]
Some more additions and hints, version bump, notes about screen tags

This tag is in addition to attachment 102364 [details], the previous patch.
Comment 8 Tammy Fox 2004-08-30 22:18:03 EDT
I would rather not use command tags within userinput tags. IMO,
userinput tags should be used instead of command tags when used within
an example or screen tags. Does that sound reasonable to you? Perhaps
I should include that in the Style Guide.

Also, from a writing style point of view, I think it is more clear to
separate the command being entered from the sample output. For example:

Enter the following command to find all instances of snmptrap in the
/etc/services file:

grep snmptrap /etc/services

The output appears similar to the following:

snmptrap        162/udp         snmp-trap       # Traps for SNMP

(I left out the XML tags b/c I don't know how Bugzilla handles them.)

Let me know if you agree with these changes.
Comment 9 Paul W. Frields 2004-08-31 08:15:10 EDT
I went a little tag-happy there, I agree! I've realized since posting
that patch back around August 2 that using so many tags is
counter-productive. There's been some discussion lately on the list
about using a CDATA container for this kind of thing; see
<http://www.redhat.com/archives/fedora-docs-list/2004-August/msg00309.html>
and some other following mesages in that thread, for example. Maybe
that is an answer. If we can get it hashed out there, I'll
fix/obsolete this patch.

As for separating the command from the output, I think Karsten had
made a suggestion about this as well, using indentation for the output
to keep it separate from the command. I had suggested a middle ground,
using <userinput> for the typed part and <computeroutput> for the
response. But I think I like yours better because it's completely
clear what's being entered and what's being output.

I think Bugzilla ignores tags, 'cause I think I blindly used them
before and they "just worked." So you should be able to write:

<para>
  Enter the following command to find all instances of snmptrap
  in the /etc/services file:
</para>
<screen>
  <userinput>
    grep snmptrap /etc/services
  </userinput>
</screen>
<para>
  The output appears similar to the following:
</para>
<screen>
  <computeroutput>
    snmptrap     162/udp     snmp-trap     # Traps for SNMP
  </computeroutput>
</screen>

I know this is not all flush-left, but there's been discussion about
that lately as well. I think Karsten, Dave and Mark are of the opinion
that this is a tool problem and not an authoring problem. I'm sure we
could use your input as well; I don't know the ramifications of
changes like this.

In any case, I have no problem with any of your suggestions.
Comment 10 eric@christensenplace.us 2009-08-05 14:18:52 EDT
I think this product is no longer supported.  Is this ticket still needed?
Comment 11 eric@christensenplace.us 2009-08-12 12:02:13 EDT
If this bug is still needed please reopen and provide additional information.  Thanks.

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