Version 4.3 of the DocBook DTD made available an xrefstyle attribute to the xref, link, and olink elements to allow an author to indicate special handling for a single cross reference. Note that for a link element, an xrefstyle attribute is limited to controlling the generated page reference, if any. For an olink with text content, then xrefstyle currently has no effect at all on the output.

The DTD does not specify standard values for the xrefstyle attribute, so stylesheets are free to implement whatever scheme they want. The DocBook XSL stylesheets provide three ways to use the xrefstyle attribute:

Each of these methods is described in more detail in the following sections.

Input:
See <xref linkend="UsingMouse" 
      xrefstyle="template:the chapter numbered %n"/>
for more information.

HTML output:
See <a href="#UsingMouse">the chapter numbered 3</a>
for more information.

Input:
<xref linkend="MouseButtons" 
      xrefstyle="select: labelnumber quotedtitle"/>

HTML output:
<a href="#MouseButtons">2.1: "Using Mouse Buttons"</a>

Customization layer:
<xsl:param name="local.l10n.xml" select="document('')"/>
<l:i18n xmlns:l="http://docbook.sourceforge.net/xmlns/l10n/1.0">
  <l:l10n language="en">
    <l:context name="xref-number-and-title">
      <l:template name="sect1" style="num-qt" text="%n-&#8220;%t&#8221;"/>
    </l:context>
  </l:l10n>
</l:i18n>

Input:
<xref linkend="MouseButtons" xrefstyle="num-qt"/>

HTML output:
<a href="#MouseButtons">2.1-"Using Mouse Buttons"</a>

<xsl:apply-templates select="$target" mode="page.citation">

<xsl:template match="*" mode="page.citation">
  <xsl:param name="id" select="'???'"/>

  <fo:basic-link internal-destination="{$id}"
                 xsl:use-attribute-sets="xref.properties">
    <fo:inline keep-together.within-line="always">
      <xsl:call-template name="substitute-markup">
        <xsl:with-param name="template">
          <xsl:call-template name="gentext.template">
            <xsl:with-param name="name" select="'page.citation'"/>
            <xsl:with-param name="context" select="'xref'"/>
          </xsl:call-template>
        </xsl:with-param>
      </xsl:call-template>
    </fo:inline>
  </fo:basic-link>
</xsl:template>

<xsl:apply-templates select="chapter|appendix" mode="page.citation"/>

You customize cross reference text by modifying gentext strings for your locale in your customization layer. See the section “Generated text” for a general description of customizing generated text. For cross references, you want to look for gentext templates in one of the xref contexts in the language file you are working with, such as common/en.xml. These are the xref contexts (as of version 1.62 of the stylesheets) and when they apply:

For example, the common/en.xml file includes the following gentext templates. The text for chapter is highlighted in each context.

<l:context name="xref">
   <l:template name="abstract" text="%t"/>
   <l:template name="appendix" text="%t"/>
   <l:template name="chapter" text="%t"/>
   ...
