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 the sections on the <link> and <xref> tags below.
For references to a Web page outside the document, see the section on the <ulink> tag below.
Both Web and paper documents may refer to external works: printed books or documents. For this kind of linking, use the <citetitle> tag (above, in the description of inline tags).

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, made from 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 attribute to the <sect1> tag.
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:

    <sect1 id="thule-history">
      <title>The History of Thule</title>
        ...
    <sect1>
      ...
      <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 PostScript output, the content of the <link> element will be underlined.

You can also use the empty (non-paired) tag <anchor id="I"> to define a target location, where I is the same unique identifier.

Cross-references won't be correct the first time you build your PostScript file. Remove your .dvi file and rebuild it twice, and references should be correct the third time.

You may find it easier to use the <xref> element to link to other locations within your document. This element is empty (has no content), since the link text is generated automatically.

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

Just say <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 may 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.

7.2. The `<ulink>` tag: Linking outside your document

To refer to a location on a Web page outside the current document, use the tag <ulink url="U"> tag, where U is the URL (Uniform Resource Locator) of the location to which you are referring.

In the HTML output this will result in a clickable link. In print output, DocBook will include the URL after the link text so that readers can find the reference.

Example:

    See the
    <ulink url="http://www.nmt.edu/tcc/"> TCC Help System at
      <userinput>http://www.nmt.edu/tcc/</userinput>
    </ulink>...”

would display as: “See the TCC Help system at http://www.nmt.edu/tcc/...”

Writing documentation with DocBook-XML 4.2