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

[Joerg Heinicke <joerg.heinicke@gmx.de>]

Hello Bob,

thanks for your comments. I already thought my mail was ignored, because 
it took a while ;-) See my answers below.

Bob Stayton wrote:

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

>>4. xsl/fo/pagesetup.xsl (partually patch included)
>>
>>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.

After sending the mail I thought over this and, yes, a template is here 
the better choice. It's much more flexible. It was only my simple case 
where I only set the attributes to different values.

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

Copy & paste :-) Yes I meant styling the separator by an attribute-set.

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

Yes, I know, it's only a FOP bug. If such an item is moved to the next 
page because of a page break, the ID on the previous page remains and 
the ID is added a second time to the next page => duplicate ID. I got 
the confirmation by J. Pietschmann, a Fop developer.

The stylesheet can add the ID dependent on the processor in the way it's 
often used in the stylesheets:

<xsl:if test="$fop.extensions != 1">
   <xsl:attribute name="id">
     <xsl:value-of select="$id"/>
   </xsl:attribute>
</xsl:if>

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

We have a programlisting that's really long because of an URL. The line 
runs out of the page because of 'no-wrap'. But I don't know whether 
making this configurable would really help: when switching @wrap-option 
to 'wrap' hyphenation is used and the hyphenation character is added. 
While writing this I thought about setting @hyphenation-character to 
empty string - is it possible? At the moment we do the break by hand, 
the typical 80 characters per line. Maybe a recursive template could be 
added to handle this automatically. I can do this - but not before my 
holidays ...

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

Very good.

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

Ah, sorry, I have to read the spec more exactly at this point I guess. I 
had a quick look when writing the above and I was not sure

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

because of strange different behaviour (maybe because of having 
sometimes not set the java.endorsed.dirs and so using the old Xalan from 
JDK 1.4). So please ignore this comment.

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

Nice to hear, go on with your good work. How can one handle such 
complexity of the stylesheets? Changing on the one end could break the 
stuff on three other ends ...

I will see if I can send further hints when improving the CI of our 
documents. Thanks for your comments.

Regards,

Joerg