Search code examples
xsltdocbook

Referencing custom elements in DocBook

another weekend and time to further play around with DocBook :-)

I added custom elements to my DocBook document and am translating them to FO and then to PDF via a XSLT transformation. This all works pretty fine. For example, I'm having a custom chapter element like:

<MyChapter xml:id="mychapter">
<title>Test</title>
</MyChapter

The background is that I want to enforce certain structures in that document and that basically works very well. There is only one thing that does not work and that I'm stuck with. My custom elements cannot be the target of an xref. E.g. the following does not work:

<xref linkend="mychapter"/>

While I think that I understand the reason that it is not working, I'm completely lost in fixing this. Did anybody here do anything similiar before and could give me a hint on how to approach this?

EDIT:

Following the first answer, I looked into what happens if (standard) sect3 is referenced. This seems to be controlled by the following template in this file:

<xsl:template match="d:section|d:simplesect
                     |d:sect1|d:sect2|d:sect3|d:sect4|d:sect5
                     |d:refsect1|d:refsect2|d:refsect3|d:refsection" mode="xref-to">
  <xsl:param name="referrer"/>
  <xsl:param name="xrefstyle"/>
  <xsl:param name="verbose" select="1"/>

  <xsl:apply-templates select="." mode="object.xref.markup">
    <xsl:with-param name="purpose" select="'xref'"/>
    <xsl:with-param name="xrefstyle" select="$xrefstyle"/>
    <xsl:with-param name="referrer" select="$referrer"/>
    <xsl:with-param name="verbose" select="$verbose"/>
  </xsl:apply-templates>
  <!-- FIXME: What about "in Chapter X"? -->
</xsl:template>

I'm trying to follow the logic here but I get stucked at 

<xsl:apply-templates select="." mode="object.xref.markup">

What does this line do?

Solution

  • Usually DocBook xref referencing logic is quite straightforward. If someone try to illustrate this logic by using human words it would be something like: put the link to the object1 with xml:id1 (using linkend) and get generated text from object2 with xml:id2 (using endterm) as link text.

    So, I suggest you want to put the mychapter title as a reference text. I would be change your sample as follows:

    <MyChapter xml:id="mychapter">
<title xml:id="mychapter_title">Test</title>
</MyChapter>

    Link snippet:

    <xref linkend="mychapter" endterm="mychapter_title"/>

    You'll get the reference (link itself) to your chapter with a reference text (link text) from a chapter title.

    This schema certainly works with default elements and should work with your custom elements if you use the default xsl template adopted to your custom mychapter.

    This logic is described very well here: http://www.sagehill.net/docbookxsl/CrossRefs.html