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 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