Links are also in-line elements.
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.
id
on Chapters and
SectionsUse 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.
anchor
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.
xref
Assume that this fragment appears somewhere in a
document that includes the id
example shown above:
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.
xref
cannot link to an
id
attribute on an
anchor
element. The
anchor
has no content, so the
xref
cannot generate the link
text.
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.
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.
link
Assume that this fragment appears somewhere in a
document that includes the id
example.
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.
link
can be used to include links
to the id
of an
anchor
element, since the
link
content defines the link
text.
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.
ulink
to a FreeBSD Documentation Web
PageLink 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:
Appearance:
Read the SVN introduction, then pick the nearest mirror from the list of Subversion mirror sites.
Usage for article links:
Appearance:
Read this article about the BSD license, or just the introduction.
ulink
to a FreeBSD Web PageUsage:
Appearance:
Of course, you could stop reading this document and go to the FreeBSD home page instead.
ulink
to an External Web
PageUsage:
Appearance:
Wikipedia has an excellent reference on GUID Partition Tables.
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>.