5.8. Links
Prev | Chapter 5. DocBook Markup | Next

## 5.8. Links

### Note:

Links are also in-line elements.

### 5.8.1. `id` Attributes

Most DocBook elements accept an `id` attribute to give that part of the document a unique name. The `id` can be used as a target for a crossreference or link.

Any portion of the document that will be a link target must have an `id` attribute. Assigning an `id` to all chapters and sections, even if there are no current plans to link to them, is a good idea. These `id`s can be used as unique anchor reference points by anyone referring to the HTML version of the document.

Example 5.28. `id` on Chapters and Sections
<chapter id="introduction"> <title>Introduction</title> <para>This is the introduction. It contains a subsection, which is identified as well.</para> <sect1 id="introduction-moredetails"> <title>More Details</title> <para>This is a subsection.</para> </sect1> </chapter>

Use descriptive values for `id` names. The values must be unique within the entire document, not just in a single file. In the example, the subsection `id` is constructed by appending text to the chapter `id`. This ensures that the `id`s are unique. It also helps both reader and anyone editing the document to see where the link is located within the document, similar to a directory path to a file.

To allow the user to jump into a specific portion of the document, even in the middle of a paragraph or an example, use `anchor`. This element has no content, but takes an `id` attribute.

Example 5.29. `anchor`
<para>This paragraph has an embedded <anchor id="para1">link target in it. It will not show up in the document.</para>

### 5.8.2. Crossreferences with `xref`

`xref` provides the reader with a link to jump to another section of the document. The target `id` is specified in the `linkend` attribute, and `xref` generates the link text automatically.

Example 5.30. Using `xref`

Assume that this fragment appears somewhere in a document that includes the `id` example shown above:

<para>More information can be found in <xref linkend="introduction"/>.</para> <para>More specific information can be found in <xref linkend="introduction-moredetails"/>.</para>

The link text will be generated automatically, looking like (emphasized text indicates the link text):

> More information can be found in Chapter 1, Introduction.

> More specific information can be found in Section 1.1, “More Details”.

The link text is generated automatically from the chapter and section number and `title` elements.

### Note:

`xref` cannot link to an `id` attribute on an `anchor` element. The `anchor` has no content, so the `xref` cannot generate the link text.

### 5.8.3. Linking to the Same Document or Other Documents on the Web

The link elements described here allow the writer to define the link text. It is very important to use descriptive link text to give the reader an idea of where the link will take them. Remember that DocBook can be rendered to multiple types of media. The reader may be looking at a printed book or other form of media where there are no links. If the link text is not descriptive enough, the reader may not be able to locate the linked section.

#### 5.8.3.1. Links to the Same Document

`link` is used to create a link within the same document. The target `id` is specified in the `linkend` attribute. This element wraps content, which is used for the link text.

Example 5.31. Using `link`

Assume that this fragment appears somewhere in a document that includes the `id` example.

<para>More information can be found in the <link linkend="introduction">sample introduction</link>.</para> <para>More specific information can be found in the <link linkend="introduction-moredetails">sample introduction with more details</link> section.</para>

This output will be generated (emphasized text is used to show the link text):

> More information can be found in the sample introduction.

> More specific information can be found in the sample introduction with more details section.

### Note:

`link` can be used to include links to the `id` of an `anchor` element, since the `link` content defines the link text.

#### 5.8.3.2. Linking to Other Documents on the Web

The `ulink` is used to link to external documents on the web. The `url` attribute is the URL of the page that the link points to, and the content of the element is the text that will be displayed for the user to activate.

Example 5.32. `ulink` to a FreeBSD Documentation Web Page

Link to the book or article URL entity. To link to a specific chapter in a book, add a slash and the chapter file name, followed by an optional anchor within the chapter. For articles, link to the article URL entity, followed by an optional anchor within the article. URL entities can be found in `doc/share/xml/urls.ent`.

Usage for book links:

<para>Read the <ulink url="&url.books.handbook;/svn.html#svn-intro">SVN introduction</ulink>, then pick the nearest mirror from the list of <ulink url="&url.books.handbook;/subversion-mirrors.html">Subversion mirror sites</ulink>.</para>

Appearance:

Read the SVN introduction, then pick the nearest mirror from the list of Subversion mirror sites.

Usage for article links:

<para>Read this <ulink url="&url.articles.bsdl-gpl;">article about the BSD license</ulink>, or just the <ulink url="&url.articles.bsdl-gpl;#intro">introduction</ulink>.</para>

Appearance:

Read this article about the BSD license, or just the introduction.

Example 5.33. `ulink` to a FreeBSD Web Page

Usage:

<para>Of course, you could stop reading this document and go to the <ulink url="&url.base;/index.html">FreeBSD home page</ulink> instead.</para>

Appearance:

Of course, you could stop reading this document and go to the FreeBSD home page instead.

Example 5.34. `ulink` to an External Web Page

Usage:

<para>Wikipedia has an excellent reference on <ulink url="http://en.wikipedia.org/wiki/GUID_Partition_Table">GUID Partition Tables</ulink>.</para>

Appearance:

Wikipedia has an excellent reference on GUID Partition Tables.

Prev | Up | Next
5.7. Images | Home | Chapter 6. Stylesheets

This, and other documents, can be downloaded from http://ftp.FreeBSD.org/pub/FreeBSD/doc/

For questions about FreeBSD, read the documentation before contacting <questions@FreeBSD.org>.
For questions about this documentation, e-mail <doc@FreeBSD.org>.