Hyperlinks

This is a draft specification. It is likely that changes will still be made before the final specification.

Use the link to create a link to another page or section, or to an external resource such as a web page. Most inline elements can act as links, but the link element allows you to create a link without any associated semantics. The link element can also generate link text automatically for links to pages and sections within the same document.

Notes

The link element can contain a mixture of text and any general inline elements.
For links within the same document, content can be automatically generated.
The link element can occur in any general inline context, including inside most inline elements, some basic block elements, and certain informational elements.
The xref attribute creates a link to another page or section within the same document, or to an external resource in some document management system.
The href attribute creates a link to a web page or other network-accessible resource.
The style attribute takes a space-separated list of style hints. Processing tools should adjust their behavior according to those style hints they understand.
The role attribute can be used to select alternative titles of the target page or section to be used as automatic content.
The link element can have attributes from external namespaces. See External Namespaces for more information on external-namespace attributes.

Examples

Link to another page in the same document:

See <link xref="mal_attr_link"/> for information on linking attributes.

See Ubiquitous Linking for information on linking attributes.

Link to a section in the same page:

See <link xref="#processing"/> for details on automatic link text.

See Processing Expectations for details on automatic link text.

Link to a section in another page:

See <link xref="mal_inline#processing"/> for more processing expectations.

See Inline Processing Expectations for more processing expectations.

Link to an external resource:

See the <link href="http://www.w3.org/TR/REC-xml-names/">XML Namespaces
recommendation</link>.

See the XML Namespaces recommendation.

Processing Expectations

A link element is displayed as a hyperlink which can be clicked on or otherwise activated to take the user to another page, document, or resource. In certain environments, such as print, it may not be possible to make links activatable. In these cases, the target of the link may be displayed in the rendered output.

The target of a link element is determined from the action, xref, and href attributes exactly as it is for other inline elements. See Ubiquitous Linking for information on determining the link target.

If the link element is non-empty, its contents are displayed as normal. Otherwise, automatic link text is generated as follows:

If the link element has an action attribute, and the processing tool understands the action scheme, then the tool may generate automatic text based on the action scheme and data, or it may use the action data as link text.
Otherwise, if the link element has an xref attribute that points to a page or section in the same document:
1. If the link element has a role attribute, and the target page or section has a link title with the role attribute set to the same value as the role attribute of the link element, then the contents of that title element are used.
2. Otherwise, if that page or section has a link title without a role attribute, the contents of that title element are used.
3. Otherwise, the contents of the primary title of that page or section are used.
Otherwise, if the link element has an extended xref attribute, and the processing tool knows how to generate link text for the target, that text is used.
Otherwise, the link target is used as text content.

Comparison to Other Formats

The link element combines the functionality of the link and xref elements in DocBook, as well as the ulink element in DocBook 4. For the link and xref elements, DocBook provides the endterm attribute to select an alternative element from which to take content. Mallard does not provide this feature, although it allows you to select from alternative titles for the linked-to element.

DocBook provides the xrefstyle attribute to control how automatic link text is generated. The behavior of this attribute is unspecified. Rather than attempt to use style hints, Mallard allows writers to specify exact alternative link contents. Alternative link contents are important in languages with case declensions. See Link Text on the page Translation Notes for more information.

The link element is similar to the xref element in DITA. DITA uses the href attribute to link to pages within the same document as well as to external resources. Mallard uses a separate xref attribute for links within the document, and allows href to be used alone or as a fallback.

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 inline link element. The namespace declarations for this definition are on the page Pages.

mal_inline_link = element link {
  mal_inline_link_attr,
  mal_inline_link_inline
}
mal_inline_link_attr = (
  mal_attr_link +,
  attribute style { xsd:NMTOKENS } ?,
  attribute role { text } ?,
  mal_inline_attr,
  mal_attr_external *
)
mal_inline_link_inline = mal_inline