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.
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)
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.
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.
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 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.
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>
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.
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.
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.
I think this product is no longer supported. Is this ticket still needed?
If this bug is still needed please reopen and provide additional information. Thanks.