Draft

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.html

Processing 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.

Comparison to Other Formats

The example element is similar to the example element in DocBook.

The example element is similar to the example element in DITA.

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