Bug 131160 (fdp-docguide-traqr)

Created attachment 103196 [details]
new section on screenshots, XML formatting fixes, container for another section

This patch has three elements:

1. Fixes some minor indenting issues in some sections.
2. Adds in a new section covering text and graphic screenshots.
3. Adds in a container section for diagrams and other images

Created attachment 103198 [details]
Minor edits, additive to previous patch

I did the technical checking on the GIMP procedures, and some minor editing,
including:
- adding a little more info about resetting theme and fonts to Bluecurve (I
checked this against a brand new user account on my system)
- inserted bit about exporting image in GIMP when making EPS
- making note about not doubling up on screenshots unless warranted
- used <userinput> and <computeroutput> in textual screenshot

It might be worth noting here that authors/editors can get away with not
resetting their own themes if they simply do what I did, which is to create a
new user for testing and screenshot purposes. Just a thought.

Two edits: 

1. "GIMP" should be "The GIMP" in application tags. 

2. "It will be useful to provide textual screen information for..."
does not need to be in future tense" It is useful to provide..."

From a style point of view, I prefer to separate commands from the
sample command outputs. Refer to my explanation in bug #128903.

Also, I intended for the "The Layout of a Tutorial" chapter to be
short and sweet -- explain the DocBook XML layout specific to the
Fedora docs such as including common files. I would prefer to create a
"Writing Style" chapter and move the screenshot instructions into a
section for it. We also need to include an xref to these instructions
at the end of the "figure" section under "DocBook XML Tags."

1. I didn't catch "The GIMP," thanks. I'll also keep this in mind for
any of my work.

2. I patched this with "Textual screen information is also useful for
readers," q.v. attachment id=103198.

I have the ticket for the style guide, which seems like it will work
better (and go to press faster) as a chapter of easy-to-remember
guidelines. There's probably enough for a whole guide, but it might be
worth sacrificing comprehensiveness to make an earlier release that
authors can use right away.

In the end, I decided to add this information at the end of the "Red
Hat Documentation Guidelines" chapter. When we have more sections on
style issues we can pull them out to a new chapter or spin off a
separate Style Guide.

Since no one objected, I also changed the Text Screenshot example to
show separating the command and example output.

The new section will appear on the website within the hour.

*** Bug 155787 has been marked as a duplicate of this bug. ***

CVS anonymous check-out information still refers to fedora-docs, rather than 
docs or docs-common

ie. cvs -z3 co fedora-docs - should be cvs -z3 co docs or docs-common

Bug is found in Chapter 1. Getting the Files

The newest version of the Documentation Guide hasn't made it to f.r.c, so I've
asked Tammy or Karsten to republish.  The guide in CVS has the latest info in it
-- not that it would help in this case! :-)  Thanks Andrew.  BTW, the note below
is not intended as a rebuke, just makes sense to let people know.

* * * * *
NOTE TO USERS:
Please don't enter any more new bug information directly into this tracker. 
Instead, enter a new bug using product "Fedora Documentation," component
"documentation-guide."  We can then make the new bug block this bug (if
required) to make tracking easier.
* * * * *

I don't think we are using this bug tracker anymore, so I'm closing it out. Feel
free to reopen if we need it.