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
