Ubiquitous Linking

Link to another page with the xref attribute on an inline code element:

<p>See the <code xref="mal_inline_link">link</code> element.</p>

Use the href attribute to turn an inline image into a link:

<p><media href="http://projectmallard.org/"
          type="image" mime="image/png" src="mallard-logo.png"/></p>

In implementations that support the install action scheme, use the action attribute to install a package:

<link action="install:yelp">Click here to install Yelp.</link>

For implementations that don't support the install action scheme, provide a fallback with the href attribute:

<link action="install:yelp"
      href="http://projects.gnome.org/yelp/">Click here to install Yelp.</link>

All basic inline elements optionally allow linking attributes. Linking attributes are mandatory on inline links and informational links; see their respective pages for details. An inline linking element is only expected to link to one resource or action, regardless of how many linking attributes are specified on the element. Link targets are used in the following order:

The xref attribute can take three basic forms to link to pages and sections within the same document. Additionally, it can be extended to point to resources in other documents. The three basic forms are as follows:

In all three basic forms, page_id and section_id must match the Nmtoken production.

The xref attribute can be extended using either the slash (U+002F) or colon (U+003A) character. If an xref attribute contains either character, the linking behavior depends on the processing tool. Processing tools should ignore any extended xref attributes they don't explicitly know how to deal with.

The action attribute allows you to create links that perform a particular action. Action attribute values resemble URIs. They begin with an action scheme that identifies the type of action. The action scheme is followed by a colon (U+003A) character and then scheme-specific data.

This specification makes no recommendations for particular action schemes. Support for particular action schemes depends entirely on the implementation. Processing tools should ignore any action attributes using an action scheme they don't understand.

The schema also provides the xref and action attributes in the namespace http://projectmallard.org/1.0/. When used on core Mallard elements, or extension formats defined on the projectmallard.org site, the attributes are in the local namespace. The namespaced versions are provided to add Mallard linking functionality to existing XML vocabularies when they are embedded into Mallard, such as SVG, MathML, or Ruby.

DocBook 4 requires explicit linking elements to create links within the document or to external resources. DocBook 5 provides common linking attributes for all elements. The xref element is similar to the linkend attribute in DocBook.

DITA does not provide linking attribute on arbitrary inline element. Instead, the xref element must be used to create links.

The formal definition of the Mallard language is maintained in RELAX NG Compact Syntax in code blocks within this specification. This is the formal definition for the linking attributes. The namespace declarations for these definitions are on the page Pages.

mal_attr_link = (
  attribute xref { text } |
  attribute href { text } |
  attribute action { text }
)
mal_attr_mal_link = (
  attribute mal:xref { text } ?,
  attribute mal:action { text } ?
)

The namespaced versions of the action and xref attributes are not used in basic Mallard documents. They are designed to be embedded in other XML vocabularies to create Mallard-based links and actions.