OASIS Darwin Information Typing Architecture (DITA) TC

Cross References to Topicheads and Implicit Title-only Topics

  • 1.  Cross References to Topicheads and Implicit Title-only Topics

    Posted 01-26-2009 19:34
    There is an issue that came up in the context of the Accounting Standards
    Codification (ASC) DITA application (asc.fasb.org).
    
    The issue is that the codified GAAP uses a taxonomy with several levels
    (Topic, Subtopic, Section, Subsection) but the Topic, Subtopic, and Section
    levels have no direct content--only Subsections have content.
    
    In the DITA source for the ASC everything above Subsection is represented
    only by topic heads--there are no separate title-only topics for the topic
    heads.
    
    However, there is a need to create cross references from subsection content
    to Topics, Subtopics, and Sections. They have done this by creating xrefs to
    the topicheads in the maps, since there was nothing else to point to.
    
    This question came to be in the form of "what value do we specify for type=
    when the target is a topichead". My response was to leave it unspecified,
    because either the effective referent type is processing-defined or it is
    implicitly a topic.
    
    I could not find anything in the DITA 1.1 spec that addressed this case
    explicitly.
    
    My questions: 
    
    1. Was my analysis correct?
    
    2. If so, does the DITA 1.2 spec need to say anything explicit about this
    case?
    
    I think it probably does, in that there's a general issue around the fact
    that topic heads imply the existence of title-only topics. I think it would
    be appropriate for the DITA spec to say explicitly that topicheads are
    functionally identical to the equivalent topicref/title-only-topic pair and
    therefore it should never be necessary to explicitly author title-only
    topics and topicrefs.
    
    If it doesn't say this then I think we need to say explicitly what it means
    to xref to a topichead in a map or say that the result is entirely processor
    defined.
    
    I guess the other way to ask this question is: is there a use case where you
    would want different behavior for topicheads than for
    topicref/title-only-topics? Note that in both the XHTML and PDF2 processors,
    you do get different effects.
    
    In thinking about it, and about topic heads in general, I think that the
    only thing that makes sense is that an xref to a topichead is an implicit
    link to the title-only topic implied by the topichead.
    
    This is sensible because a processor can always unambiguously generate
    title-only topics for every topic head and the result will be
    indistinguishable from an input data set in which the topicheads are replced
    by topicref/title-only-topic pairs (this doesn't have to be a literal
    generation but in the case of the DITA Open Toolkit that would be the most
    natural way to implement the effective behavior).
    
    If this behavior were to be codified (simply by adding language to xref or
    wherever it needs to be to say what I just said here) there could be a
    potential for interference with the new keyref facility, as with keyref it
    is meaningful to xref (or at least conref) to topicheads where those heads
    are providing text values. We would just need to be careful that it is
    always clear what type of reference is meant and, if necessary, define
    additional values for "type=" on xref to make the author intent clear.
    
    Cheers,
    
    E.
    ----
    Eliot Kimber | Senior Solutions Architect | Really Strategies, Inc.
    email:  ekimber@reallysi.com