This is the mail archive of the docbook-apps@lists.oasis-open.org mailing list .


Index Nav: [Date Index] [Subject Index] [Author Index] [Thread Index]
Message Nav: [Date Prev] [Date Next] [Thread Prev] [Thread Next]
Other format: [Raw text]

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


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


Index Nav: [Date Index] [Subject Index] [Author Index] [Thread Index]
Message Nav: [Date Prev] [Date Next] [Thread Prev] [Thread Next]