A mechanism for allowing topics and specializations of topic to have lightweight nested structures.
DITA provides two basic mechanisms to group information
Currently, there are no built-in mechanisms within DITA to further subdivide content subsets into smaller groups of information smaller than a section, or to group sections into a container smaller than a topic.
To solve this problem, two elements are proposed for DITA 1.2:
bodydivsectiondiv
DITA's architecture contains two primary container
structures for organizing content:
topicsection
Topics are the primary container for information and designed for
reuse. Within topics, information designers can organize subsets of information within
a topic using sections. Content within sections are implicitly
subgroups of information that is not intended to stand alone as single, reusable
pieces of information. For example, a command synopsis, or description
within a manpage reference is only relevant in the context of the command reference
it is written for.
Because sections are only intended to be a subset of information, these are intentionally "flat" to prevent unwarranted nesting of content that would better be managed through the use of topics and maps.
From a specialization perspective, however, the inability to subdivide sections into smaller subsets of information or to group section into logical containers without the "heavyweight" mechanics of a topic has proven to be a limitation for some types of information and for specializers because sections do not allow recursive "sub-sections." For example, a knowledge base article found on a support website:
<kbarticle>
<title>Support Issue</title>
<symptoms>
<symptom>
<title>...</title>
</symptom>
<symptom>
...
</symptom>
</symptoms>
<resolutions>
<resolution>
<title>Check your log file</title>
...
</resolution>
<resolution>
<title>Re-install software</title>
...
</resolution>
...
</resolutions>
</kbarticle>
Each symptom and resolution could be specializations of
section. However, there is no mechanism currently within DITA to group
these sections into logical semantic groups (i.e., there is no way to create a container
element called <symptoms> or <resolutions>).
bodydiv Element
The bodydiv element is a body-level
element used to contain informal blocks of infromation.
The bodydiv element can contain both phrase-level (e.g., ph,
b, etc.) and block-level content (e.g., p, table, etc.),
and sections. The bodydiv element can also be nested
and can also contain nested div elements.
The bodydiv element is specifically designed to be a grouping element, without
any explicit semantics, other than to organize subsets of content into logical groups
that are not intended or should not be contained as a topic. As such, it shall not
contain an explicit title to avoid enabling the creation of deeply
nested content that would otherwise be written as separate topics).
sectiondiv
To enable logical grouping of content within a section, the
sectiondiv element may be used in a similar fashion as
the bodydiv element.
In this scenario, the section element is used as formal container
with the ability to contain nested informal blocks of information within. However,
it cannot contain formal (titled) sections.
The following are a few high-level use cases where the bodydiv or
sectiondiv is appropriate
<body id="my.logical.block">
<p>...</p>
<ul>
<li>....</li>
</ul>
<bodydiv id="nested.logical.block">
...
</bodydiv>
...
</div>
------------
...
<bodydiv conref="my-other-topic.xml#my.logical.block"/>
The scope of the change to the current DITA architecture impacts two elements:
bodysectionTwo new element definintions would need to be created. The following pseudo-code illustrates the basic nature of the content models for each element:
<!ELEMENT bodydiv (#PCDATA | %inline.content.mix | %block.content.mix | bodydiv | section)* >
<!ELEMENT sectiondiv (#PCDATA | %inline.content.mix | %block.content.mix | sectiondiv)* >
Additionally, two existing elements would need to be modified:
<!ELEMENT body (%body.cnt; | %section; | %example; | bodydiv)* >
<!ELEMENT section (%section.cnt; | sectiondiv)* >
To ensure backward compatibility with earlier DITA versions, both the
bodydiv and sectiondiv elements
should be optional elements within their respective parent content models
to ensure that legacy content will not become invalid with these changes.
None
The costs for implementing this proposal should be relatively minimal
for DITA implementations. In most cases, the rendering expectations for
both elements should be treated as a block element, similar a
div element in HTML. Specializations may treat
these elements as a way to autogenerate a title based on the
implied semantics of the specialization.
Both elements provide several potential benefits including: