1.2 (2019-02-09)
Informational Links
This is a draft specification. It is likely that changes will still be made before the final specification.
Use the link element inside an info element to express logical links between pages and sections to be collected by automatic links.
Notes
The informational link element contains either an xref or an href attribute.
With an xref element, the informational link element has no content, although it may contain elements from external namespaces.
With an href element, the informational link element contains a title element and an optional desc element, optionally followed by elements from external namespaces.
The link element can occur in any info element.
-
The type attribute specifies what type of link is being expressed. The following values are currently recognized:
"topic"
specifies a topic link from a guide; target implicitly has a guide link back to the source
"guide"
specifies a link to a guide; target implicitly has a topic link back to the source
"seealso"
specifies a see-also link to another page or section; target implicitly has a see-also link back to the source
"next"
specifies another page to follow in a linear sequence
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 group attribute specifies a link group for explicit topic links, or for implicit topic links from guide links.
The link element can have attributes from external namespaces. See External Namespaces for more information on external-namespace attributes.
The link element can also be used in an inline context. See Hyperlinks for more information.
Examples
Provide a topic link from a guide page to another page:
<page type="guide" id="page1">
<info>
<link type="topic" xref="page2"/>
</info>
</page>Instead of the previous example, provide a guide link from the other page back to the guide:
<page id="page2">
<info>
<link type="guide" xref="page1"/>
</info>
</page>The previous two examples are equivalent, and produce the same results.
Provide a see-also link to another page:
<page id="page1">
<info>
<link type="seealso" xref="page2"/>
</info>
</page>You can also link to external resources. Since processing tools can't extract metadata from external resources, you provide the title and other metadata as child elements:
<page id="page1">
<info>
<link type="seealso" href="http://projectmallard.org/">
<title>Mallard</title>
</link>
</info>
</page>Processing Expectations
A recognized informational link element will generally cause a link to be displayed on both the page it was declared on and the page it links to. The details of how links are displayed depends on the link type, and can often be controlled with the links element. See Automatic Links for details.
Informational links in Mallard generally reciprocate in some way. Topic links are the inverse of guide links. See-also links are symmetric. Next links create implicit previous links. Tools must look at links originating from all pages to display the links for any page properly.
Most links can occur in pages or sections, and link to pages or sections. Next links, however, are only supported between pages.
Informational link elements must have a type attribute. This page lists standard link types that must be supported by any Mallard 1.2 processor. Extensions may add other link types. Although the href and action attributes are not used by any of the standard link types, they may be used by extensions. To avoid name conflicts, extensions should include a colon in the name of link types.
Informational links normally use the xref attribute to reference another page or section. When used this way, they do not have child content. The text for the displayed links they cause is taken from title and desc elements.
Mallard also allows certain informational link type to reference external resources with an href attribute. When used this way, the link element must contain a title element, and may optionally contain a desc element.
In either case, external-namespace elements are always allowed as child content. Child content should be treated as data in an informational context, and any unrecognized content should be ignored.
See Automatic Links for detailed processing expectations of different types of informational 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 informational link element. The namespace declarations for this definition are on the page Pages.
mal_info_link = ( mal_info_link_xref | mal_info_link_href )
mal_info_link_xref = element link {
attribute xref { text },
mal_info_link_attr,
mal_info_link_content *
}
mal_info_link_href = element link {
attribute href { text },
mal_info_link_attr,
mal_info_link_href_title,
mal_info_link_href_desc ?,
mal_info_link_content *
}
mal_info_link_href_title = element title {
attribute style { xsd:NMTOKENS } ?,
mal_attr_external *
mal_info_title_inline
}
mal_info_link_href_desc = element desc {
attribute style { xsd:NMTOKENS } ?,
mal_attr_external *
mal_info_desc_inline
}
mal_info_link_attr = (
attribute type { xsd:NMTOKEN },
attribute style { xsd:NMTOKENS } ?,
attribute group { text } ?,
mal_attr_external *
)
mal_info_link_content = mal_external