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

[Karsten Wade]

On Mon, 2004-08-30 at 18:41, Tammy Fox wrote:
> On Mon, 2004-08-30 at 17:40, Karsten Wade wrote:
> > On Sat, 2004-08-28 at 05:25, Paul W. Frields wrote:
> > > On Sat, 2004-08-28 at 06:30, Dave Pawson wrote:
> > > > What processing tools Paul?
> > > >   And why is computeroutput necessary within screen? I'd have thought an
> > > > either or was more reasonable for the processor to sort out?
> > 
> > I am advocating:
> > 
> > <screen>
> > <![CDATA[
> > foo {
> >   bar ()
> > }
> > ]]>
> > </screen>
> > 
> > Same for <programlisting/> blocks.
> > 
> > This material, in the Fedora Doc Guide, is historical practice that we
> > can (and should) revise.
> > 
> 
> There are 2 reasons why the style guide says to include computeroutput
> or userinput tags inside screen tags:
> 
> 1. Technically, the content is computeroutput or userinput and should be
> marked accordingly to make it more correct
> 2. Marking them as computeroutput and userinput allows the text to be
> styled using CSS for the HTML version.

We've moved into very fine lines of distinction here.

In many situations, I'm not even sure I want any styling for the
contents of _some_ of my <screen> and <programlisting> blocks (esp.
<programlisting>).  It should be unstyled fixed-width fonts, no bold, no
extra fancy characters, no matter if it's utf-8 or iso-whatever.

However, Tammy's poing in 1) above is important -- perhaps the only
thing that _should_ be in a <screen> block is STDIN (<userinput>) or
STDOUT (<computeroutput>).  

If that is the case, then we wouldn't use CDATA blocks for <screen>. 
FWIW, putting CDATA in e.g. <computeroutput/> does not validate, but it
does build PDF and HTML.

It seems that my examples using foo {} is actually incorrect; that
should be a <programlisting> block which should probably always use
CDATA.

Sounds like I might be reversing myself!

How about this:

* We modify current usage rules to show a couple of acceptable styles
and which ones are likely to break or cause problems.  Specify that the
point is not XML styling but quality of output -- if your code gets the
desired output of no extra vertical or horizontal whitespace in PDF or
HTML, then it's fine.

* <screen> has <computeroutput> or <userinput> within it to be
semantically correct.

* <programlisting> always uses a CDATA section to preserve every detail
from processing (XSL and CSS included).

- 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