Re: [docbook-apps] any problems with DocBook XSL 1.79.0?

[Michael Fuchs <mlist@dbdoclet.org>]

Hi,

I am the author of dbdoclet and for my own transformation I did the following customization of the synop stylesheet. I also use attribute-sets for the keywords to have syntax highlighting. I also try to deal with annotation and the indentation.
I hope this is helpful for somebody.

Regards,
Michael

<?xml version='1.0'?>
<!DOCTYPE xsl:stylesheet [
<!ENTITY RE "&#10;">
<!ENTITY nbsp "&#160;">
]>

<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
    xmlns:fo="http://www.w3.org/1999/XSL/Format" version="1.0">

    <xsl:output method="xml" />

    <xsl:param name="line-length" select="80" />

    <xsl:template match="processing-instruction('line-break')">
        <fo:block />
    </xsl:template>

    <xsl:template match="classsynopsisinfo" mode="java">
        <xsl:if test="@role = 'comment'">
            <xsl:text>&RE;&nbsp;&nbsp;</xsl:text>
        </xsl:if>
        <fo:inline xsl:use-attribute-sets="synopsis.comment">
            <xsl:apply-templates mode="java" />
        </fo:inline>
        <!-- <xsl:if test="@role = 'comment'"> <xsl:text>&RE;</xsl:text> </xsl:if> -->
    </xsl:template>

    <xsl:template match="classsynopsis" mode="java">
        <fo:block wrap-option="wrap" white-space-collapse="false"
            linefeed-treatment="preserve" xsl:use-attribute-sets="monospace.verbatim.properties">

            <xsl:apply-templates select="ooclass[1]" mode="java" />

            <xsl:if test="ooclass[position() &gt; 1]">
                <fo:inline xsl:use-attribute-sets="synopsis.keyword">
                    <xsl:text> extends </xsl:text>
                </fo:inline>
                <xsl:apply-templates select="ooclass[position() &gt; 1]"
                    mode="java" />
                <xsl:if test="oointerface|ooexception">
                    <xsl:text>&RE;&nbsp;&nbsp;</xsl:text>
                </xsl:if>
            </xsl:if>
            <xsl:if test="oointerface">
                <fo:inline xsl:use-attribute-sets="synopsis.keyword">
                    <xsl:text> implements </xsl:text>
                </fo:inline>
                <xsl:apply-templates select="oointerface" mode="java" />
                <xsl:if test="ooexception">
                    <xsl:text>&RE;&nbsp;&nbsp;&nbsp;&nbsp;</xsl:text>
                </xsl:if>
            </xsl:if>
            <xsl:if test="ooexception">
                <fo:inline xsl:use-attribute-sets="synopsis.keyword">
                    <xsl:text>throws</xsl:text>
                </fo:inline>
                <xsl:apply-templates select="ooexception" mode="java" />
            </xsl:if>
            <xsl:text>&nbsp;{&RE;</xsl:text>
            <xsl:apply-templates
                select="constructorsynopsis
                                   |destructorsynopsis
                                   |fieldsynopsis
                                   |methodsynopsis
                                   |classsynopsisinfo"
                mode="java" />
            <xsl:text>}</xsl:text>
        </fo:block>
    </xsl:template>

    <xsl:template match="fieldsynopsis" mode="java">
        <fo:block wrap-option='wrap' white-space-collapse='false'
            linefeed-treatment="preserve" xsl:use-attribute-sets="monospace.verbatim.properties">
            <xsl:attribute name="space-before.minimum">0em</xsl:attribute>
            <xsl:attribute name="space-before.optimum">0em</xsl:attribute>
            <xsl:attribute name="space-before.maximum">0em</xsl:attribute>
            <xsl:attribute name="space-after.minimum">0em</xsl:attribute>
            <xsl:attribute name="space-after.optimum">0em</xsl:attribute>
            <xsl:attribute name="space-after.maximum">0em</xsl:attribute>
            <xsl:text>&nbsp;&nbsp;</xsl:text>
            <xsl:apply-templates mode="java" />
            <xsl:text>;</xsl:text>
            <xsl:call-template name="synop-break" />
        </fo:block>
    </xsl:template>

    <xsl:template mode="java"
        match="constructorsynopsis|destructorsynopsis|methodsynopsis">
        <xsl:variable name="start-modifiers"
            select="modifier[following-sibling::*[name(.) != 'modifier']]" />
        <xsl:variable name="notmod" select="*[name(.) != 'modifier']" />
        <xsl:variable name="end-modifiers"
            select="modifier[preceding-sibling::*[name(.) != 'modifier']]" />
        <xsl:variable name="decl">
            <xsl:text>&nbsp;&nbsp;</xsl:text>
            <xsl:apply-templates select="$start-modifiers"
                mode="java" />
            <!-- type -->
            <xsl:if test="name($notmod[1]) != 'methodname'">
                <xsl:apply-templates select="$notmod[1]" mode="java" />
            </xsl:if>
            <xsl:apply-templates select="methodname" mode="java" />
        </xsl:variable>
        <fo:block wrap-option='wrap' white-space-collapse='false'
            linefeed-treatment="preserve" xsl:use-attribute-sets="monospace.verbatim.properties">
            <xsl:attribute name="space-before.minimum">0em</xsl:attribute>
            <xsl:attribute name="space-before.optimum">0em</xsl:attribute>
            <xsl:attribute name="space-before.maximum">0em</xsl:attribute>
            <xsl:attribute name="space-after.minimum">0em</xsl:attribute>
            <xsl:attribute name="space-after.optimum">0em</xsl:attribute>
            <xsl:attribute name="space-after.maximum">0em</xsl:attribute>
            <xsl:copy-of select="$decl" />
            <xsl:text>(</xsl:text>
            <!-- Länge der Deklaration mit allen Parametern -->
            <xsl:variable name="decl-length">
                <xsl:call-template name="get-decl-length">
                    <xsl:with-param name="indent" select="string-length($decl)" />
                </xsl:call-template>
            </xsl:variable>
            <!-- Länge der Deklaration mit nur dem ersten Parameter -->
            <xsl:variable name="decl-first-param-length">
                <xsl:call-template name="get-decl-first-param-length">
                    <xsl:with-param name="indent" select="string-length($decl)" />
                </xsl:call-template>
            </xsl:variable>
            <!-- Zur Berechnung der Einrückungstiefe ist nur die letzte Zeile der
                Deklaration interessant. Darüber stehende Annotationen dürfen nicht mit in
                die Berechnung einfliessen. -->
            <xsl:variable name="decl-last-line">
                <xsl:choose>
                    <xsl:when test="contains($decl, '&#xA;')">
                        <xsl:value-of select="substring-after($decl, '&#xA;')" />
                    </xsl:when>
                    <xsl:otherwise>
                        <xsl:value-of select="$decl" />
                    </xsl:otherwise>
                </xsl:choose>
            </xsl:variable>
            <xsl:variable name="max-param-length">
                <xsl:for-each select="methodparam">
                    <xsl:sort select="string-length(concat(type, ' ', parameter))"
                        data-type="number" />
                    <xsl:if test="position() = last()">
                        <xsl:value-of select="string-length(concat(type, ' ', parameter))" />
                    </xsl:if>
                </xsl:for-each>
            </xsl:variable>
            <!-- <xsl:message> <xsl:text>[</xsl:text> <xsl:value-of select="../methodname"/>
                <xsl:text>] decl=</xsl:text> <xsl:value-of select="$decl"/> <xsl:text>, decl-last-line=</xsl:text>
                <xsl:value-of select="$decl-last-line"/> <xsl:text>, decl-length=</xsl:text>
                <xsl:value-of select="string-length($decl)"/> <xsl:text>, decl-first-param-length=</xsl:text>
                <xsl:value-of select="$decl-first-param-length"/> <xsl:text>, max-param-length=</xsl:text>
                <xsl:value-of select="$max-param-length"/> </xsl:message> -->
            <!-- Bestimmung der Einrückungstiefe -->
            <xsl:variable name="indent">
                <xsl:choose>
                    <xsl:when
                        test="((string-length($decl-last-line) + $max-param-length) &gt; $line-length)
              and (string-length($decl-last-line) &gt; ($line-length - $max-param-length))">
                        <xsl:value-of select="$line-length - $max-param-length + 1" />
                    </xsl:when>
                    <xsl:otherwise>
                        <xsl:value-of select="string-length($decl-last-line) + 1" />
                    </xsl:otherwise>
                </xsl:choose>
            </xsl:variable>
            <xsl:apply-templates select="methodparam" mode="java">
                <xsl:with-param name="indent" select="$indent" />
                <xsl:with-param name="decl-length" select="$decl-length" />
                <xsl:with-param name="decl-first-param-length"
                    select="$decl-first-param-length" />
            </xsl:apply-templates>
            <xsl:text>)</xsl:text>
            <xsl:if test="exceptionname">
                <fo:inline xsl:use-attribute-sets="synopsis.keyword">
                    <xsl:text>&RE;&nbsp;&nbsp;&nbsp;&nbsp;throws&nbsp;</xsl:text>
                </fo:inline>
                <xsl:apply-templates select="exceptionname"
                    mode="java" />
            </xsl:if>
            <xsl:if test="modifier[preceding-sibling::*[name(.) != 'modifier']]">
                <xsl:text> </xsl:text>
                <xsl:apply-templates select="$end-modifiers"
                    mode="java" />
            </xsl:if>
            <xsl:text>;</xsl:text>
        </fo:block>
        <xsl:call-template name="synop-break" />
    </xsl:template>

    <xsl:template match="ooclass" mode="java">
        <xsl:if test="position() &gt; 1">
            <xsl:text>, </xsl:text>
        </xsl:if>
        <xsl:apply-templates mode="java" />
    </xsl:template>

    <xsl:template match="oointerface" mode="java">
        <xsl:choose>
            <xsl:when test="name(preceding-sibling::*[1]) = 'oointerface'">
                <xsl:text>,&RE;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;</xsl:text>
            </xsl:when>
            <xsl:otherwise>
                <xsl:text></xsl:text>
            </xsl:otherwise>
        </xsl:choose>
        <xsl:apply-templates mode="java" />
    </xsl:template>

    <xsl:template match="classname" mode="java">
        <xsl:if test="name(preceding-sibling::*[1]) = 'classname'">
            <xsl:text>, </xsl:text>
        </xsl:if>
        <fo:inline xsl:use-attribute-sets="synopsis.name">
            <xsl:apply-templates mode="java" />
        </fo:inline>
    </xsl:template>

    <xsl:template match="interfacename" mode="java">
        <xsl:if test="name(preceding-sibling::*[1]) = 'interfacename'">
            <xsl:text>, </xsl:text>
        </xsl:if>
        <fo:inline xsl:use-attribute-sets="synopsis.name">
            <xsl:apply-templates mode="java" />
        </fo:inline>
    </xsl:template>

    <xsl:template match="exceptionname" mode="java">
        <xsl:if test="name(preceding-sibling::*[1]) = 'exceptionname'">
            <xsl:text>,&RE;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;</xsl:text>
        </xsl:if>
        <fo:inline xsl:use-attribute-sets="synopsis.name">
            <xsl:apply-templates mode="java" />
        </fo:inline>
    </xsl:template>

    <xsl:template match="methodname" mode="java">
        <fo:inline xsl:use-attribute-sets="synopsis.name">
            <xsl:apply-templates mode="java" />
        </fo:inline>
    </xsl:template>

    <xsl:template match="methodparam" mode="java">
        <xsl:param name="indent" select="0"/>
        <xsl:param name="decl-length" select="0" />
        <xsl:param name="decl-first-param-length" select="0" />
        <xsl:if
            test="not(preceding-sibling::methodparam) and $decl-first-param-length &gt; $line-length">
            <xsl:text>&RE;</xsl:text>
            <xsl:if test="$indent &gt; 0">
                <xsl:call-template name="copy-string">
                    <xsl:with-param name="string" select="' '" />
                    <xsl:with-param name="count" select="$indent" />
                </xsl:call-template>
            </xsl:if>
        </xsl:if>
        <xsl:if test="preceding-sibling::methodparam">
            <xsl:choose>
                <xsl:when test="$decl-length &gt; $line-length">
                    <xsl:text>,&RE;</xsl:text>
                    <xsl:if test="$indent &gt; 0">
                        <xsl:call-template name="copy-string">
                            <xsl:with-param name="string" select="' '" />
                            <xsl:with-param name="count" select="$indent" />
                        </xsl:call-template>
                    </xsl:if>
                </xsl:when>
                <xsl:otherwise>
                    <xsl:text>, </xsl:text>
                </xsl:otherwise>
            </xsl:choose>
        </xsl:if>
        <xsl:apply-templates mode="java" />
    </xsl:template>

    <xsl:template name="get-decl-length">
        <xsl:param name="indent">
            0
        </xsl:param>
        <xsl:variable name="buffer">
            <xsl:for-each select="methodparam">
                <xsl:if test="position()>1">
                    <xsl:text>, </xsl:text>
                </xsl:if>
                <xsl:value-of select="type" />
                <xsl:text> </xsl:text>
                <xsl:value-of select="parameter" />
                <xsl:text> </xsl:text>
            </xsl:for-each>
        </xsl:variable>
        <xsl:value-of select="$indent + string-length($buffer)" />
    </xsl:template>

    <xsl:template name="get-decl-first-param-length">
        <xsl:param name="indent">
            0
        </xsl:param>
        <xsl:variable name="buffer">
            <xsl:value-of select="methodparam[1]/type" />
            <xsl:text> </xsl:text>
            <xsl:value-of select="methodparam[1]/parameter" />
            <xsl:text> </xsl:text>
        </xsl:variable>
        <xsl:value-of select="$indent + string-length($buffer)" />
    </xsl:template>

    <xsl:template match="type" mode="java">
        <fo:inline keep-together="always" wrap-option="no-wrap"
            xsl:use-attribute-sets="synopsis.type">
            <xsl:apply-templates mode="java" />
        </fo:inline>
        <xsl:text>&nbsp;</xsl:text>
    </xsl:template>

    <xsl:template match="varname" mode="java">
        <fo:inline xsl:use-attribute-sets="synopsis.name">
            <xsl:apply-templates mode="java" />
        </fo:inline>
        <xsl:choose>
            <xsl:when test="name(.. ) = 'fieldsynopsis'">
                <xsl:if test="count(../initializer) &gt; 0">
                    <xsl:text>&nbsp;</xsl:text>
                </xsl:if>
            </xsl:when>
            <xsl:otherwise>
                <xsl:text>&nbsp;</xsl:text>
            </xsl:otherwise>
        </xsl:choose>
    </xsl:template>

    <xsl:template match="parameter" mode="java">
        <fo:inline xsl:use-attribute-sets="synopsis.name">
            <xsl:apply-templates mode="java" />
        </fo:inline>
    </xsl:template>

    <xsl:template match="modifier" mode="java">
        <xsl:choose>
            <xsl:when test="@role = 'annotation'">
                <fo:inline xsl:use-attribute-sets="synopsis.annotation">
                    <xsl:apply-templates mode="java" />
                </fo:inline>
            </xsl:when>
            <xsl:otherwise>
                <fo:inline xsl:use-attribute-sets="synopsis.keyword">
                    <xsl:apply-templates mode="java" />
                </fo:inline>
            </xsl:otherwise>
        </xsl:choose>
        <!-- <xsl:message>[dbdoclet.xsl] modifier role = <xsl:value-of select="@role"/></xsl:message> -->
        <xsl:choose>
            <xsl:when test="@role = 'annotation'">
                <xsl:choose>
                    <xsl:when test="local-name(..)='ooclass'">
                        <xsl:text>&RE;</xsl:text>
                    </xsl:when>
                    <xsl:otherwise>
                        <xsl:text>&RE;&nbsp;&nbsp;</xsl:text>
                    </xsl:otherwise>
                </xsl:choose>
            </xsl:when>
            <xsl:otherwise>
                <xsl:text>&nbsp;</xsl:text>
            </xsl:otherwise>
        </xsl:choose>
    </xsl:template>

