RE: [dita] Two proposals for nested sections

[Michael Priestley <mpriestl@ca.ibm.com>]

"Paul Prescod" <paul.prescod@blastradius.com>
wrote on 11/07/2005 07:14:02 PM:

> But it will make your life as spec editor much harder (as well as
> making the lives of readers harder). According to my understanding
> of the proposal, we would have to go through the entire DITA spec
> and everywhere it says "topic" (as in maps point to topics
through 
> "topicref" elements), we would have to say: "topic
or thingee" 
> (depending on what we call the thingees). 

We went through a similar change earlier changing
"topic type or map type" to "structural type". 

>The topicref attribute 
> would be a misnomer because it could point to topics or thingees.


It can already point to maps, PDFs, and websites,
so it's arguably already a misnomer. If necessary we can introduce a domain
specialization for <articleref>

> We'll have to add "thingee" to the "type" attribute.


I'm suggesting it will be a base type, same as map
and topic. And same as map and topic, when an element already exists in
topic, we could just keep the topic class attribute.

>What module 
> will the shared elements be in? That seems like a lot of painful 
> reworking to me. 

Since <article> would contain all the same elements
as topic plus some additional ones, the shared elements would be in the
topic module files (topic.mod etc.).

>It also implies that things with a certain 
> organization are "topics" (even if they nest deeply!) whereas
things
> with a slightly different organization (even if they have only one
> level of nesting) are not topics! They aren't articles. So I don't
> know what to call them.

This is the crux of our problem. I can propose all
the compromises I want, but you and I seem to fundamentally disagree on
the nature of a topic in DITA. So regardless of whether my proposal addresses
your immediate issue, I suspect you will not be satisfied with anything
short of changing the current definition of topic.

For me it comes down to how much control we put in
the hands of the map author versus the content author. On the one hand,
I want the content author to have considerable freedom in how they author
content: one per file or multiple per file, nested or flat, etc. On the
other hand I want the map author to have considerable freedom in how they
reuse and integrate content: whether it's in one file or many, nested or
flat etc. The topic is a handshake between the two formats: no matter how
complex the content gets, it will be consumable in topic-sized chunks that
have a maximum complexity determined by the limited nesting depth of topic.


The topic is also the unit of reuse in design and
processing, allowing for shared design elements and processing modules
at the topic level, across multiple complex document types and applications.

Changing the size of the basic unit of reuse - on
both the content, design, and processing dimensions - is not trivial. Adding
even one level of nesting increases the potential complexity of a topic
exponentially, with a corresponding decrease in the potential for reuse
across document type and system boundaries. Allowing unlimited nesting
destroys the entire idea of a topic, in the DITA architecture - the unit
of reuse becomes essentially unlimited in its complexity. 

I would rather simply preserve the existing architecture;
my compromise proposal is article as a peer of topic. You would rather
allow unlimited nesting of sections in topic; your compromise proposal
is to add one level of nesting. It sounds like neither of our compromises
is acceptable to the other. Perhaps the only thing we agree on is that
we disagree. I suspect we need input from others, and ultimately a decision
from the TC. 

Michael Priestley