Examples

This specification has been replaced by Mallard 1.1.

Use the example element to place block elements into a logical group, indicating that they are part of a single example. This may be used to group example input with its result, to show different steps with different types of block elements, or simply to group some paragraphs together.

Notes

The example element can contain any general block content.
The example 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 example element can have attributes from external namespaces. See External Namespaces for more information on external-namespace attributes.

Examples

Use example to show how to use the screen element, grouping the input and formatted result:

<example>
<code><![CDATA[
<screen>
xsltproc -o mal_block_screen.html \
  --stringparam mal.cache.file `pwd`/mallard.cache \
  `pkg-config --variable mal2html gnome-doc-utils` \
  mal_block_screen.html
</screen>
]]></code>
<screen>
xsltproc -o mal_block_screen.html \
  --stringparam mal.cache.file `pwd`/mallard.cache \
  `pkg-config --variable mal2html gnome-doc-utils` \
  mal_block_screen.html
</screen>
</example>

<screen>
xsltproc -o mal_block_screen.html \
  --stringparam mal.cache.file `pwd`/mallard.cache \
  `pkg-config --variable mal2html gnome-doc-utils` \
  mal_block_screen.html
</screen>

xsltproc -o mal_block_screen.html \
  --stringparam mal.cache.file `pwd`/mallard.cache \
  `pkg-config --variable mal2html gnome-doc-utils` \
  mal_block_screen.html

Processing Expectations

The contents of an example element are each rendered as block elements as normal. Processing tools should use margins, borders, or other styling effects to provide a clear visual indication of the grouping.

Comparison to Other Formats

The example element is similar to the example element in DocBook. In DocBook, the example element is a formal element. In Mallard, example is a simple container element, and does not allow a title element.

The example element is similar to the example element in DITA. In DITA, the example element is a specialization of the section element. It contains a title and is used in contexts where sections are permitted. The example element in Mallard is more lightweight, and is designed to be used in general block contexts.

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

mal_block_example = element example {
  mal_block_example_attr,
  mal_block_example_content +
}
mal_block_example_attr = (
  attribute style { xsd:NMTOKENS } ?,
  mal_block_attr,
  mal_attr_external *
)
mal_block_example_content = mal_block