Table of Contents
Within a document.
Specialized cross references.
The following sections describe how to create each kind of cross reference and what extra features are available for it.
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
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:
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.
Example 14.1. Internal cross references
... <chapter id="intro"> <title>Introduction</title> <para>Welcome to our new product. One of its new features is a <link linkend="WidgetIntro">widget</link>. Other new features include ... </para> </chapter> <chapter id="WidgetIntro"> <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"/>. </para> </chapter> ...
When this document is processed, the
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
Here is some guidance for using these cross reference elements:
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.
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
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
Chapter 3 is generated.
For elements like
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>
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.
If you put an
xreflabel on an element that normally does have generated text, the attribute will override the default generated text.
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
Here is an example that matches the previous one but uses
<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" />
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.
|DocBook XSL: The Complete Guide - 3rd Edition||PDF version available|
Copyright © 2002-2005 Sagehill Enterprises