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.

Version 4.3 of the DocBook DTD made available an xrefstyle attribute to the xref and olink elements to allow an author to indicate special handling for a single cross reference. Version 1.62 of the stylesheets added support for this new attribute.

The DTD does not specify standard values for the 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>

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 don't. The gentext templates specify text in attributes, and attributes are not permitted to have elements in XML. So you can't 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 don't 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 23, 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.