Draft

1.2 (2019-02-09)

Automatic Links

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

Mallard features an automatic linking system that allows pages and sections to declare links both to and from other pages and sections. Links are declared with a link element inside an info element. These links are then collected and displayed on pages. The links element allows you to control how automatic links are displayed.

Some types of links elements are implicitly added if they are absent. See the descriptions of the different types of links for details on implicit links.

Some types of links also allow you to link to external resource using the href attribute of an informational link. The title and other metadata for these links are taken from the link element itself, rather than a target node.

A links element belongs only to the page or section that is its direct parent.

Notes

  • The links element can contain an optional title element.

  • The links element can occur in page and section elements, either where block content occurs, or following any subsections.

  • The type attribute specifies the type of links to be inserted. Links types may be added by extensions. This specification requires the following types:

    "topic"

    see Topic Links

    "guide"

    see Guide Links

    "seealso"

    see See-Also Links

    "prevnext"

    see Previous and Next Links

    "series"

    see Series Links

    "section"

    see Section Links

  • 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 groups attribute takes a space-separated list of link groups. Links groups are used by topic links.

  • The links element can have attributes from external namespaces. See External Namespaces for more information on external-namespace attributes.

Examples

Insert all topic links for a page or section:

<links type="topic"/>

Separate topic links by group, giving a title to each group:

<links type="topic" groups="#first">
  <title>First Things First</title>
</links>
<links type="topic" groups="#default">
  <title>Topics</title>
</links>
<links type="topic" groups="#last">
  <title>In Other News</title>
</links>

Provide quick links to the sections in a page:

<page id="index">
  <links type="section"/>
  <section id="first">
    <title>First</title>
  </section>
  <section id="second">
    <title>Second</title>
  </section>
  <section id="third">
    <title>Third</title>
  </section>
</page>

Topic Links

A links element with type "topic" inserts topic links from a guide page or section. Guides may also have topic links to external resources using an href attribute. A guide has a topic link to an external resource or to another node if one of the following conditions is true:

  • The guide has an informational link with type "topic" whose href attribute points to the external resource.

  • The guide has an informational link with type "topic" whose xref attribute points to the target node.

  • The target node has an informational link with type "guide" whose xref attribute points to the guide.

Topic links are the inverse of guide links for internal links using the xref attribute.

There may be more than one topic links element in a single guide, each one displaying links from a different list of groups. The groups for a links element are taken from the groups attribute, which is treated as a space-separated list. The groups are then augmented as follows:

  • If no topic links elements contain the group #first, it is prepended to the list of groups of the first topic links element in the guide.

  • If no topic links elements contain the group #default, it is appended to the list of groups of the last topic links element in the guide.

  • If no topic links elements contain the group #last, it is appended to the list of groups of the last topic links element in the guide.

  • If both #default and #last are added implicitly, #last comes after #default.

Each topic link for the guide has an associated group, taken from the group attribute of the link element that declared the link. If the link element does not declare a group, or if its group is not in the list of all groups for the guide, its group is #default.

A topic links element shows only those links with a group that matches one of the values in its groups list. Links are sorted first by the position of their group in the groups list for the links element. They are then sorted by their sort titles.

The link text for a topic link is taken from the title of the target node, or from the link element itself for external links, as follows:

  1. If the link uses an href attribute to point to an external resource, the child title of that link element without a type attribute is used.

  2. Otherwise, if the links element has a role attribute, and the target node has a link title with the role attribute set to the same value as the role attribute of the links element, that title is used.

  3. Otherwise, if the target node has a link title with the role attribute set to "topic", that title is used.

  4. Otherwise, if the target node has a link title without a role attribute, that title is used.

  5. Otherwise, the primary title of the target node is used.

Topic links are valid for guide pages and sections in guide pages. If a guide page or section has topic links, but does not have a topic links element, the topic links are inserted implicitly as if there were a topic links element after all child block content, but before any subsections. The implicit links element has the default groups list "#first #default #last".

Previous draft revisions of this specification did not contain the links element, and placed the groups attribute on the page or section element. When implicitly adding topic links, processing tools may recognize the groups attribute on those elements to support older documents.

Guide Links

A links element with type "guide" inserts guide links to guide pages or sections. A node may also have guide links to external resources using an href attribute. A node has a guide link to an external resource or to a guide if any of the following conditions is true:

  • The node has an informational link with type "guide" whose href attribute points to the external resource.

  • The node has an informational link with type "guide" whose xref attribute points to the target guide.

  • The target guide has an informational link with type "topic" whose xref attribute points to the node.

Guide links are the inverse of topic links for internal links using the xref attribute.

If a node has a guide link to another page or section, that link is shown even if the target is not a guide. This allows guide links to be used for upwards navigation to different types of collection pages, such as those defined by extensions.

A guide links element shows all guide links for the enclosing page or section. Links are sorted by the sort title of their target guides.

The link text for a guide link is taken from the title of the target node, or from the link element itself for external links, as follows:

  1. If the link uses an href attribute to point to an external resource, the child title of that link element without a type attribute is used.

  2. Otherwise, if the links element has a role attribute, and the target node has a link title with the role attribute set to the same value as the role attribute of the links element, that title is used.

  3. Otherwise, if the target node has a link title with the role attribute set to "guide", that title is used.

  4. Otherwise, if the target node has a link title without a role attribute, that title is used.

  5. Otherwise, the primary title of the target node is used.

