9.8.Â Links

Note:

9.8.1.Â xml:id Attributes

Most DocBook elements accept an xml:id
attribute to give that part of the document a unique name.
The xml: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 xml:id attribute. Assigning
an xml:id to all chapters and sections,
even if there are no current plans to link to them, is a good
idea. These xml:ids can be used as unique
anchor reference points by anyone referring to the
HTML version of the document.

ExampleÂ 9.34.Â xml:id on Chapters and
Sections

<chapter xml:id="introduction"><title>Introduction</title><para>This is the introduction. It contains a subsection,
which is identified as well.</para><sect1 xml:id="introduction-moredetails"><title>More Details</title><para>This is a subsection.</para></sect1></chapter>

Use descriptive values for xml:id
names. The values must be unique within the entire document,
not just in a single file. In the example, the subsection
xml:id is constructed by appending text to
the chapter xml:id. This ensures that the
xml:ids 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 xml:id attribute.

ExampleÂ 9.35.Â anchor

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

9.8.2.Â Crossreferences with xref

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

ExampleÂ 9.36.Â Using xref

Assume that this fragment appears somewhere in a
document that includes the xml: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
xml:id attribute on an anchor
element. The anchor has no content, so the
xref cannot generate the link text.

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

9.8.3.1.Â Links to the Same Document

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

ExampleÂ 9.37.Â Using link

Assume that this fragment appears somewhere in a
document that includes the xml: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
xml:id of an anchor element,
since the link content defines the link
text.

9.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Â 9.38.Â link 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 <link
xlink:href="&url.books.handbook;/svn.html#svn-intro">SVN
introduction</link>, then pick the nearest mirror from
the list of <link
xlink:href="&url.books.handbook;/svn.html#svn-mirrors">Subversion
mirror sites</link>.</para>