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

[Bob Stayton <bobs at sco dot com>]

Thanks for all this.  It took awhile to digest
it all, but I'll check in most of these changes.
Norm may want to respond to some of them in case he
knows why something was done the way it was.
Some of my comments below.

On Tue, Aug 19, 2003 at 12:59:35AM +0200, Joerg Heinicke wrote:
> 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.

I'm not sure what a better solution is for handling
these margins without restructuring the page templates.

> 
> 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!

This must be a bug. 
 
> 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.

This must also be an improvement in FOP 0.20.5.
 
> 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?

I think this was done because a
template can respond to the type of pageclass and sequence.

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

I think you mean use an attribute-set in addition
to the named template.  The template outputs the
fo:static-content.  But it should use an attribute
set rather than having fixed characteristics.

> g) making the page.number.format configurable by parameters
> 
> We wanted 'I' instead of 'i' for toc/preface/dedication.

Good point.
 
> 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)??

This seems to be a bug in FOP, and continues with version 
0.20.5. There is no duplicate in the fo file, only in
the memory image that FOP constructs.  I'm not sure what
the stylesheets can do, because you can't just omit
the id because it might be the target of a cross reference.
 
> 
> 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.

You are right, $titleabbrev is not empty in this context.
This area needs some work, and possibly some choice about
what appears in the marker.
 
> 
> 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?

There are still several areas where properties could be moved
from templates to attribute-sets.  But I'm not sure why you
would want to change these properties, since they define
the behavior of a 'verbatim' environment.
 
> 
> 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 ...

Good point.
 
> 
> 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)

These will all be fixed in the next stylesheet release.
I changed the way the files are generated so they all
have all they keys, even if they aren't all translated.
> 
> 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.

That is not true.  Atribute-sets are supposed to be merged,
based on import precedence.  There is a bug in the current
xsltproc that prevents the merger, and so is you use xsltproc
you must copy all of them.  But that bug should be fixed
in the next release of xsltproc.

> 
> 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.

All of these suggestions are very much appreciated.
I have similar thoughts about moving a lot of
the FO properties into a more structured collection
of attribute-sets.  Just haven't had time to 
do the design work.

-- 

Bob Stayton                                 400 Encinal Street
Publications Architect                      Santa Cruz, CA  95060
Technical Publications                      voice: (831) 427-7796
The SCO Group                               fax:   (831) 429-1887
                                            email: bobs@sco.com

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