RE: [dita] Nested Sections Solution Proposal

A mechanism for allowing topics and specializations of topic to have lightweight nested structures.

Longer description

Many topics have an internal narrative structure that is analogous to sections within a book chapter or help topic. DITA has two mechanisms for dealing with this situation. One is to use sections. This mechanism breaks down if the required hierarchy is more than one level deep. The second mechanism is to use sub-topics. This mechanism is "heavy-weight" in a few different ways:

Topics must have authored titles rather than specialization-specified ones ("spectitles").
Topics must always have titles: sometimes neither authored nor generated titles are required (see the "output-transparent grouping" use case below)
Topics must always have IDs.
Topics require an extra layer of "body" wrapping that differentiates between metadata and content: even when metadata is either not needed or explicitly disallowed through specialization.
Acccording to some definitions of "topic", making content into a sub-topic has certain unwanted semantic implications like: "This content is independently reusable" or "this content should be independently indexed by CMS search engines".
Topics can only be grouped by other topics with all of the issues described above. Topics cannot be grouped by sections.
The output behaviours for subtopics are typically quite different from those for sections. E.g. with respect to HTML chunking and locations of related-links elements.

This proposal defines mechanisms for lightweight, hierarchical, sectional grouping.

Scope

Intermediate

Use Cases

Complex Specialized Templates: Imagine if the document type for DITA Proposed Features were a specialization. It would likely have elements like "Longer Description", "Use Cases", "Technical Requirements" and so forth. For the sake of clarity, lets call these specialization-defined sections "schematic sections". In contrast, sections with titles and semantics totally under the control of authors will be called "author-defined sections". It seems quite possible that under many circumstances, these schematic sections will require author-defined subsections or schematic sub-sections. For example, the use case you are reading right now might be within a sub-section (perhaps a specialized "Use Case" section type) rather than a definition list if that were possible. Because the output-requirements for this document type are so lax, we can get away with using a definition list. But sometimes customers really do require "section behaviour" for sub-sections.
Output-transparent Grouping: Sometimes it is necessary to group multiple sections and other content into a single unit in order to "conref" them or filter than all together.

Anti-Use Cases

The proposal is not meant to address situations where authors wish to create deeply nested topics with many levels of titles. They should use nested topic features to do that.

Technical Requirements

The proposal is the addition of two elements. One, "bodydiv" or "div" would be able to contain sections and other body-level elements. The other, "sectiondiv" would be contained by sections and contain body-level elements. Neither type would allow authors to write titles. Both types would have optional "spectitle" attributes that would behave the same as the equivalent attribute on sections.

Here is an example of the "bodydiv" element:

<body> 
<p>Got some stuff to say</p> 
<bodydiv> 
<p>A logical grouping of content within a body - a
specializer could use this to generate a title, but there's no
facility for the author to define a topic-like or unique
title.</p> 
<section> 
<title>A</titke> 
<p>etc.</p> 
</section> 
<section> 
<title>B</titke> 
<p>etc.</p> 
</section>
<bodydiv>
<p>A nested bodydiv.</p>
</bodydiv> 
</bodydiv> 
<bodydiv> 
<p>Another bodydiv</p>
</bodydiv>
</body>

Here is an eample fo the "sectiondiv" element:

<section> 
<title>stuff</title> 
<p>etc.</p> 
<sectiongroup> 
<p>A logical grouping of content within a section - a
specializer could use this to generate a title, but there's no
facility for the author to define a topic-like or unique
title.</p> 
<p>etc.</p> 
</sectiongroup>

Costs

The DTD changes required to allow this are minor. Basically two new element definitions are required. They are not particularly complex elements and are almost the same as sections.

The implementation changes are relatively minor as these elements can be treated as a variant of section elements.

The largest long-term cost is the incremental bloat to the DITA language itself. DITA is already a large language, so the addition of new elements should be carefully considred.

Benefits

As per the introduction, the benefit is the ability to create section-nested content without the overhead and mismatched content model of nested topics. It is hard at this time to determine how many people are bothered by the issues with nested topics.

Time Required

The technical time to implement is relatively small: on the order of a day. The submitter feels that there are still some open issues with respect to defining best practices for using this feature versus using nested topics. It may take a further few meetings to work through these issues.

dita message

DITA Proposed Feature # 00