OASIS Darwin Information Typing Architecture (DITA) TC

  • 1.  Comments on Glossary elements section

    Posted 01-23-2007 02:55
    I find the glossary elements slightly confusing.
    
    The first sentence of the introductory paragraph is:
    
    "Use the glossary topic type to define terms."
    
    However, there is no glossary topic type, only the glossary entry topic 
    type. I think this should read "Use the glossary entry topic type to 
    define terms"
    
    Under "contained by" for glossentry, there is this statement:
    
    "When used in a glossary topic on its own, the glossentry element cannot 
    be contained by anything."
    
    This sentence doesn't make sense to me--the phrase "used in" isn't well 
    defined--does that mean organized hierarchically via a map relative to 
    another topic? I can't think of any other way that a topic can be "used 
    by" another topic but not be literally nested within it.
    
    In any case, it's a pointless constraint since the whole point of DITA 
    is that topics can be organized for storage without regard to how they 
    are combined into packages via maps.
    
    Or have I just totally missed something non-obvious about glossentry topics?
    
    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
    
    


  • 2.  Re: [dita] Comments on Glossary elements section

    Posted 01-23-2007 15:10
    Hi Eliot -
    
    One complaint that several reviewers submitted was that the
    contains/contained by was not accurate, depending on whether they were
    looking at a topic in the ditabase context or in one of the other main
    topic types. The comment was most often received about the topic types,
    though it also applies to body elements (section can be in body, conbody,
    or refbody when inside ditabase, but only in one of those when in the OASIS
    reference type).
    
    For the current draft of the language reference, I put in the ditabase
    content model. I considered putting in all of the models: "When in an OASIS
    Ditabase, you will see this. When in an OASIS topic or concept, you will
    see this." However, that would really blow up the size of the reference.
    So, I put in the wording you will see in many places about the model
    differing slightly. Even that is not great, because as you point out the
    statement is only accurate with regards to the OASIS doctypes. That is
    really the best we can do though, if we are going to list the
    contains/contained by at all.
    
    Do you (or anybody else) have any better wording for the glossentry
    element, or for the common text that appears with elements like 

    ? For glossary, I could change the text to something like this: In the OASIS Composite document type, the glossentry element can be contained by other topic types (topic, concept, task, reference), and by the dita element. In the OASIS glossentry topic type, the glossentry element cannot be contained by any other element. Like other topic types, this model may differ when the glossary module is used in new document types. Related to this and to your other note - one open item from Jeff Ogden's original review of the language reference is to use the same wording everywhere for composite, ditabase, and the other terms that are used for the