Re: [docbook-apps] Suggested Writing Style

["Bob Stayton" <bobs@sagehill.net>]

Hi,
To be more precise, the general rule is that spaces in elements whose 
content models include #PCDATA (text) cannot be ignored by the processor. 
For elements whose children can be only other elements and not #PCDATA, 
then spaces between those child elements are generally ignored.  Since the 
content model for <para> includes #PCDATA among other things, spaces in it 
can't be ignored. But the content model for <section> has only elements as 
children, so you can line-break and indent its children without 
consequence.

And "spaces" here means white space, which includes any combination of 
space characters, tabs, and carriage returns.  The DocBook styleheets (as 
do most) pass through all #PCDATA white space to the output.  If you 
examine your output (HTML or FO) and compare the white space in text 
elements to the original XML, then any text elements should retain it the 
same sequences of blanks, tabs, and carriage returns.

How does the stylesheet know which elements should have their white space 
preserved if it doesn't have access to the DTD?  By using the 
<xsl:preserve-space> and <xsl:strip-space> elements in common/common.xsl.

What happens then to that white space that is preserved by the stylesheet 
depends on the downstream processing.

When you view a <p> element in an HTML browser, the browser will collapse 
any sequence of white space characters into a single space (or carriage 
return if it falls at the end of a line).  If the text is inside a <pre>, 
then the browser doesn't collapse the white space.

In FO output, the default behavior of the XSL-FO processor is to do the 
same, that is, it will collapse a sequence of white space characters in 
text to a single space.  There are FO properties like 
white-space-treatment="preserve" and white-space-collapse="false" that can 
preserve the white space for certain elements like programlisting.

So as Sean said, this style:

<para>
This is a para.
</para>

has a carriage return at the start of the text, and one at the end.  In the 
final output, these will each become a single space.  The trailing space is 
usually of no consequence, but the leading space is noticeable in a 
left-aligned layout.

As others have pointed out, this is even more noticeable in 
<programlisting>:

<programlisting>
This is a listing.
</programlisting>

The handling of programlisting is to preserve white space exactly, without 
collapsing it. So the carriage return at the start will add a blank line to 
your listing, and the one at the end will do the same.

With this style of writing it is easier to view the XML.  And people think 
that because you can stack and indent nested elements, then it has no 
consequences.  But in any element that permits #PCDATA, it does.

BTW, the handling of white space in the SGML specification was a bit fuzzy. 
The XML and XSL specs define how white space should be handled more 
precisely.  That's why you may see different results when processing SGML.


Bob Stayton
Sagehill Enterprises
DocBook Consulting
bobs@sagehill.net


----- Original Message ----- 
From: "Euis Luhuanam" <eluhu6@gmail.com>
To: <docbook-apps@lists.oasis-open.org>
Sent: Thursday, August 10, 2006 7:04 AM
Subject: Re: [docbook-apps] Suggested Writing Style


> Sean Wheller wrote:
>>> <para>Blah... Blah... Blah sentences.</para>
>> This way is correct. Any other will induce spaces into the before and 
>> after of
>> the element value.
>
> Thank you! This brings me to the second issue:
> "Does the space matter"?
>
> CMIIW: It seems that xsltproc cares less then when I was using
> SGML with Jade tools,
>
> -- 
> EL6.
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: docbook-apps-unsubscribe@lists.oasis-open.org
> For additional commands, e-mail: docbook-apps-help@lists.oasis-open.org
>
>
>