</xsl:stylesheet>


Am 29.10.2015 um 17:58 schrieb Torsten Stolpmann:

Hi Bob,

sounds reasonable.

A tempting approach would be to check if the match is not the first occurrence of ooclass|oointerface|ooexception in a classsynopsis and there is a following sibling instead (including moving the choose statement behind the span).

Then again this might of course break other stuff I do not now about.

Please let me know if I can assist in getting this resolved in a future release.

Do you need a bug filed for this at the Sourceforge Tracker?

Regards,

Torsten

On 29.10.2015 17:38, Bob Stayton wrote:

Hi Torsten,
Thanks for the report.  It is unfortunate that it wasn't filed as a bug
report earlier so it could be fixed.  I'm unclear how to fix this as I'm
not very familiar with the synop templates.  I'm concerned about
introducing further bugs into a release that's about to go out.

Bob Stayton
Sagehill Enterprises
bobs@sagehill.net

On 10/29/2015 3:25 AM, Torsten Stolpmann wrote:

Hi Bob,

we use DBDoclet (http://www.dbdoclet.org/) to auto-generate
API-Documentation for DocBook.

Using the DocBook 1.79.0 stylesheets for html and fo output formats, the
following behavior also occurred with prior stylesheet versions:

When rendering a derived class in java the following output appears
(notice the trailing comma):

public final class Foo extends,
     Bar
{
}

The corresponding Docbook source generated by DBDoclet looks like the
following:

<section xreflabel="Foo" xml:id="dbdoclet-class-Foo">
   <title>Foo</title>
   <para>The Foo class.</para>
   <section>
     <title>Synopsis</title>
     <classsynopsis class="class" language="java">
       <ooclass>
         <modifier>public</modifier>
         <modifier>final</modifier>
         <modifier>class</modifier>
         <classname>Foo</classname>
       </ooclass>
       <ooclass>
         <classname>
           <link linkend="dbdoclet-class-Bar">Bar</link>
         </classname>
       </ooclass>
     </classsynopsis>
   </section>
</section>

I think this is rooted in the implementation of the following match
which does not recognize being called from a classsynopsis:

<xsl:template match="ooclass|oointerface|ooexception" mode="java">
   <xsl:choose>
     <xsl:when test="preceding-sibling::*">
       <xsl:text>, </xsl:text>
     </xsl:when>
     <xsl:otherwise>
       <xsl:text> </xsl:text>
     </xsl:otherwise>
   </xsl:choose>
   <span>
     <xsl:apply-templates select="." mode="common.html.attributes"/>
     <xsl:call-template name="id.attribute"/>
     <xsl:apply-templates mode="java"/>
   </span>
</xsl:template>

I think that the dbdoclet output is correct and this is a bug in the
stylesheets.

Otherwise the 1.79.0 release seems to be working great over here.

Regards,

Torsten

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

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