Thoughts On Sections

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

On last week's call we discussed several different approaches to
sections. My personal opinion on the current section element is that
they are simultaneously too strict and too loose. We've discussed at
length the sense in which they are too loose: they do not provide any
guidance for authoring and overlap almost exactly with the content model
of paragraph.

On the other hand, sections are more strict than HTML "DIV" elements in
a very important way: they cannot be nested. Some of our customers have
a need for "grouper sections" that can wrap up other sections in their
specializations. Basically their topics are not necessarily flat. For
privacy reasons I'll make up an example structure:

Part Description
	Subparts
		Subpart 1 description
		Subpart 2 description
		Subpart 3 description
	Use contexts
		Context 1 description
		Context 2 description
		Context 3 description

The customer sees the "Part Description" as the topic level because the
subparts are meaningless to the reader out of context of the parent.

Therefore I feel that in the loose, designed-to-be-specialized base DITA
topic type, sections should be nestable. Another key reason to allow
sections to nest is to have a body-level container that can serve the
"generic wrapper" role that phrases do at the inline level. Generic
wrappers are useful as a basis for specialization, as a place to put
filtering attributes and as a way to logically conref a set of content
elements at once.

I propose short-term and long-term directions for sections:

DITA 1.1: they should be loosened to be generic wrappers that can nest.

<!ENTITY % section.cnt "(#PCDATA | %basic.ph; | %basic.block; | %title;
|  %txt.incl; | section)*">

DITA 2.0: they should be tightened to be generic wrappers _of body
elements_ with zero or one titles and no PCDATA.

<!ELEMENT % section.cnt "(title? , %basic.block;)">

If we could agree on this direction then we wouldn't need a new
structured-section element. But if it is important that section have
basically the same content model as paragraph plus titles (I'm not sure
why) then we probably do need structured-section.

 Paul Prescod