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

[Karsten Wade]

On Fri, 2004-08-27 at 21:47, Paul W. Frields wrote:
> On Fri, 2004-08-27 at 21:34, Karsten Wade wrote:

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

Okay, so the proposals for new ID generation rules are:

1. "similar-to-title"
2. "s.similar.to.title"
3. "sn-similar-to-title"

I combined "meaningful" and "similar to" under the idea that an ID
should closely match the title and have the same meaning as title, but
not necessarily be the same length as the title (which could be very
long).

> 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 can't get anything to build PDF right now to test this, but in HTML I
see the same thing as output, so am not sure of the advantage of the
different way you suggest it.

I do notice that doing sgml-fill-paragraph will make them line up like:

<screen><computeroutput>foo bar</computeroutput></screen>

Then introducing the line break gets the functionality you mention.

Ultimately, I think we will want to drop the redundant <computeroutput>
and use a CDATA container instead.  In that case, _all_ whitespace will
be considered for certain.  All content will need to use the left margin
of the XML as starting point for indention.

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

I'll look today.

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

I'll suggest it; I've seen RLR before, it was a cool experience.  I may
throw up some paras about it on blogs.redhat.com/people.

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