7. Links: connecting your document to itself and elsewhere

The advent of hypertext technology gives us the opportunity to make it much easier for the reader to jump around when looking for information. However, DocBook's ability to create both Web pages and paper copy complicates the task of linking. We want the Web versions to be hot-clickable, but keep in mind that the paper version must still be useful even though we can't click on it.

The paper equivalent of a hyperlink is a cross-reference. A cross-reference within the same work might say something like “See the section on frog identification below.” If you phrase your document in this way and use the right tags carefully, this will read normally in the print version and the Web version will read the same way and also be a link.

For cross-references to other locations in the same document, refer to Section 7.1, “The link and xref tags: Linking within your document”.
For references to a Web page outside the document, see Section 7.2, “The ulink tag: Linking to a Web page”.
Both Web and paper documents may refer to external works: printed books or documents. For this kind of linking, use the citetitle element; see Section 6, “Inline markup”.

7.1. The `link` and `xref` tags: Linking within your document

To refer to another location in the same document:

Invent a unique identifier name for the location to which you want to refer. The first character must be a letter, and the rest letters, numbers, hyphens, and the underscore (_) character.
For example, you might use the identifier flute-tuning for a section on how to tune a flute.
Find the start tag for the element to which you want to refer, and attach an id="I" attribute to that tag, where I is the identifier name you invented in the previous step. Any DocBook start tag can carry an id attribute.
For example, to refer to a main section, add the id attribute to the section element.
At the location where you want to cross-refer, use a tag of the form:
```
    <link linkend="I">T</link>
```
where I is the identifier defined in the previous step and T is the text of the link.

For example:

    <section id="thule-history">
      <title>The History of Thule</title>
        ...
    <section>
      ...
      <para>For more amusing folk traditions of Greenland, see
        <link linkend="thule-history">History of Thule</link> above.
      </para>

In the HTML output, this will produce a clickable link.
In the PDF output, the content of the link element will also be clickable, although it will not appear any differently than the surrounding text.

You can also use the empty element <anchor id="I"/> to define a target location, where I is the same unique identifier.

You may find it easier to use the xref element to link to other locations within your document. This is an empty element; the link text is generated automatically.

There are three ways to use this element. All three require that you assign a unique id attribute to the element to which you are linking:

Just encode it as <xref linkend="I"/>, where I is the target identifier. The link text will depend on the type of element. For example, a reference to a chapter element will generate link text containing the chapter number and title.
If there is an element somewhere near the target identifier whose content you would like to use as the link text, use this construct:
```
<xref linkend="I" endterm="J"/>
```
where I is the identifier of the element you want to link to, and the link text will be taken from the content of the element with id="J".
For example, suppose a chapter starts like this:
```
    <chapter id="ch11">
      <title>The <emphasis id="ch11-abbr">Last
        Chapter<emphasis></title>
```
Then this reference would use “Last Chapter” as the link text:
```
    <xref linkend="ch11" endterm="ch11-abbr"/>
```
You can specify what link text you want to use for a specific target by adding an xreflabel attribute to the target element. Any xref element that refers to that target will automatically use that attribute's value as its link text.
For example, suppose you start a chapter like this:
```
    <chapter id="ch14" xreflabel="The Silly Chapter">...
```
then any reference of the form <xref id="ch14"/> would use “The Silly Chapter” as its link text.

Writing documentation with DocBook-XML 4.3

7. Links: connecting your document to itself and elsewhere

7.1. The link and xref tags: Linking within your document

7.1. The `link` and `xref` tags: Linking within your document