1.2 (2019-02-09)
Divs
This is a draft specification. It is likely that changes will still be made before the final specification.
Use the div element to surround block elements without using any of the semantic block container elements. Divs may be used along with style hints to provide lightweight extensions or to provide information for localization and other tools. They also serve as the basis for formal block extensions.
Notes
The div element contains an optional info element, an optional title element, an optional desc element, and any general block content.
The div 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 div element can have attributes from external namespaces. See External Namespaces for more information on external-namespace attributes.
Examples
Use div to create a formal paragraph:
<div>
<title>Hello world</title>
<p>This is a paragraph about saying hello to the world.</p>
</div>Hello world
This is a paragraph about saying hello to the world.
Use div to group together block elements so you can transclude them as a whole, easing content reuse:
<div>
<p>Planting magic beans is fun and easy.</p>
<steps>
<item><p>Dig a hole 10cm deep.</p></item>
<item><p>Place magic beans in the hole.</p></item>
<item><p>Fill hole with fertilized soil.</p></item>
<item><p>Water frequently.</p></item>
</steps>
<note style="warning">
<p>Watch out for giants!</p>
</note>
</div>Planting magic beans is fun and easy.
Dig a hole 10cm deep.
Place magic beans in the hole.
Fill hole with fertilized soil.
Water frequently.
Watch out for giants!
Use div to mark multiple block elements as untranslatable using the Internationalization Tag Set:
<div xmlns:its="http://www.w3.org/2005/11/its" its:translate="no">
<p>This paragraph should not be translated.</p>
<code>// Neither should this code block.</code>
</div>This paragraph should not be translated.
// Neither should this code block.Use div as a generic container for UI expanders:
<div xmlns:ui="http://projectmallard.org/ui/1.0/" ui:expanded="false">
<info>
<title type="ui:collapsed">Click to say hello</title>
</info>
<title>Hello world</title>
<p>This is a paragraph about saying hello to the world.</p>
</div>Processing Expectations
Figures are displayed as block elements, with each of their child elements interpreted as block elements. When present, the title and description should be displayed in a way that makes their respective roles clear. There is no expectation of a visual indication of grouping. Style hints or extension attributes may override this.
The optional info element can provide metadata for the div, such as attributions, licensing information, and additional titles for extensions. It is not displayed directly.
Comparison to Other Formats
DocBook does not have a generic block container element with no semantics. The div element may be used in place of the DocBook formalpara element.
When used without a title as a grouping element, the div element is similar to the bodydiv and sectiondiv elements in DITA, although the div element is allowed in more places. When used with a title, the div element is similar to the DITA section element, which is a lightweight formal block container.
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 figure element. The namespace declarations for this definition are on the page Pages.
mal_block_div = element div {
mal_block_div_attr,
mal_info ?,
mal_block_title ?,
mal_block_desc ?,
mal_block_div_content +
}
mal_block_div_attr = (
attribute style { xsd:NMTOKENS } ?,
mal_block_attr,
mal_attr_external *
)
mal_block_div_content = mal_block