The page element is the root element of any Mallard page file. In Mallard, documents are composed of discrete pages which are interlinked using various linking mechanisms. There are two types of pages in Mallard: guide pages and topic pages. Topic pages contain the bulk of the material discussed in a document, whereas guide pages serve as navigational aids.
The page element contains an optional info element, a title element, any general block content, and any number of section elements.
The page element is the top-level element in any Mallard page file, and cannot occur in any other elements.
The id attribute takes a unique identifier, which should match the base file name (without extension) of the file containing the page.
The type attribute takes the values "guide" and "topic". Guide pages and topic pages are discussed below. If the type attribute is omitted, it is assumed to be "topic".
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 page element can have attributes from external namespaces. See External Namespaces for more information on external-namespace attributes.
Guide pages have the type attribute set to "guide". They serve as navigational aids, linking to topics and other guides. Readers can browse through guides much as they would browse through container sections in a linear document. Since pages can be included in multiple guides, however, readers are able to reach the same content by navigating different paths.
Guide pages have links automatically inserted into their content based on topic links within their own info elements and guide links within the info elements of other pages and sections. Guide pages can contain sections to help organize content. Each section in a guide page has automatic links inserted as well. See Topic Links for details on automatic topic links.
Guides also have see also links generated automatically. See See-Also Links for more information.
Generally, guide pages will contain some introductory content to help readers understand the topics being presented. Introductory content should be short and concise.
Topic pages have the type attribute set to "topic", or have no type attribute at all. Topics contain the bulk of the material in a document. A Topic may be a tutorial, a conceptual overview, reference material, or any other type of content. Mallard does not distinguish between different content types, although tools may introduce special styling based on style hints. Topics are distinguished from guides only in that their primary purpose is to convey information, whereas guides serve as navigational aids.
Topic pages have links automatically inserted to all guides which link to them. Topic pages can contain sections to help organize material and present finer-grained chunks of information to the reader. Each section in a topic page has automatic guide links inserted as well. See Guide Links for details on automatic guide links.
Topics also have see also links generated automatically. See See-Also Links for more information.
In on-screen media, a page element is displayed as a single page. In this case, page is used in the sense of web page: something which can be read top-to-bottom by scrolling. This should not be confused with physical pages — one side of a leaf of paper — or with any fixed-height electronic pages such as those used by word processors and e-books.
The info child element is not displayed directly, although certain informational elements may be displayed or affect aspects of the page display. In particular, the info element may contain link elements which will cause automatic links to be inserted into the displayed output. See Dynamic Links for more information.
The title of a page is displayed prominently at the top, followed by any child block content, and finally by each child section. Note that automatic links, style hints, or other special features may insert material or change the way pages are displayed.
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 page element.
namespace local = ""
default namespace mal = "http://projectmallard.org/1.0/"
start = mal_page
mal_page = element page {
attribute id { xsd:NMTOKEN },
attribute type { "guide" | "topic" } ?,
attribute style { xsd:NMTOKENS } ?,
attribute groups { xsd:NMTOKENS } ?,
mal_attr_external *,
mal_info ?,
mal_block_title,
mal_block_subtitle ?,
mal_block *,
mal_section *
}