OASIS Darwin Information Typing Architecture (DITA) TC

I have a related use-case. I just finished porting an unstructured FrameMaker publication to DITA, and found that I had to fabricate several title-only topics to furnish xref targets. When it came time to integrate the HTML into the product's help system, I had to fabricate several more such topics to serve as context-sensitive help targets. The shell topics for context-sensitive help also required a collection-type of family so that the user would have something more than a title to look at when sent there. It would have been nice if the production system had been tasked with fabricating these topics from topicheads and applying the collection-type attribute to the fabricated topics when specified.

The only down-side I see with auto-generating title-only shell topics from topichead is that
 someone may prefer not to have a title-only HTML topic appear in the content-pane of frameset HTML ouput. It would be nice to be able to selectively suppress the output of the shell topic or at least the suppress TOC link (but not the TOC entry) to such a topic.

The presense of topicref attributes such as linking and collection-type in topichead seems to imply the generation of shell topics. If not, what possible use would these attributes have with topichead? I think that the 1.2 spec ought to convey some processing expectations for topichead.
 
Bob Thomas
Tagsmiths, LLC
+1 720 201 8260


From: Eliot Kimber
 <ekimber@reallysi.com>
To: dita <dita@lists.oasis-open.org>
Sent: Monday, January 26, 2009 12:33:10 PM
Subject: [dita] Cross References to Topicheads and Implicit Title-only Topics


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 <mailto:ekimber@reallysi.com>
office: 610.631.6770 | cell: 512.554.9368
2570 Boulevard of the Generals | Suite 213 | Audubon, PA 19403
www.reallysi.com <http://www.reallysi.com>  | http://blog.reallysi.com
<http://blog.reallysi.com> | www.rsuitecms.com <http://www.rsuitecms.com>


---------------------------------------------------------------------
To unsubscribe from this mail list, you must leave the OASIS TC that
generates this mail.  Follow this link to all your TCs in OASIS at:
https://www.oasis-open.org/apps/org/workgroup/portal/my_workgroups.php