MEP-0013

Top-level stack element

This page proposes a top-level stack element that contains page elements to make it easier to work on collections of pages.

Authors: Shaun McCance
Created: 2018-10-21
Status: incomplete (2018-10-21)
Target: 1.2
Issue: https://github.com/projectmallard/projectmallard.org/issues/17
History:
show history
hide history
history
2018-10-21 1.2 incomplete

This proposal is still under consideration. Revisions may still be made based on your input. Discuss this proposal on mallard-list.

Background

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.

Proposal

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.

Examples

This section is not yet written. Discuss this proposal on mallard-list.

Internationalization

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.

Compatibility and Fallback

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.

Comparison to Other Formats

This section is not yet written. Discuss this proposal on mallard-list.

© 2018 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