Next / Previous / Contents / Shipman's homepage

8. 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.

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

To refer to another location in the same document:

  1. 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.

  2. Find the start tag for the element to which you want to refer, and attach an xml: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 xml:id attribute.

    For example, to refer to a main section, add the xsl:id attribute to the section element.

  3. 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 xml:id='thule-history'>
      <title>The History of Thule</title>
      <para>For more amusing folk traditions of Greenland, see
        <link linkend='thule-history'>History of Thule</link> above.
  • 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 xml: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 xml: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 xml:id='J'.

    For example, suppose a chapter starts like this:

        <chapter xml:id='ch11'>
            <title>The <emphasis xml:id='ch11-abbr'>Last

    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 xml:id='ch14' xreflabel="The Silly Chapter">...

    then any reference of the form <xref xml:id='ch14'/> would use “The Silly Chapter” as its link text.


You may use any inline element as a link: simply add a linkend attribute.

For example, to mark up the word “Smashilator” as an application, and to make this word a link to a section whose xml:id is "smashor":

    <application linkend='smashor'>Smashilator</application>