MEP: Generic div element

Proposal attached as page. Ducktype version inline below.


= MEP-XXXX
- Generic &code(div) element

This page proposes adding &code(div) as a formal block
container element to allow better integration for extensions.


== Background

Mallard provides multiple formal block container elements, such as
&code(figure), &code(listing), and &code(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.


== Proposal

This page proposes adding a formal &code(div) element which can take an
optional &code(title) element followed by any general block content.
Pending &link[>mep0002], it may also contain a leading &code(info)
element.

The processing expectations for &code(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
&code(div) element. Block fallback behavior would be to process the
element as if it were a &code(div) element, but processing the children
in restricted block context.


== Examples

Use &code(div) to provide a title for a paragraph.

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

Use &code(div) to group together block elements so you can transclude
them as a whole, easing content reuse.

[example]
[code]
<div>
  <p>Planing 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>


== Compatibility and Fallback

This proposal makes no backwards-incompatible changes. That is, 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 &code(title) element is processed is unclear. The
aim of the &code(div) element is to make the fallback behavior more
clear for other formal elements in the future.


== Comparison to Other Formats

DocBook has the
&code[>>http://docbook.org/tdg51/en/html/formalpara.html](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
&code[>>http://docs.oasis-open.org/dita/v1.2/cd03/spec/langref/bodydiv.html](bodydiv) and &code[>>http://docs.oasis-open.org/dita/v1.2/cd03/spec/langref/sectiondiv.html](sectiondiv) elements allow you to add multiple block elements without additional semantics. These elements do not allow a title, but the &code[>>href="http://docs.oasis-open.org/dita/v1.2/cd03/spec/langref/section.html](section) 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 &code(topic) elements.

-------------- next part --------------
A non-text attachment was scrubbed...
Name: mep-div.page
Type: text/x-mallard-page+xml
Size: 5416 bytes
Desc: not available
URL: <http://projectmallard.org/pipermail/mallard-list/attachments/20141109/97161866/attachment.bin>