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