We use the <xref>, <link>, and <ulink> elements to refer (or link) to other resources. Note that we prefer <xref> over <link>.

Normally, we use the <xref> element, like this:

...
<para>
Here is a link that points to <xref linkend="some-id"/>.
</para>
<section id="some-id">
<title>Important Section</title>
</section>

In this example, the link description is taken from the title of the referenced section, so that in most output formats, it will look like this:

Here is a link that points to Important Section.

In output formats that can display the link description as “hot” (or clickable), “Important Section” becomes a hotspot. This is, for example, true for HTML and PDF. In output formats where this is not possible (like printed books), our XSL stylesheets take care of adding additional information, so that the above example might look like this:

Here is a link that points to Section 10.5 Important Section.

You should use the <link> element only if you have to use text other than the linked element's title as the link description, like in the following example:

...
<para>
Here is a link that points to an <link linkend="some-id">important section</link>.
</para>
<section id="some-id">
<title>Important Section</title>
</section>

For both <xref> and <link>, do not use numbers to refer to elements! For example, do not use something like this:

See  <link linkend="some-id">10.5</link>.

For information about (automatic) numbering, see Section 5.2, “Guidelines for Numbering”.

Also, do not add additional information like the words “chapter” or “section” to your link. For example, do not use something like this:

See section <link linkend="some-id">Important Section</link>.

Our XSL stylesheets take care of adding such additional information in the correct language (bear in mind translations) when appropriate.

For links referring to resources other than XML documents, you should use the <ulink> element, which has the following syntaxes:

<ulink url="target-resource">descriptive text</ulink>
<ulink url="target-resource"/>

The second form can be used if the content of the element is the same as the URL attribute. Here is an example:

The MySQL Reference Manual is
<ulink url="http://dev.mysql.com/doc/mysql/">available online</ulink>
or can be downloaded in a number of formats. For example, you can find the
PDF version here:
<ulink url="http://dev.mysql.com/get/Downloads/Manual/manual.pdf/from/pick"/>