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