[docbook-apps] DocBook XSLT stylesheets: bugs, features, patches, enhancements

[Joerg Heinicke <joerg dot heinicke at gmx dot de>]

Hello,

I tried to style the auto-generated PDF documents in our CI. These 
documents now look quite good except because of some FOP limitations. It 
was a not so simple work and I came across some bugs and (missing) 
features in the DocBook stylesheets. Maybe you are interested. I used 
the XSLs in version 1.61.3 for it.

(The SourceForge CVS server seems to be unreliable. Had a few problems 
when doing the diffs. The same for bug tracking system.)

1. xsl/common/l10n.xsl (patch included)

a) bugfix

missing $target (already fixed after 1.61.3)

b) optimization

replacing

($target/ancestor-or-self::*[@lang]
|$target/ancestor-or-self::*[@xml:lang])[last()]

with

$target/ancestor-or-self::*[@lang or @xml:lang][1]

c) optimization

replacing

count($local.l10n.gentext) > 0

with

$local.l10n.gentext


2. xsl/fo/admon.xsl (patch included)

changing admon.graphic.width from named template to parameter, for 
consequency (other parameter names) renamed to $admon.graphics.width

Sorry, I don't know what exactly I have to update for automatically 
generating a correct param.xsl.


3. xsl/fo/formal.xsl (patch included)

using $table.properties instead of $formal.object.properties for tables

Seems to be a bug (or simply a missing change), because attribute-set 
$table.properties "extends" $formal.object.properties.


4. xsl/fo/pagesetup.xsl (partually patch included)

a) Why aren't $body.margin.left and $body.margin.right for 
fo:region-body offered? I guess the 3 days old fix

margin-left="{$page.margin.inner} - {$title.margin.left}"

addresses exactly this, but is more or less only a work around.

b) Having a non double-sided document and different settings for 
$page.margin.inner and $page.margin.outer leads to the strange effect of 
having the narrower border once left, once right, once left, ... but 
hey, it's not a double-sided document!

c) activating background image for FOP (already done after 1.61.3)

d) activating footnote-separator for FOP

Is there still any problem with it? It seemed to work for me except the 
fact that the text goes into the footnote's area, but this is 
independent on the footnote separator I guess.

What about blank-body? Why is this excluded for FOP, what's wrong with 
it? Have it included, but not used.

e) making head.sep.rule and foot.sep.rule configurable

Why not using an attribute-set for both head.sep.rule and foot.sep.rule 
instead of named templates?

f) making the footnote-separator configurable by an attribute-set 
$footnote.separator.properties instead of using a named template

g) making the page.number.format configurable by parameters

We wanted 'I' instead of 'i' for toc/preface/dedication.

5. xsl/fo/qandaset.xsl (no patch included)

Had a problem with FOP and duplicate ID messages when using 
<fo:list-item-label id="{$id}" end-indent="label-end()"> in lines 153 
and 202. I solved them by removing the id attribute. I don't know if I'm 
the only one, but maybe this issue should be addressed in the 
stylesheets (depending on $fop.extensions)??


6. xsl/fo/sections.xsl (patch included)

a) Shouldn't the marker depend on the section toc level (or another 
parameter)?

replacing

<xsl:if test="$marker != 0">

with

<xsl:if test="$marker != 0 and $toc.section.depth > $level">

b) wrapping the marker in the header (maybe to be parameterized?)

changing

<fo:marker>
  text
</fo:marker>

to

<fo:marker>
  <fo:inline wrap-option="no-wrap">
    text
  </fo:inline>
</fo:marker>

c) $titleabbrev is never '' even if no <titleabbrev/> is specified

The test

<xsl:when test="$titleabbrev = ''">
  <xsl:value-of select="$title"/>
</xsl:when>
<xsl:otherwise>
  <xsl:value-of select="$titleabbrev"/>
</xsl:otherwise>

is useless, because $titleabbrev is the unnumbered $title. I don't know 
exactly in which way it should be fixed without too many side effects. 
At least we wanted to have the numbered $title in the header and so I 
changed this to

