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

[Karsten Wade]

On Tue, 2004-08-31 at 10:48, Dave Pawson wrote:
> On Tue, 2004-08-31 at 18:33, Karsten Wade wrote:
> 
> > 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.
> 
> <grin/> Which is a pretty good definition of a style IMHO.

Ha!  You caught me there.

You can tell by my flip-flopping and half-thought-through opinions that
I'm not quite sure what is the best thing to do, which usually means
it's time to pick something that works and move on.


> > 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.
> 
> Its not a validity issue. Simply well-formedness.

Odd, I did C-c C-v and got some validation errors, which, uh, aren't
occurring now.  *shrug*

> > * 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.
> 
> -1.
>   I'd have thought the project needs valid XML instances.

Which instances are valid and which are not?

I only meant, valid XML usage.  Is there only one "right way"?  If so,
then I guess this whole discussion is no longer moot!


> > * <screen> has <computeroutput> or <userinput> within it to be
> > semantically correct.
> 
> Why isn't screen 'right' for the contents of the screen?
> Or if you are talking about a programs output, or a user input,
> then use computeroutput or userinput.

I would reckon that the usage came about this way from wanting to mark
all user input as <userinput> and all screen output as <computeroutput>,
whether it is inline in a <para/> or blocked in a <screen/>.

The idea would be, it should be marked as <...input/> or <...output/> in
all instances.

However, those tags cannot stand alone the way <screen> can.  <screen/>
must be used to get the desired styling output.  Just putting <para>
tags around the <...put/> tags would not be the same thing, semantically
or stylistically.

I'm guessing as to that reasoning; Ed or Tammy would be better to answer
that.

That reasoning makes some amount of sense to me.

> > * <programlisting> always uses a CDATA section to preserve every detail
> > from processing (XSL and CSS included).
> 
> But thats the point of stylesheets Karsten, to apply style.
> 
> http://www.w3.org/TR/2004/REC-xml-20040204/#sec-cdata-sect
> 
> 
> An example of a CDATA section, in which "<greeting>" and "</greeting>"
> are recognized as character data, not markup:
> 
> <![CDATA[<greeting>Hello, world!</greeting>]]> 
> 
> 
> That's all CDATA sections do.

Okay, I concede that I'm getting myself into a confused corner.

For maintainability and ease of handing off documents to others for
editing and writing, I find using CDATA inside <programlisting> to be
invaluable.  Perhaps we don't make this a hard requirement, just fix the
stylesheets so <programlisting> content output looks the same regardless
of CDATA usage (it may already do that), and leave it up to the author.

- 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