link

link — A hypertext link.

Synopsis

link ::=

Zero or more of:
- text
- Bibliography inlines
- Computer-output inlines
- Graphic inlines
  - inlinemediaobject
- Linking inlines
  - link
  - xref
- Markup inlines
  - email
  - literal
- Operating system inlines
- Product inlines
  - trademark
- Publishing inlines
  - abbrev
  - acronym
  - emphasis
  - footnote
  - footnoteref
  - phrase (db.phrase)
  - quote
- Technical inlines
- Ubiquitous inlines
- User-input inlines

Attributes

Common attributes and common linking attributes.

Additional attributes:

endterm (IDREF)
xrefstyle

Required attributes are shown in bold.

Description

The link is a general-purpose hypertext element. Usually, link surrounds the text that should be made “hot” (unlike xref which must generate the text), but the endterm attribute can be used to copy text from another element.

The link can have either a linkend attribute or an xlink:href attribute:

If it has a linkend attribute, link creates an internal cross-reference analagous to xref except that the author provides the link text.
If it has an xlink:href attribute, link is the equivalent of an HTML anchor (html:a href="...") for cross-reference with a Uniform Resource Identifier (URI).
(In this form, it replaces the ulink element from DocBook 4.x and earlier.)

Processing expectations with linkend

Formatted inline.

If the link element has content, then that content is processed for output as the “hot” text. If the link element has content and an endterm attribute, then the content is used and the endterm is ignored. If the link element has an endterm attribute and no content, then the content of the element pointed to by endterm is used as the “hot” text.

Processing expectations with xlink:href

Formatted inline.

When rendered online, it is natural to make the content of the link element an active link. When rendered in print media, the URI might be ignored, printed after the text of the link, printed as a footnote, or rendered in some other way.

When the content of the link element is empty, the content of the xlink:href attribute should be rendered as the text of the link. (In which case, naturally, it should be rendered even in print media.)

Attributes

Common attributes and common linking attributes.

endterm: Points to the element whose content is to be used as the text of the link
xrefstyle: Specifies a keyword or keywords identifying additional style information

Parents

These elements contain link: caption (db.html.caption), citetitle, emphasis, entry, link, literallayout, para, phrase (db.phrase), programlisting, quote, subtitle, td, term, th, title, titleabbrev.

Children

The following elements occur in link: text, abbrev, acronym, author, citetitle, command, computeroutput, editor, email, emphasis, filename, footnote, footnoteref, inlinemediaobject, link, literal, option, orgname, personname, phrase (db.phrase), quote, replaceable, subscript, superscript, systemitem, trademark, userinput, xref.

Examples

 1 |<article xmlns="http://docbook.org/ns/docbook"
   |         xmlns:xlink="http://www.w3.org/1999/xlink">
   |<title>Example links</title>
   | 
 5 |<para>In this sentence, <link linkend='nextsect'>this</link>
   |word is hot and points to the following section.
   |</para>
   | 
   |<para>In this sentence, the hot text of the link,
10 |<link linkend='nextsect' endterm="nextsect.title"/>,
   |is just the section title.
   |</para>
   | 
   |<para>In this sentence,
15 |<link xlink:href="http://docbook.org/">this</link> word is
   |hot and points to DocBook website.
   |</para>
   | 
   |<para>In this sentence, <link xlink:href="#nextsect">this</link>
20 |word is hot and also points to the following section. Note,
   |however, that this is dependent on the link target appearing
   |in the same document as the link and may not work consistently.
   |Use <tag class="attribute">linkend</tag> instead.
   |</para>
25 | 
   |<section xml:id='nextsect'>
   |  <title xml:id="nextsect.title">A Subsection</title>
   |  <para>This section only exists to be the target of a link.
   |  </para>
30 |</section>
   | 
   |</article>