<xsl:otherwise>
  <xsl:value-of select="$title"/>
</xsl:otherwise>

in my locally extending stylesheets, but this is of course not good patch.


7. xsl/fo/verbatim.xsl (no patch included)

Why not making the attributes @wrap-option, @white-space-collapse, etc. 
configurable?

<fo:block wrap-option='no-wrap'
          white-space-collapse='false'
          linefeed-treatment="preserve"
          xsl:use-attribute-sets="monospace.verbatim.properties
                                  shade.verbatim.style">

With the above the specified attributes have higher precedence than the 
attribute sets and can not be configured (per param or attribute-set) 
from outside. Why not moving the attributes into attribute-sets too?


8. xsl/fo/autotoc.xsl

$autotoc.label.separator not l10n-able

I only found it strange, that I can change

<template name="chapter"><Chapter/> %n. %t</template>

to

<template name="chapter"><Chapter/> %n %t</template>

but must configure the style of the chapter numbering with 
$autotoc.label.separator. It was only irritating ...


9. gentext/locale/de.xml

adding

<gentext key="hyphenation-character" text="-"/>
<gentext key="hyphenation-push-character-count" text="2"/>
<gentext key="hyphenation-remain-character-count" text="2"/>

to avoid disturbing warnings (same values as in en.xml)

10. general: named templates

In general I would like to see some things more to be configurable by 
params or attribute-sets instead of using named templates. The params 
are configured, the templates have to be searched deep in the 
stylesheets (what can be of course difficult if you don't know of their 
existence). A few examples are above already mentioned.

11. general: attribute-sets

What's bad with attribute-sets, is the fact, that you have to copy all 
attributes in an attribute-set if you want to overload only one attribute.

E.g. $formal.title.properties

<xsl:attribute-set name="formal.title.properties" 
use-attribute-sets="normal.para.spacing">
  <xsl:attribute name="font-weight">bold</xsl:attribute>
  <xsl:attribute name="font-size">
    <xsl:value-of select="$body.font.master * 1.2"></xsl:value-of>
    <xsl:text>pt</xsl:text>
  </xsl:attribute>
  <xsl:attribute name="hyphenate">false</xsl:attribute>
  <xsl:attribute name="space-after.minimum">0.4em</xsl:attribute>
  <xsl:attribute name="space-after.optimum">0.6em</xsl:attribute>
  <xsl:attribute name="space-after.maximum">0.8em</xsl:attribute>
</xsl:attribute-set>

Might be wrong here, but I think to set the font-size to our own value I 
have to copy the complete attribute set to my stylesheet that includes 
the DocBook stylesheets. If the original implementation changes, my 
stylesheet overloads the values I didn't want to have different from the 
original one.

An option would be to offer for all attribute-sets a 
user.name-of-the-attribute-set or something similar. The original 
attribute-set would be untouched. Refering attribute-sets must use the 
user attribute-sets of course then:

<xsl:attribute-set name="normal.para.spacing">
  ... some attributes ... untouched by user ...
</xsl:attribute-set>

<xsl:attribute-set name="user.normal.para.spacing"
          use-attribute-sets="normal.para.spacing">
  ... empty by default, the user sets values ...
</xsl:attribute-set>

<xsl:attribute-set name="formal.title.properties"
          use-attribute-sets="user.normal.para.spacing">
  ... refers to user's attribute-set ...
</xsl:attribute-set>

===========================================================================

Should be enough for the time being :-) The list guide lines mention 
that all attachements are removed, so I could not post the patches. The 
SourceForge bug tracking system is so slow or does not work completely - 
it's no fun. I try to post them there.

Of course I would be happy to see as much as possible in the docbook 
stylesheets - makes the customizing of the next version easier :-)

Any comments are appreciated.

Regards,

Joerg


---------------------------------------------------------------------
To unsubscribe, e-mail: docbook-apps-unsubscribe@lists.oasis-open.org
For additional commands, e-mail: docbook-apps-help@lists.oasis-open.org