[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]
Subject: Ditabase and nesting of topic types
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
[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]