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.

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.

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.

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.

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
© 2008-2009 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