Chapter 14. Cross references

Table of Contents

Cross references within a document
Options for generated xref text
Cross references between documents
Linking to websites
Customizing cross references
Modifying gentext templates
Customizing with an xrefstyle attribute
Customizing cross reference typography
Specialized cross references

DocBook supports a rich set of elements and features for creating cross references. Here are the basic kinds of cross references you can create:

The following sections describe how to create each kind of cross reference and what extra features are available for it.

Cross references within a document

DocBook employs the built-in feature of XML for cross referencing within a document, in which attributes are used to identify starting and ending points for cross references. In an XML DTD, an attribute can be assigned an attribute type of ID. That type of attribute is used to label an element as a potential target (end point) of a cross reference. The attribute name does not have be ID, it just needs to be declared as that type. In DocBook, the name of the attribute assigned this purpose just happens to be named id as well. In the DocBook DTD, almost every element can have an id attribute, with attribute type ID. That means any element in your document could be the target of a cross reference.

According to the XML standard, every value of an attribute with type ID must be unique. In DocBook, this means every instance of an id attribute in a document must be unique within that document. When you validate your document, the validator will tell you if you have any duplicate id attributes.

Other attributes can have a type of IDREF, which is used to point to an ID on another element to form a cross reference. There are a handful of elements in the DocBook DTD that have attributes of type IDREF, of various names. There are two main elements that are used to create cross references to targets within the same document:

xref

An automatic cross reference that generates the text of the reference. For that purpose, it is an empty element that takes no content of its own. The stylesheets control what output is generated. The generated text can be the target element's titleabbrev (if it has one) or title, number label (if it has one), or both.

link

A cross reference where you supply the text of the reference as the content of the link element. So it must not be an empty element.

Both of these elements require a linkend attribute whose value must match some id value in the document. Here are two examples:

Example 14.1. Internal cross references

...
<chapter  id="intro"> 1
<title>Introduction</title>
<para>Welcome to our new product. One of its 
new features is a <link  linkend="WidgetIntro">widget</link>.  2
Other new features include ...
</para>
</chapter>
<chapter  id="WidgetIntro">  3
<title>Introducing the Widget</title>
<para>Widgets are just one of our new features.
For a complete list of new features, see <xref  linkend="intro"/>.  4
</para>
</chapter>
...
1

Chapter element has an id attribute.

2

A link element has a linkend attribute that matches the second chapter, and some text content.

3

The second chapter also has an id attribute.

4

An xref element also has a linkend attribute, but it has no text content.

When this document is processed, the link and xref elements are converted to cross references. In HTML, they become A anchor tags, with the text of link becoming the link text and an appropriate HREF attribute being generated by the stylesheet. The HTML hot spot text for an xref is generated by the stylesheet from the chapter information. In PDF output, the links will also be active, and a page reference might also be generated for an xref (but never for a link element).

Here is some guidance for using these cross reference elements:

  • Use xref when you want to reference another element's title or number. It will automatically get the current information so you don't have to maintain such references.

  • Use link when you want to create a less formal reference that doesn't include the title or number. You can use whatever words you want.

  • When adding an id attribute, put it on the element itself, not the title. The stylesheets know how to find the title for each element being referenced.

  • Not all elements are appropriate as targets of an xref, because they don't have a title or number. For example, you may want to cross reference to a para, but you wouldn't want the whole paragraph to be copied as the reference text. See the next section for options you can use to use xref anyway.

Options for generated xref text

The stylesheets provide several options for generating the text for an xref element when it is processed.

Exclude title from chapter and section references

The generated text for chapters and appendixes is by default both the number and the title, such as Chapter 3, Using a Mouse. When section numbering is turned on, references to sections also get both. If you set the stylesheet parameter xref.with.number.and.title to zero (it's one by default), then only a number label like Chapter 3 is generated.

Attach an xreflabel to a target element

For elements like para or note that don't have a title or number, you can add an xreflabel attribute to the element. That attribute should contain the text you want to appear when an xref points to that element. Here is an example:

<para  id="ChooseSCSIid"  xreflabel="choosing a SCSI id">The methods
for choosing a <acronym>SCSI</acronym> id are ...
</para>
...
<para>
See the paragraph on <xref  linkend="ChooseSCSIid"/>.
</para>

The xref in the second paragraph points to the first paragraph. When processed, the second paragraph will read “See the paragraph on choosing a SCSI id.” and an HTML hot link will take the reader to the beginning of the paragraph.

The advantage of xreflabel over using a link element is to provide consistent reference text to that element. If you decide to change the wording, you only have to change the xreflabel, and all xref references to it will change. If you had used link instead, then you would have to find and edit each instance to change the text.

Note

If you put an xreflabel on an element that normally does have generated text, the attribute will override the default generated text.

Use another element's text for an xref

DocBook has another trick for generating text for an xref. You can actually grab the text from another element. Here is how it works.

You can add an endterm attribute to the xref element. The value of endterm must match an id value of an element in the document. The children of the element pointed to by endterm are used as the cross reference text. But the cross reference destination is still the linkend element.

Here is an example that matches the previous one but uses endterm instead:

<para  id="ChooseSCSIid"  >The methods
for <phrase  id="SCSIxref">choosing a <acronym>SCSI</acronym> id</phrase>
are ...
</para>
...
<para>
See the paragraph on <xref  linkend="ChooseSCSIid"  endterm="SCSIxref"/>.
</para>

Note that the endterm attribute goes in the xref element, not the target element. In this case it points to a phrase element in the paragraph that has the text you want in the reference text. When processed, the second paragraph will read “See the paragraph on choosing a SCSI id.” and an HTML hot link will take the reader to the beginning of the paragraph.

There is one difference with the previous example, however. Here, the <acronym>SCSI</acronym> element will be processed by the stylesheet as an acronym. You could not put the acronym markup in the xreflabel, because attributes cannot contain elements. So this feature is most useful when the generated text needs to contain elements.

You also need to be careful what element you point the endterm to. All the children of the selected element will be processed by the stylesheet as the reference text. If you point to a list, for example, then all the listitem elements in the list become the reference text.

A more likely example is forming a cross reference to the question in a qandaentry. By default, an xref to a question element displays just the label for the question, such as Q:1. If you want the reference text to be the question text, then you might try pointing both the endterm and the linkend attributes to the id on the question element. But the child elements of question will likely include para, which will be processed into <P> tags in HTML and introduce paragraph breaks where you just wanted some inline reference text. The solution is to add an id attribute to the para and point the endterm to that instead. Here are both the good and bad examples for comparison:

Example 14.2. Xref to a question in qandaentry

<qandaentry>
  <question  id="myQuestion">
    <para  id="QuestionText">What is the circumference of the Earth?</para>
  </question>
  <answer>
    ...
  </answer>
</qandaentry>

Bad example:  introduces paragraphs breaks in reference text
<xref  linkend="myQuestion"  endterm="myQuestion" />

Good example:  selects only the text children of para
<xref  linkend="myQuestion"  endterm="QuestionText" />

Customize the generated text

You may want to change the way xref text is generated for a particular kind of element, such as chapter or appendix. See the section “Customizing cross references” for the methods of doing that.