OASIS Darwin Information Typing Architecture (DITA) TC

Ditabase and nesting of topic types

  • 1.  Ditabase and nesting of topic types

    Posted 01-23-2007 03:27
    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