taking screenshots - new section for Documentation Guide (was installation guide)

[Karsten Wade]

(note message id intentionally broke to start new thread)

On Fri, 2004-08-27 at 16:33, Karsten Wade wrote:

> For expediency, I'm prepared to just submit the patch to the Doc Guide,
> rolling in some other dangling issues I can include.  Tammy would see
> the CVS report and can address any mistakes and expand/modify.

Darn that cowboy mentality!

For those who chomp at the bit, you can see that I am the same myself.  
The above is a perfect example.  Even I get impatient at process, though
I recognize we need it more than I need to feel comfortable.

1. I don't own the document, although Tammy said I could do some minor
bugfixes and commit them to CVS.  What I just wrote is a whole new
<section> not a minor fix, so that requires a new bug for tracking work
on the Documentation Guide:

https://bugzilla.redhat.com/bugzilla/show_bug.cgi?id=131160

with an attachment of a diff against current CVS and then ....

2. An editor to look it over, which can be the first person who grabs it
and confirms what I did, and who can then move it on to block bug #
129722 (ready to publish) for Tammy (in her role as a document owner) to
pick up and commit to CVS, then (in the role of website maintainer)
update f.r.c/participate/documentation-guide/.

To make this easier, I have opted to host this as a DRAFT version at the
following URL:

http://people.redhat.com/kwade/patches/fedora-docs/documentation-guide-quaid/documentation-guide-en-quaid/taking-screenshots.html

The editor will want to a) wordsmith, and b) check the technical
details, such as steps and information shown.  Also, a check of the
DocBook XML is in order.

Note thought that I broke rules from the Documentation Guide:

1. I used a meaningful ID for <sect1>, dropping the location and section
specific information.  At this point, the most legitimate debate is
between "similar-to-title" and "s.similar.to.title", the latter being
Norm Walsh's current usage.

2. My <screen> tags themselves are not flush left, although the content
is.  I think that information described on this page:

http://fedora.redhat.com/participate/documentation-guide/s1-xml-tags-screen.html

is a legacy SGML problem.  My builds show that the following:

      <screen>
foo
      </screen>
<screen>
foo
</screen>
      <screen>
foo
      </screen>

renders as:

foo 
foo
	foo
      
Obviously the contents of the <screen/> are highly sensitive to
whitespace issues, and in fact could perhaps be CDATA containers instead
to totally make them ignored by the toolchain.  Either way, I don't
think the <screen> tags need to be flush left, nor the the
<computeroutput/> container.  I'd like to recommend this for a change in
the Documentation Guide, and will file a bugzilla with patch if there is
no technical objection. 

- Karsten, off to see Run Lola Run at http://www.thespoon.com/drivein/
-- 
Karsten Wade, RHCE, Tech Writer
a lemon is just a melon in disguise
http://people.redhat.com/kwade/
gpg fingerprint: 2680 DBFD D968 3141 0115  5F1B D992 0E06 AD0E 0C41