DITA Proposed Feature # 12021

A Proposal for nesting subsets of information

Longer description

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:

Statement of Requirement

DITA's architecture contains two primary container structures for organizing content:

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

The 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).

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

Use Cases

The following are a few high-level use cases where the bodydiv or sectiondiv is appropriate

Scope

The scope of the change to the current DITA architecture impacts two elements:

and would require moderate changes to the base topic DTD to support this proposal (approximately 4 hours).

Technical Requirements

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

New or Changed Specification Language

None

Costs

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.

Benefits

Both elements provide several potential benefits including: