Informational Links
This specification has been replaced by Mallard 1.1.
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 has no content, although it may contain 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 link element can contain any of the linking attributes. The link types in this specification only use the xref attribute.
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.
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.0 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 hyphen in the name of link types.
Informational links do not have child content. The text for the displayed links they cause is taken from title and desc elements. External-namespace elements are allowed. Child content should be treated as data in an informational context, and any unrecognized content should be ignored.
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 = element link {
mal_info_link_attr,
mal_info_link_content *
}
mal_info_link_attr = (
attribute type { xsd:NMTOKEN },
attribute style { xsd:NMTOKENS } ?,
mal_attr_link +,
attribute group { text } ?,
mal_attr_external *
)
mal_info_link_content = mal_external