1.12. Choosing Between Link Methods

1.12. Choosing Between Link Methods
Prev	Chapter 1. Knowing DocBook’s Structure	Next

Difficulty: ★☆☆ (easy)

Keywords: external links, simple XLinks, xlink:href, ulink

Problem

You need some ideas about link markup.

Solution

Use the link^[4] element. Usually, external links are used in two ways:

Empty. The link element is completely empty:

<link xlink:href="https://github.com/tomschr/dbcookbook"/>

With content. The link element has text or element content:

<link xlink:href="https://github.com/tomschr/dbcookbook">The DoCookBook</link>

Don't forget to add the XLink namespace declaration into the root element of your document, for example:

<book xmlns:xlink="http://www.w3.org/1999/xlink" ...>

Discussion

The link element has several features for creating internal or external links. It optionally has content. Regardless of content, you have to choose between the attributes xlink:href or linkend.

Knowing the Properties of the `xlink:href` and `linkend` Attributes

Using linkend always points to an internal link and is semantically equivalent to xref. You cannot create external links using the linkend attribute.

On the other hand, the XLink attribute xlink:href can be used for both types: internal or external links. An example is shown in Table 1.8, “Internal and External Links Examples”.

Table 1.8. Internal and External Links Examples With linkend vs. xlink:href

	`xlink:href`	`linkend`
Datatype	xsd:anyURI	xsd:IDREF
Internal	`#cha.intro`	`cha.intro`
External	`http://www.docbook.org`	―

Note, validation is only performed when using linkend, not with xlink:href! The reason for this is the different datatypes. The XML parser can only validate a xsd:ID and xsd:IDREF connection.

Choosing the Needed Combination

With text content, you have several combinations that are shown in Table 1.9, “Different Possibilities for Links”:

Table 1.9. Different Possibilities for Links

		Content
		With Content	Empty
Linking Attributes	`xlink:href`	Content is a link to the specified URI	The specified URI is used as the content
Linking Attributes	`linkend`	Content is an internal link to the element identified	Semantically equivalent to an `xref` (internal link)

The following list shows some examples:

Links With Content Using xlink:href

Use this code to create an external link with a text different than the URL:

<link xlink:href="https://github.com/tomschr/dbcookbook">My Project</link>

Links With Content Using linkend

Use this code to create an internal link (cross reference). The “hot text” is created from the content of link:

<link linkend="cha.intro">Introduction</link>

Empty Links Using xlink:href

Use this code to create an external link where the “hot text” is taken from the URL:

<link xlink:href="http://www.example.org/Intro"/>

If you want to create an internal link without ID validation check, use this code:

<link xlink:href="#cha.intro"/>

This is equivalent to the following xref notation:

<xref linkend="cha.intro"/>

Note the absence of the # character. In both cases, an empty link with xlink:href or an xref with linkend, the ID must exist within the document. Otherwise, the element cannot be resolved during processing thus causing a broken link.

Empty Links Using linkend

This notation is semantically equivalent to an xref. See also Section 1.11, “Inserting Cross-References”:

<link linkend="cha.intro"/>

The only difference of the previous example is that it constitutes a validation error if the ID cha.intro is missing document.

In most cases, it is enough to just use an empty link element. As such, avoid the following notation when the URL in xlink:href is the same as the text:

<link xlink:href="https://github.com/tomschr/dbcookbook">https://github.com/tomschr/dbcookbook</link>

This is mostly unnecessary as it is overly verbose, difficult to read, and does not add any value. Correct such links and remove the text:

<link xlink:href="https://github.com/tomschr/dbcookbook"/>

Shortening Links

DocBook 5 also adds new concepts. One of this new concept is that every element can become a link. In other words, you do not have to use a link element anymore. For example, if you want to insert a book title with an additional link, in DocBook 4 it has to be written like this:

<citetitle><ulink url="https://github.com/tomschr/dbcookbook">The DoCookBook</ulink></citetitle>

or this, depending on what you prefer:

<ulink url="https://github.com/tomschr/dbcookbook"><citetitle>The DoCookBook</citetitle></ulink>

With DocBook 5 this can be shortend:

<citetitle xlink:href="https://github.com/tomschr/dbcookbook">The DoCookBook</citetitle>

Apart from the previous described link concept, DocBook 5 allows to control the link behavior. For example, to open a new window when clicking a link, use the xlink:show attribute:

<link xlink:show="new" xlink:href="https://github.com/tomschr/dbcookbook"/>

The attribute value show opens a “new window, frame, pane, or other relevant presentation context” (see Common Linking Attributes). Of course, this is only useful for online formats.

Prev	Up	Next
1.11. Inserting Cross-References	Home	1.13. Inserting Inline Quotes