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

[Paul W. Frields]

On Fri, 2004-08-27 at 21:34, Karsten Wade wrote:
> (note message id intentionally broke to start new thread)

I probably should have done that, sorry.

[...snip...]
> 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/.

I'll take you up on that, seeing as how I haven't hit the hay quite yet.

> 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.

Honestly, I didn't see much to do with (a). I made a couple of changes
which I thought at the time were good ideas. On the other hand, I'm
getting sleepy.

> 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.

I like using meaningful ID's; I have moved to using <section> tags, with
"sn-meaningful-title". Modularity, check. Easy to grab all
element-related ID's with a regex, also check. 

> 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. 

I have seen the most problem in the PDF builds, but the HTML builds also
seem to do funny stuff with more vertical space if you don't run your
first and last text against the opening and closing <screen> tags,
respectively. In other words, given these two examples:

<!-- first example -->
<screen>
<computeroutput>
foo
bar
</computeroutput>
</screen>

<!-- second example -->
<screen><computeroutput>foo
bar</computeroutput></screen>

The second example renders into a more pleasing vertical context,
without a lot of wasted space. The PDF, IIRC, was particularly ugly if
you didn't use the second form, but I seem to remember the HTML also was
noticeably different.

I posted an additive patch to Bugzilla for you to take a look at. I feel
a little strange correcting work by someone who does this for a living,
when I'm more of a dilettante. Hope the editing sparks something
positive.

> - Karsten, off to see Run Lola Run at http://www.thespoon.com/drivein/

Very good movie! Not that it's necessarily going to be at a Guerilla
Drive-In, but if you like "Run Lola Run," you should see Tom Tykwer's
film of Krzysztof Kieslowki's "Heaven," if you haven't already. (Sorry
for going OT at the end there. Now I'm going TB as well.)

-- 
Paul W. Frields, RHCE    (*TB = To Bed)