Ubiquitous Linking

Mallard contains three linking attributes that can be used with all basic inline elements. These attributes allow you to link to other Mallard pages, link to external resources, and create links that perform an action when clicked.

Notes

  • The xref attribute links to another page within the same Mallard document. See Processing Expectations for details on valid xref attribute values.

  • The href attribute links to an external resource by a URI.

  • The action attribute allows you to specify an action to perform when a user clicks a link. See Processing Expectations for details on the action attribute.

  • The schema also provides the xref and action attributes in the namespace http://projectmallard.org/1.0/. These are provided for extensions.

Examples

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>

See the link element.

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>

Click here to install Yelp.

Processing Expectations

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:

  • If an action attribute is present, and if the processing tool supports that action, the action attribute is used.

  • Otherwise, if an xref attribute is present, and if processing tool supports the target, the xref attribute is used.

  • Otherwise, if an href attribute is present, it is used.

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:

page_id

Link to another page with ID page_id.

page_id#section_id

Link to the section with ID section_id in the page with ID page_id.

#section_id

Link to the section with ID section_id in the current page.

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.

Comparison to Other Formats

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.

Schema

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.