1.10. Knowing the Difference Between Cross-References and Links

1.10. Knowing the Difference Between Cross-References and Links
Prev	Chapter 1. Knowing DocBook’s Structure	Next

Difficulty: ★☆☆ (easy)

Keywords: cross-reference, xref, links, localization

Problem

You want to set a “link” but you do not know which DocBook element to use.

Solution

DocBook distinguishes between two link types:

Internal Links or Cross-References. Used primarily with xref.
External Links. Used primarily with link.

Discussion

There are several differences between xref and link. An xref is used for cross referencing another part of the document. In its simplest form, you only need an ID value of the object that you want to refer:

Example 1.12. A Cross-Reference

<chapter xml:id="tea">
  <title>All About Tea</title>
  <section xml:id="about-tea">
    <title>About Tea</title>
    <para>This section gives you an introduction about tea.</para>
  </section>
  <section xml:id="prepar">
    <title>Preparing Tea</title>
    <para>Read an introduction in <xref linkend="about-tea"/>.</para>
  </section>
</chapter>

The DocBook XSL stylesheets take care of resolving the xref. By default, it replaces the xref element with a number and the title of the reference. It could look like this:

Read an introduction in Section 1.1, “About Tea”.

The text Section 1.1, “About Tea” is a “hot link” and points to the respective section. Using xref for cross-references has several advantages:

Whenever a text of a title changes, all xrefs pointing to it will automatically change too.
During validation, the linkend attribute is checked for existence.
During resolution, additional words like “Section”, “Chapter”, or “Figure” are automatically inserted according to the document language.
You do not have to care about numbering.
For further customization, use the xrefstyle attribute
.

In contrast, a link is used in most cases for external links.

Example 1.13. A Hyperlink

<section xml:id="about-tea">
  <title>About Tea</title>
  <para>See <link xlink:href="http://www.example.org/tea"/> for further information.</para>
</section>

Using link has the following advantages:

Usually no automatic resolution is performed (only if you use xlink:href).
No validation is necessary between source and target.
The link content can be created manually.
Additional inline elements are allowed.

The differences between xref and link are collected in Table 1.5, “Differences Between xref and link”.

Table 1.5. Differences Between xref and link

Topic	`xref`	`link`
TDG^[a] Definition	A cross-reference to another part of the document	A hypertext link
TDG Link	http://www.docbook.org/tdg51/en/html/xref.html	http://www.docbook.org/tdg51/en/html/link.html
Content Model	empty	text and inline elements
Resolution	Yes, automatically during transformation	No, link content must be definied manually
ID/IDREF Checking	Yes	No^[b]
Restrictions	Only cross referencing to elements that contain a `title`	No restrictions
^[a]The Definitive Guide, see http://www.docbook.org/tdg51/en/html/docbook.html . ^[b]Checking can be performed, when `linkend` attribute is used.

Prev	Up	Next
1.9. Inserting Remarks	Home	1.11. Inserting Cross-References