Draft

1.2 (2019-02-09)

Pages

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

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.

Notes

  • The page element contains an optional info element, a title element, an optional subtitle element, any mixture of general block content and links elements, any number of section elements, and any number of links 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 specifies the page type, which affects processing. Types defined by this specification are "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.

Examples

Create a very basic Mallard page:

<page xmlns="http://projectmallard.org/1.0/" id="index">
<title>A Simple Page</title>
</page>

Pages are topic pages by default. Create a guide page instead:

<page xmlns="http://projectmallard.org/1.0/" type="guide" id="index">
<title>A Simple Guide Page</title>
</page>

Add an introductory paragraph:

<page xmlns="http://projectmallard.org/1.0/" type="guide" id="index">
<title>A Simple Guide Page</title>
<p>This is a paragraph</p>
</page>

Guide Pages

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.

In addition to other types of automatic links, guide pages have topic links inserted. See Topic Links for details.

Topic Pages

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.

Processing Expectations

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 Automatic 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.

All pages may have links inserted automatically based on informational links found on in pages and sections throughout the document. See Automatic Links for details.

Comparison to Other Formats

The page element is similar to the topic element introduced in DocBook 5.1. Previous versions of DocBook did not have a topic container element. Articles or books written in DocBook were sometimes chunked into pages. Compared to those documents, the page element may be used in place of division elements like book, article, and chapter.

The page element is similar to the topic element in DITA. DITA allows specializations of the topic element, such as the concept, reference, and task elements. Mallard does not use the same specialization mechanism. Style hints may be used to indicate semantic distinctions for validation or formatting. For substantial functional differences, different page types should be introduced.

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 page element.

namespace local = ""
default namespace mal = "http://projectmallard.org/1.0/"
start = mal_page
mal_page = element page {
  mal_page_attr,

  mal_info ?,
  mal_block_title,
  mal_block_subtitle ?,
  ( mal_block | mal_links ) *,
  mal_section *,
  mal_links *
}
mal_page_attr = (
  mal_page_id,
  attribute type { xsd:NMTOKEN } ?,
  attribute style { xsd:NMTOKENS } ?,
  mal_attr_version ?,
  mal_attr_external *
)
mal_page_id = attribute id { xsd:NMTOKEN }
© 2008-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