MEP-0005

Mallard provides multiple formal block container elements, such as figure, listing, and note. These provide base semantics that are suitable for most documents, and can be made more specific using style hints. Extensions can be used when these are not sufficient.

Mallard allows extensions to add elements to the core vocabulary with predictable fallback behavior. For block elements, the fallback behavior is to process the child elements as block, but ignoring unknown child elements. If an extension adds a formal element with a title, and this element is processed in fallback mode, the title is left dangling without a parent formal block element.

This page proposes adding a formal div element which can take an optional title element followed by any general block content. Pending MEP-0002: Block info Element, it may also contain a leading info element.

The processing expectations for div would be to process its block content as normal, with no expectation of extra visuals to show grouping. The title should look like a title, although without extra visuals, the extent of the text under the title may not be clear. Style hints may override the default rendering.

With this change, the specified fallback behavior should mention the div element. Block fallback behavior would be to process the element as if it were a div element, but processing the children in restricted block context.

Use div to provide a title for a paragraph.

<div>
  <title>Know Your Audience</title>
  <p>When writing, it is important to know who you're writing for.</p>
</div>

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>

This proposal makes no backwards-incompatible changes. Any page written in a version prior to the implementation of this proposal will work exactly the same in a processing tool that implements this proposal.

The fallback behavior for a new block element is that its child elements are processed as block elements, ignoring child elements that are unknown. How a child title element is processed is unclear. The aim of the div element is to make the fallback behavior more clear for other formal elements in the future.

DocBook has the formalpara element for adding a title to a paragraph without any additional semantics. The title is required, and it can only contain a single paragraph. There is no element to contain multiple blocks without additional semantics.

In DITA, the bodydiv and sectiondiv elements allow you to add multiple block elements without additional semantics. These elements do not allow a title, but the section element can be used to have a titled group with at least little additional semantics. Sections in DITA are lightweight block containers because sectioning is more often done by nesting topic elements.