1.2 (2019-02-09)
Informational Elements
This is a draft specification. It is likely that changes will still be made before the final specification.
The info element contains metadata about a page, section, or formal block element. Mallard provides a core set of informational elements for most common needs. Informational elements like link, title, and desc are the core of automatic links. Other informational elements record credits, copyrights, revisions, and license information.
Furthermore, Mallard allows elements from external namespaces to be used inside the info element. External-namespace informational elements can be used to record any additional information you need.
Notes
-
The info element contains a mixture of the following, in any order:
An optional desc element.
An optional keywords element.
Any number of credit elements.
Any number of license elements.
Any number of informational link elements.
Any number of informational title elements.
Any number of revision elements.
Any number of elements from an external namespace. There are no restrictions on the contents of these elements. See External Namespaces and Processing Expectations for more information on external-namespace elements.
The info element can occur as the first element of a page, section, or formal block element.
The info element can have attributes from external namespaces. See External Namespaces for more information on external-namespace attributes.
Examples
The info element for this page:
<info>
<link type="guide" xref="index" group="info"/>
<credit type="author">
<name>Shaun McCance</name>
<email>shaunm@gnome.org</email>
<years>2008-2018</years>
</credit>
<license href="http://creativecommons.org/licenses/by-sa/3.0/us/">
<p>This work is licensed under a
<link href="http://creativecommons.org/licenses/by-sa/3.0/us/">Creative
Commons Attribution-Share Alike 3.0 United States License</link>.</p>
<p>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.</p>
</license>
<desc>Include metadata and automatic links for pages and sections.</desc>
</info>See the various informational elements for more examples.
Informational Elements
The core informational elements are elements that can appear directly inside an info element.
Additional Elements
Mallard provides additional elements that allow you to provide structured information inside some informational elements.
Processing Expectations
Information inside an info element is not displayed directly, although some tools may adjust their formatting or display extra controls or information based on elements in the info element.
Certain informational elements are responsible for automatic links. Pages and sections are displayed with additional links based on this information. See Automatic Links for more information.
The info element can contain elements from external namespaces. Processing tools may use known elements to affect processing or add additional information. Tools should ignore any elements they do not understand.
If an info element appears in any context other than as the first element of a page, section, or block element, it is ignored.
Comparison to Other Formats
The info element is similar to the info element in DocBook 5, or to the various *info elements in DocBook 4, such as articleinfo, bookinfo, chapterinfo, and blockinfo.
The info element is similar to the prolog element in DITA. In Mallard, all metadata about a page or section is in the info element. It does not have a separate container child like the metadata element in DITA.
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 info element. The namespace declarations for this definition are on the page Pages.
mal_info = element info {
mal_info_attr,
mal_info_content
}
mal_info_attr = (
mal_attr_external *
)
mal_info_content = (
mal_info_desc ? &
mal_info_keywords ? &
mal_info_credit * &
mal_info_license * &
mal_info_link * &
mal_info_title * &
mal_info_revision * &
mal_external *
)