1.2 (2019-02-09)
Examples
This is a draft specification. It is likely that changes will still be made before the final specification.
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 contains an optional info element, an optional title element, an optional desc element, and 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.htmlProcessing Expectations
Examples 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. Processing tools should use margins, borders, or other styling effects to provide a clear visual indication of the grouping.
The optional info element can provide metadata for the example, such as attributions, licensing information, and additional titles for extensions. It is not displayed directly.
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_info ?,
mal_block_title ?,
mal_block_desc ?,
mal_block_example_content +
}
mal_block_example_attr = (
attribute style { xsd:NMTOKENS } ?,
mal_block_attr,
mal_attr_external *
)
mal_block_example_content = mal_block