Guide links are valid on all pages and sections. If a node has guide links, but does not have a guide links element, the guide links are inserted implicitly as if there were a guide links element at the end of the node, after any block content and subsections.

See-Also Links

See-also links are links from nodes to any other nodes. Nodes may also have see-also links to external resources using an href attribute. A node has a see-also link to an external resource or to another node if any of the following two conditions is true:

  • The node has an informational link with type "seealso" whose href attribute points to the external resource.

  • The node has an informational link with type "seealso" whose xref attribute points to the target node.

  • The target node has an informational link with type "seealso" whose xref attribute points to the source node.

Internal see-also links always reciprocate; that is, if A has a see-also link to B, B always has a see-also link back to A.

A links element with type "seealso" inserts the see-also links for the containing node. Links are sorted by the sort title of their target nodes.

The link text for a see-also link is taken from the title of the target node, or from the link element itself for external links, as follows:

  1. If the link uses an href attribute to point to an external resource, the child title of that link element without a type attribute is used.

  2. If the links element has a role attribute, and the target node has a link title with the role attribute set to the same value as the role attribute of the links element, that title is used.

  3. Otherwise, if the target node has a link title with the role attribute set to "seealso", that title is used.

  4. Otherwise, if the target node has a link title without a role attribute, that title is used.

  5. Otherwise, the primary title of the target node is used.

See-also links are valid on all pages and sections. If a node has see-also links, but does not have a see-also links element, the see-also links are inserted implicitly as if there were a see-also links element at the end of the node, after any block content and subsections.

Previous and Next Links

Previous and next links are links between pages that allow you to create simple linear series of pages within a Mallard document. Previous and next links are only expected to be supported on pages. Previous and next links may not reference external resources with the href attribute.

A page has a next link to another page if it has an informational link with type "next" whose xref attribute points to that target page. Previous links are not declared explicitly. Instead, a page implicitly has a a previous link to a target page if the target page has a next link to it. If more than one page declares a next link to the same target, the behavior is undefined.

A links element with type "prevnext" inserts previous and next links for the containing page. Link text may be standard strings like “Previous” and “Next”. When link text is taken from the title of the target page, it is taken as follows:

  1. If the target node has a link title without a role attribute, that title is used.

  2. Otherwise, the primary title of the target node is used.

No link title roles are currently recommended for previous and next links.

Previous and next links are valid for all pages. If a page has previous or next links, but does not have a links element with type "prevnext", the previous and next links are inserted implicitly. Previous and next links may be displayed in a navigation bar in a header or footer. Some implementations may have other presentations.

Series Links

A links element with type "series" inserts links to all pages within a linear series created by next links. The sequence of links is such that each target page has a next link to the next target. The current page is shown at its place in the series without being linked to, to give users context. Implementations should be careful to detect cycles in next links.

The link text for a series link is taken from the title of the target node, as follows:

  1. If the links element has a role attribute, and the target node has a link title with the role attribute set to the same value as the role attribute of the links element, that title is used.

  2. Otherwise, if the target node has a link title with the role attribute set to "series", that title is used.

  3. Otherwise, if the target node has a link title without a role attribute, that title is used.

  4. Otherwise, the primary title of the target node is used.

Since next links are only valid on pages, series links are also only valid on pages. If a page does not contain a series links element, the series links are not displayed. Series links are not implicit.

Section Links

A links element with type "section" inserts links to the child sections of the containing node. By default, only the direct child sections should be shown, but tools may use a style hint to create a tree of links to nested sections.

The link text for a section link is taken from the title of the target section, as follows:

  1. If the section has a link title without a role attribute, that title is used.

  2. Otherwise, the primary title of the section is used.

No link title roles are currently recommended for section links.

Section links are valid for any page or section that contains child sections. If a page or section does not contain a section links element, the section links are not displayed. Section links are not implicit.

Processing Expectations

A links element is displayed as a block, usually with each link as a block or list item. Some types of links may be formatted differently, and formatting may depend on style hints. Links should be clearly formatted to separate them from surrounding content and other types of links.

When present, the title element should be displayed in a way that makes it clear that it is the title of the links element. If a title element is not present, a title may be automatically generated for certain types of links.

If there are no links to display for a links element, then the element as a whole is not displayed, including its title.

If links for a node are displayed after child sections of that node, they should be separated using a header or other formatting to make it clear that they do not belong to the child section.

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

mal_links = element links {
  mal_links_attr,
  mal_block_title ?,
  mal_links_content *
}
mal_links_attr = (
  attribute type { xsd:NMTOKEN },
  attribute style { xsd:NMTOKENS } ?,
  attribute role { text } ?,
  attribute groups { text } ?,
  mal_attr_external *
)
mal_links_content = mal_external
© 2011 Shaun McCance
cc-by-sa 3.0 (us)

This work is licensed under a Creative Commons Attribution-Share Alike 3.0 United States License.

As a special exception, the copyright holders give you permission to copy, modify, and distribute the example code contained in this document under the terms of your choosing, without restriction.

Powered by
Mallard