Nested sections proposed compromise and call for use cases

["Paul Prescod" <paul.prescod@blastradius.com>]

Michael Priestly and I discussed this nested sections issue further last
week. We still don't agree on all of the design issues but we came up
with a compromise that both of us are tentatively happy with. Now we
would like to validate the compromise against other use cases to see
whether it holds up.

Michael felt it was very important that we strongly discourage
structures where you have many nested sections with titles authored by
writers. In his opinion, this puts too much control in the hands of
writers to write in an old-fashioned, non-topic-oriented fashion. For
example:

 * http://support.microsoft.com/kb/834489

Allowing this was never of interest to me (though, given my druthers, I
would not explicitly disallow it). My goal was not to put extra control
in the hands of the author, but in the hands of the specializer. For
example, one could imagine a specialization like this:

<kbarticle>
	<symptoms>...</symptoms>
	<resolutions><resolution><title>Hack your
registry</title>...</resolution>
		<resolution><title>Re-install
software</title>...</resolution>
		...
	</resolutions>
</kbarticle>

Each <resolution> would be a specialization of section. <resolutions>
itself would be a specialization of section (with a generated title).
The output might look like this (using this as a use case because it is
public -- not because I am working with support.microsoft on DITA):

	http://support.microsoft.com/kb/906294

(note that my variant of it is a bit more structured than this article
is)

The intersection between what I need and what Michael can stand is a
restriction that only one level should have authored (as opposed to
generated) titles.

The core of our proposal is an element called "bodydiv" (or perhaps just
"div"). This element will not allow an authored title. Specializations
may supply a generated title. (probably with a spectitle attribute?)
Bodydiv elements may contain sections. So <resolutions> could be a
bodydiv and <resolution> could be a section. Bodydiv elements may also
nest, so both could be bodydivs. (my thinking is that bodydivs should be
used when you don't want authors to supply titles and sections should be
used when you do: Michael probably does not agree and might prefer
people continue to use sections with or without titles as they do today)

When used without specialization, bodydiv is a pure grouping element:
the body-level equivalent of the "ph" element. It has no semantics other
than that it groups stuff. Authors could use that to conref or filter a
bunch of body-level things all at once.

If you need the grouping function within a section, then we propose
another element called <sectiondiv>. I find it harder to envision the
specialization-based use case for this element but for semantic-less
grouping within sections it could also be useful. For consistency,
sectiondivs would also be able to nest. Sectiondivs cannot contain
bodydivs so there is no way to achieve arbitrary authored-title nesting.

If someone did want to achieve arbitrary authored-title nesting (perhaps
for dealing with legacy content) then one could "hack" DITA to
specialize a paragraph into a bodydiv title. (you can hack DITA in
similar ways today)

Please compare this compromise to your use cases and report back on
whether it meets your needs.

 Paul Prescod