Ditabase and nesting of topic types

["W. Eliot Kimber" <ekimber@innodata-isogen.com>]

The language reference mentions "composite file" and "ditabase" with no 
definition of either (other than the implicit connection to the database 
declaration set). It never makes an explicit connection between these 
two terms and the "dita" element except in the description of the dita 
element itself. For example, if you're reading the description of 
glossentry and trying to figure out why it's mentioning "composite 
files" and the special rules for them, there's nothing there that will 
get to you the "dita" element. Doh!

Likewise the architecture document mentions the ditabase document type 
and shows declarations with the "composite" public identifier and talks 
about how within composite documents topics can be nested without 
restriction, but it never says *why* or mentions the "dita" element 
(except in examples where it's use is not discussed or explained and has 
no obvious purpose, such as the examples under "Usage with the conref 
attribute").

Several comments:

1. The term "file" is not a meaningful XML term--either the term 
"document" or "storage object" should be used. In addition, the term 
"composite document" usually has another meaning in a lot of contexts, 
namely a logical document composed from multiple physically-distinct 
components (e.g., via XInclude), so I think there's likely to be 
confusion, or at least assumption that it means more than it does. In 
fact, the term "composite file" as it's used here explicitly *has no 
meaning* because it has no processing implications at all--it is simply 
a storage organization convenience. I think a clearer term might be 
something like "multi-topic document" (although that's somewhat 
ambiguous because it could mean a document with a topic root that has 
nested topics). Unfortunately, the most correct term, namely "dita 
document" (meaning a document whose document type is "dita"), is 
ambiguous with the more usual meaning of "a document that conforms to 
the DITA specification". Maybe it would be best to change the name of 
the "dita" element to something like "topicset" that is a much clearer 
reflection of what it actually is.

Unfortunately, if my clients and prospects are any indication, there are 
a lot of documents of the form <dita><topic></topic></dita> out there 
(which is of course totally unnecessary and pointless). But maybe we can 
add "topicset" and depricate "dita". This wouldn't break anything 
existing but would make the whole subject a lot clearer and easier to 
talk about.

2. It's not clear *why* it's useful to allow arbitrary nesting of topics 
in the context of "dita" elememnts but not, by default, in the elements 
when used standalone. I can only see it causing confusion, especially 
when a topic containing mixed subtopics was subsequently re-used in a 
context where mixed subtopics are not allowed (that is, any other context).

3. If this distinction was *not* made there'd be no *syntatic* need for 
ditabase to be a separate document type (it's only required now because 
there are different effective values for the info-types parameter 
entity). Actually, now that I think about it, having a generic 
"info-types" parameter entity that is used in the content models of all 
topic types seems like a bad idea--it leads to exactly this problem with 
no particular value that I can see.

Hmmm.

The "dita" (or "topicset") element is needed but I don't see that it 
needs to do anything other than allow any topic type as its direct 
child--there's no obvious benefit to allowing unconstrained nesting.

Cheers,

Eliot

-- 
W. Eliot Kimber
Professional Services
Innodata Isogen
8500 N. Mopac, Suite 402
Austin, TX 78759
(214) 954-5198

ekimber@innodata-isogen.com
www.innodata-isogen.com