Draft

1.2 (2019-02-09)

Block Elements

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

Block elements are the building blocks of pages. Mallard provides block elements for most common needs in software documentation, from simple paragraphs to example blocks to powerful tables. Pages and sections in Mallard are built up of block elements, which in turn contain either further block elements or inline content.

Authors, editors, or other content producers sometimes need to supply richer information in their documents. While this information may not be conveyed by display tools, it may be used for various internal tracking purposes. Mallard allows elements to be extended with attributes from external namespaces. See External Namespaces for more information.

Basic Elements

Basic block elements are elements that do not contain a title and which have either general block content or inline content. Using basic block elements, you can build up simple pages which convey information clearly.

Code Blocks — Mark up a block of code or the contents of a file.

Multimedia Objects — Insert an image, video, or other multimedia object.

Paragraphs — Create a simple paragraph of text.

Screens — Mark up a text-based user interface or an interactive shell session.

Formal Elements

Formal block elements contain a title and general block content. Formal block elements allow you to provide richer information in your pages.

Block Quotes — Create a block-level quotation with an attribution.

Divs — A generic formal block element that can be used for semantic, localization, and styling purpose.

Editorial Comments — Include an editorial comment that's hidden from normal readers.

Examples — Mark a group of block elements as being part of a single example.

Figures — Provide a title or caption for a multimedia object.

Listings — Provide a name and description for a code block or other content.

Notes — Include notes, tips, warnings, and other parenthetical information.

Synopses — Create an overview of concepts.

List Elements

Mallard provides list elements for most common needs, including the common definition, ordered, and unordered lists. Mallard also provides simple trees, which are useful for representing hierarchies such as class inheritance or directory layouts. Each of the list elements uses the item element, though the content model for item varies. See the list element pages for details.

Basic Lists — Create a basic bulleted or numbered list.

Step Lists — Create a list of steps the reader should perform to accomplish a task.

Term Lists — Create a list of terms and associated descriptions.

Tree Lists — Create simple trees to show hierarchical structures.

Tables

Mallard provides a simple table model based on HTML tables. While not allowing the level of styling flexibility as HTML and CSS, Mallard tables provides simple solutions to common styling needs, such as alternate-row shading.

Tables — Arrange data into rows and columns.

Columns and Column Groups — Define columns groups for rules and shading.

Rows and Row Groups — Create rows and row groups for tables.

Table Cells — Create cells in table rows.

Other Block-like Elements

Mallard contains various block-like elements which are only used in specific contexts, and are not allowed in general block content. These elements allow for richer content models for the elements they appear in.

Titles — Provide a title for a page, section, or block element.

Subtitles — Provide a subtitle for a page or section.

Block Descriptions — Provide a caption for a formal block element.

Citations — Provide attributions for quotations and comments.

Processing Expectations

Block elements all begin on a new line in rendered output. Pages can be visualized as a sequence of vertically-stacked block elements. Some block elements contain other block elements. In these cases, the containing element may introduce certain styling effects, and each of the child elements is rendered as normal.

Each block element should be clearly distinguishable from its surrounding block elements. Typically, vertical padding is placed between block elements to set them apart. Certain block elements, especially those that have block content, may use a border, background color, or other styling effects. See each block element's specification for more details.

Mallard allows elements from external namespaces to be used in any block context. Processing tools may have special behavior for particular elements they understand. If a processing tool does not understand an element in block context, it should process the children of the element as if they were block elements, except it should ignore any child elements it does not understand. This restricted block context allows extensions to have any content model while still providing a standard mechanism for fallback content.

Sometimes extension block elements will use title or desc elements. Processing tools should process title and desc elements as if the unrecognized block element were a div element, processing other child content in restricted block context.

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 block content model. The namespace declarations for this definition are on the page Pages.

mal_block = (
  mal_block_elements |
  element * - (mal:* | local:*) {
    attribute * { text } *,
    ( mal_external * &
      mal_block_elements *
    )
  }
)
mal_block_elements = (  
  mal_block_code |
  mal_block_comment |
  mal_block_div |
  mal_block_example |
  mal_block_figure |
  mal_block_list |
  mal_block_listing |
  mal_block_media |
  mal_block_note |
  mal_block_p |
  mal_block_quote |
  mal_block_screen |
  mal_block_steps |
  mal_block_synopsis |
  mal_block_terms |
  mal_block_tree |
  mal_table
)
mal_block_attr = empty