Chapter 6. Links

Linking in DocBook is very similar to linking in HTML. The <link> and <xref> tags are used to link to any element with an id in a document, and can also be used to link to other local files as well. The <ulink> tag is used when you need to link to a URL. The <email> tag is a specialized form of the ulink tag used for email addresses. <anchor> is used to mark a spot in the text that you want to reference later with a Link. An overview of these most common link elements of DocBook follows.

Example 6.1. Five kinds of links

  1 <sect1 id="sec.link">
    <title id="sec.title.link">Docbook link types</title>
    <para id="par.link">
    This is a paragraph that will be linked to with a link tag. 
  5 If you want to know what's cool in HEP, point your browser
    at the <ulink url="http://www.cern.ch">CERN Web Page</ulink>.
    <anchor id="einstein.anchor"/>Einstein has been there.</para>
    <para>
    The above paragraph is reference <link linkend="par.link">here</link>.
 10 <xref linkend="sec.link"/> (<xref linkend="sec.link"
    endterm="sec.title.link"/>) is a reference to a section.  
    My email address is <email>[email protected]</email>
    </para>
    </sect1>

We see that to address their link targets the link and xref elements use the linkend attribute (lines 9 and 10), while the ulink element uses the url attribute (line 6). The link and xref elements can also have a endterm attribute, which specifies that the content of the element with the value of its id attribute equal to the value of endterm must be used as the text of the cross-reference (line 11).

The above example would be displayed something like what is shown below.

  1 1. Docbook link types 
    
    This is a paragraph that will be linked to with a link tag. 
    If you want to know what is cool in HEP, point your browser 
  5 at the CERN Web Page [http://www.cern.ch]. 
    Einstein has been there.
    
    The above paragraph is reference here. Section 1. (Docbook 
    link types) is a reference to a section. My email address is
 10 <[email protected]>.

We see how on lines 8 and 9 the work "Section 1." was generated by the application. Between brackets we find the contents of the title element, since the value of its id attribute (sec.title.link) corresponds to that specified on the endterm attribute of the xref element. Thus, we can finetune what we want to display as cross-reference information by making optimal us of the id attributes of the structural document elements.