</l:context>
<l:context name="xref-number">
   <l:template name="appendix" text="Appendix&#160;%n"/>
   <l:template name="chapter" text="Chapter&#160;%n"/> (&#160; is a non-breaking space)
   ...
</l:context>
<l:context name="xref-number-and-title">
   <l:template name="appendix" text="Appendix&#160;%n, %t"/>
   <l:template name="chapter" text="Chapter&#160;%n, %t"/>
   ...
</l:context>
   ...

Each DocBook element that can generate text has a l:template element within each context that can apply. The text attribute value is used to generate the output for a cross reference to that element. The %t placeholder resolves to the target element's title, and %n resolves to its number (if it is numbered).

For example, an xref that points to a chapter would normally generate text like Chapter 3, Using a Mouse (the non-breaking space was replaced for clarity). The context="xref-number-and-title" template is used because chapters are numbered and the stylesheet parameter xref.with.number.and.title is set to 1 by default. If you set xref.with.number.and.title to zero, then the context="xref-number" template is used instead. If you set chapter.autolabel to zero to turn off chapter numbering, then the context="xref" template is used.

To customize cross references, you add new gentext templates to your customization layer that override the stock templates. You have to make sure you cover all the targets elements you reference, and in all the contexts that you use.

For example, if you prefer to use a colon and quotes in cross references to chapters and appendixes, you can add the following to your customization layer:

<xsl:param name="local.l10n.xml" select="document('')"/> 
<l:i18n xmlns:l="http://docbook.sourceforge.net/xmlns/l10n/1.0"> 
  <l:l10n language="en"> 
    <l:context name="xref-number-and-title"> 
      <l:template name="appendix" text="Appendix %n: &#8220;%t&#8221;"/> 
      <l:template name="chapter" text="Chapter %n: &#8220;%t&#8221;"/> 
    </l:context>    
  </l:l10n>
</l:i18n>

If you want to do this for French as well as English, you'll need the following:

<xsl:param name="local.l10n.xml" select="document('')"/> 
<l:i18n xmlns:l="http://docbook.sourceforge.net/xmlns/l10n/1.0"> 
  <l:l10n language="en"> 
    <l:context name="xref-number-and-title"> 
      <l:template name="appendix" text="Appendix %n: &#8220;%t&#8221;"/> 
      <l:template name="chapter" text="Chapter %n: &#8220;%t&#8221;"/> 
    </l:context>    
  </l:l10n>
  <l:l10n language="fr"> 
    <l:context name="xref-number-and-title"> 
      <l:template name="appendix" text="Annexe %n: &#171;%t&#187;"/> 
      <l:template name="chapter" text="Chapitre %n: &#171;%t&#187;"/> 
    </l:context>    
  </l:l10n>
</l:i18n>

The gentext templates are shared by the HTML and FO stylesheets. If you are satisfied that your changes work in both output formats, you can put all of your gentext changes in a separate file and bring them into each of your stylesheet customization layers using:

<xsl:param name="local.l10n.xml" select="document('mygentextmods.xml')"/>

Or if you find you need different cross reference styles for the different output formats, you can keep them as separate modification files.

The mechanism of using gentext templates to generate cross references has one big limitation. The generated text is specified using an attribute in a l:template element in a localization file. An attribute value cannot contain element markup, nor can it alter the cross reference behavior under different contexts. If you need more control over how a cross reference is generated, you can create or customize a template in mode="xref-to".

If you look in the DocBook XSL stylesheet file xref.xsl (for either HTML or FO), you will see that the cross reference text is generated with this line:

<xsl:apply-templates select="$target" mode="xref-to">

The $target variable contains the element being referenced. Since this is a mode, there can be separate templates matching on each element type. You can customize the behavior for individual elements by creating or customizing a template that matches on that element in this mode.

If you examine the templates with mode="xref-to" in xref.xsl, you will see that most of them use xsl:apply-templates in mode="object.xref.markup". That mode is the DocBook mechanism that selects the appropriate gentext template from the localization files, and fills in the title and number for a cross reference. For example, here is the gentext template for sections when section numbering is not turned on:

<l:context name="xref">
  ...
  <l:template name="section" text="the section called &#8220;%t&#8221;"/>
  ...

Some templates using mode="xref-to" do not use the gentext template mechanism. For example:

<xsl:template match="author|editor|othercredit|personname" mode="xref-to">
  <xsl:param name="referrer"/>
  <xsl:param name="xrefstyle"/>

  <xsl:call-template name="person.name"/>
</xsl:template>

If you want to customize the behavior or generate additional markup for a cross reference for a particular element, then add a template that matches on that element and uses that mode. For example, you could customize how an author is referenced so that their affiliation is added:

<xsl:template match="author" mode="xref-to">
  <xsl:param name="referrer"/>
  <xsl:param name="xrefstyle"/>

  <xsl:call-template name="person.name"/>
  <xsl:if test="child::affiliation">
    <xsl:text> (</xsl:text>
    <xsl:apply-templates select="affiliation"/>
    </xsl:text>)</xsl:text>
  </xsl:if>
</xsl:template>

This template for author elements checks to see if it contains an affiliation element, and if so, outputs it within parentheses after the name. This template does not affect cross references to editor or other name elements.

Perhaps you want to change the typographical style for the generated text of a cross reference. For example, you might notice that xrefs to chapters italicize the chapter title, but xrefs to sections do not. You might think the gentext templates would let you customize the style, but they do not. The gentext templates specify text in attributes, and attributes are not permitted to have elements in XML. So you cannot wrap the gentext in HTML or FO elements for formatting.

You can italicize section titles with a stylesheet customization using the insert.title.markup mode. That mode is used to generate the title to replace the %t placeholder in a gentext template. For FO output, you need to create a template like the following in your customization layer:

<xsl:template  match="sect1|sect2|sect3|sect4|sect5|section"  
               mode="insert.title.markup">
  <xsl:param name="purpose"/>
  <xsl:param name="xrefstyle"/>
  <xsl:param name="title"/>

  <xsl:choose>
    <xsl:when test="$purpose = 'xref'">
      <fo:inline font-style="italic">
        <xsl:copy-of select="$title"/>
      </fo:inline>
    </xsl:when>
    <xsl:otherwise>
      <xsl:copy-of select="$title"/>
    </xsl:otherwise>
  </xsl:choose>
</xsl:template>

The mode named insert.title.markup is designed to handle adding markup to titles in a given context. The template parameter named purpose indicates the context. In this case, you want to wrap an inline font-style tag around a section title, but only if the purpose of the title is an xref. That way you do not also italicize these titles in their original location or the table of contents.

If you want something similar for HTML output, just copy this template to your HTML customization layer and replace the fo:inline start and end tags with the equivalent HTML I start and end tags.

If you want to style all cross references in FO output, for xref, link, and ulink references, then a simpler mechanism is available. The xref.properties attribute-set can be used to add FO properties to the text of all such cross references. For example, if you want the cross reference text to appear in blue for ulink elements, then use this customization:

<xsl:attribute-set name="xref.properties">
  <xsl:attribute name="color">
    <xsl:choose>
      <xsl:when test="self::ulink">blue</xsl:when>
      <xsl:otherwise>inherit</xsl:otherwise>
    </xsl:choose>
  </xsl:attribute>
</xsl:attribute-set>

This sets the color property conditionally. When the element using the xref.properties attribute set is a ulink, then the test matches and the color is blue. Otherwise the color is inherited, so there is no color change. Be sure to include the otherwise part. If you want all three cross reference elements to be blue, then you can just set the attribute value without using the choose statement.

For olink elements, the olink.properties attribute-set is available instead. It sets properties on the text generated for olink elements. See Chapter 24, Olinking between documents for more information.

To style all cross references in HTML output, just create a CSS selector on the A element, which is used for all hot links in HTML.