MEP-0013

Mallard documents are collections of pages, with various types of semantic links between pages creating the navigational structure. Sometimes a set of pages are closely related, and it would be useful to be able to work on them as a single unit and easily express links amongst them.

This page proposes adding a top-level stack element. Files that use a stack element should have the .stack extension instead of the .page extension. A stack element contains one or more page elements, which have the same data model as if they were top-level elements.

A stack element may have a type attribute and a style attribute. This proposal recognizes two values for the type attribute: set and series. The default is set and carries no additional semantics. A stack with the type attribute set to series defines a series. In a series, each page in the stack has an implicit next-type link to the following page, overriding any next-type links explicitly defined in the info elements of the pages.

A stack element may start with an info element with the same content model as the info element on page elements. The credit, license, and revision elements apply to each page in the stack. The title and desc elements do not apply to the pages, but if the series has a title element with type="series", it is used as the default title for any series-type links elements in the pages.

How informational link elements are handled may depend on the link type. Further discussion is required.

Stacks do not present any new difficulties for internationalization. However, some translation tools may need to update their ITS rules or other definitions to account for a different top-level element.

This proposal makes no backwards-incompatible changes. Any page written in a version prior to the implementation of this proposal will work exactly the same in a processing tool that implements this proposal.

There is no defined fallback behavior for a new top-level element, or for a file with a different extension. A stack file will simply be ignored by any tool that implements a version of Mallard prior to this proposal being implemented.