Draft

1.0 (2015-07-16)

Page and Section Markup

FIXME

Notes

  • Pages may optionally have any number of parser directives at the top, each starting with the @ character. See Parser Directives for details.

  • After directives, pages start with a page title on a line starting with an equals sign followed by a space.

  • Sections start with section titles, each on a line starting with two or more equals signs followed by a space. Section depth is determined by the number of equals signs. Sections end implicitly with new sections at the same or higher level.

  • A page and section title may optionally be followed by a subtitle on a line starting with hyphens followed by a space. The number of hyphens matches the number of equals signs used for the corresponding title.

  • Page and section titles are then followed by optional info elements, each on a line starting with the @ character. See Info Elements for details.

  • All other content is block content. See Block Elements for details.

Examples

Create a simple page:

= My Page Title

This is a paragraph.
<page xmlns="http://projectmallard.org/1.0/">
  <title>My Page Title</title>
  <p>This is a paragraph.</p>
</page>

Create a page with a subtitle:

= My Page Title
- My Page Subtitle

This is a paragraph.
<page xmlns="http://projectmallard.org/1.0/">
  <title>My Page Title</title>
  <subtitle>My Page Subtitle</subtitle>
  <p>This is a paragraph.</p>
</page>

Titles and subtitles can span multiple lines. Indent at least one space to keep following lines in the title or subtitle:

= This is a Very Long Title That
  Wraps onto the Next Line
- This is a Very Long Subtitle That
  Wraps onto the Next Line

This is a paragraph.
<page xmlns="http://projectmallard.org/1.0/">
  <title>This is a Very Long Title That Wraps onto the Next Line</title>
  <subtitle>This is a Very Long Subtitle That Wraps onto the Next Line</title>
  <p>This is a paragraph.</p>
</page>

Attribute lists for pages and section follow the title or subtitle, and start with at least one space followed by a left square bracket:

= My Page Title
  [style=tutorial]

This is a paragraph.
<page xmlns="http://projectmallard.org/1.0/" style="tutorial">
  <title>My Page Title</title>
  <p>This is a paragraph.</p>
</page>

Specification

A line that starts with an equals sign and at least one space is a page title. A line that starts with two or more equals signs and a space is a section title. There may only be one page title, and it must occur before any other block-level content. (Directives may come before the page title.)

Each following line is still part of the page or section title as long as the line is indented by at least one space and does not start with a left square bracket. The full title is the concatenation of all such lines, parsed as inline content.

A section title automatically creates a section at the correct depth. The number of equals signs that started the section title line is two greater than the number of ancestor section elements of the new section. The parser closes as many sections as necessary. It is an error if the new section is more than one level deeper than the current section.

Following a page or section title:

  • If the line begins with the same number of hyphen characters as the number of equals signs starting the title, followed by a space, then that line starts a page or section subtitle.

  • If the line starts with at least one space and then a left square bracket, then that line starts an attribute list for the page or section.

  • If the line starts with the @ character, possibly preceded by spaces, then that line begins an informational element.

  • Otherwise, regular block content begins.

A page or section subtitle immediately follows a title, and begins with the same number of hyphen characters as the title had equals signs, plus a space. Each following line is still part of the subtitle as long as the line is indented by at least one space and does not start with a left square bracket. The full subtitle is the concatenation of all such lines, parsed as inline content.

Following a page or section subtitle:

  • If the line starts with at least one space and then a left square bracket, then that line starts an attribute list for the page or section.

  • If the line starts with the @ character, possibly preceded by spaces, then that line begins an informational element.

  • Otherwise, regular block content begins.

An attribute list for a page or section follows the title or subtitle (but may not be between them) and starts with at least one space followed by a left square bracket. Note that the leading space is necessary to disambiguate from regular block content.

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