Listings

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

Use the listing element to create named listing of file contents or other content. Listings are usually used with code blocks to provide a name for the file to enter the content into. They may also be used to provide a name for an interactive shell session or any other type of content. To provide a title for images or other multimedia objects, use the figure element.

Notes

The listing element contains an optional info element, an optional title element, an optional desc element, and any general block content.
The listing element can occur in any general block context, including inside pages, sections, and certain block elements.
The style attribute takes a space-separated list of style hints. Processing tools should adjust their behavior according to those style hints they understand.
The listing element can have attributes from external namespaces. See External Namespaces for more information on external-namespace attributes.

Examples

Use listing to provide a file name and description for a code block:

<listing>
  <title><file>index.page</file></title>
  <desc>A first Mallard page</desc>
  <code><![CDATA[
<page xmlns="http://projectmallard.org/1.0/"
      type="guide"
      id="index">
  <!-- Content goes here -->
</page>]]></code>
</listing>

index.page

A first Mallard page

<page xmlns="http://projectmallard.org/1.0/"
      type="guide"
      id="index">
  <!-- Content goes here -->
</page>

Processing Expectations

Listings are displayed as block elements, with each of their child elements being interpreted as block elements. When present, the title and description should be displayed in a way that makes their respective roles clear.

The optional info element can provide metadata for the listing, such as attributions, licensing information, and additional titles for extensions. It is not displayed directly.

Comparison to Other Formats

There is no direct equivalent to the listing element in DocBook. The example element in DocBook is a formal element, and may be a suitable substitute for listing.

There is no direct equivalent to the listing element in DITA. The example element in DITA allows titles in mixed content, and may be a suitable substitute for listing.

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

mal_block_listing = element listing {
  mal_block_listing_attr,
  mal_info ?,
  mal_block_title ?,
  mal_block_desc ?,
  mal_block_listing_content +
}
mal_block_listing_attr = (
  attribute style { xsd:NMTOKENS } ?,
  mal_block_attr,
  mal_attr_external *
)
mal_block_listing_content = mal_block