“KWARC was!”

When I was at the WritersUA conference before easter, the compatibility (and transformation) between DITA (as a topic-centered format) and DocBook (as a narrative one) was one of the topics with wider interest. In OMDoc we have always maintained that we can follow both the topic-centered approach (which is quite natural for mathematical texts and indeed for wiki-based approaches like the one in SWiM) as well as the narrative one. So I got thinking how we would really do the topic-centered approach in OMDoc.

When I was reading Christine Müller’s Ph.D. thesis that looked a the integration of topic-based and narrative writing styles, I noticed that she says that OMDoc does not have support for topic-style writing. I think that this is wrong. Taking her example (slightly simplified)

<concept id="A.dita">
 <title>Natural Numbers</title>
 <conbody>
 <p>The set of <term>natural numbers</term>
 defined <cite>here</cite> or in <xref href="nat.dita#nat1"/>.
 </p>
 <para conref="topic/p2"/>
 </conbody>
 <related-link>http://example.com/nats.html</related-link>
</concept>

it is obviously directly  expressible in OMDoc as

<omdoc>
 <omgroup type="concept" xml:id="A.dita">
 <metadata>
 <dc:title>Natural Numbers</dc:title>
 <link rel="dita:related-link" resource="http://example.com/nats.html"/>
 </metadata>
 <omgroup type="conbody">
 <omtext&gt
 <CMP>
 <p>The set of <phrase role="term">natural numbers</phrase>
 defined <cite>here</cite> or in <ref type="cite" href="nat.dita#nat1"/>.
 </p>
 </CMP>
 </omtext>
 <ref href="topic/p2" type="include"/>
 </omgroup>
 </omgroup>
</omdoc>

(again slightly simplified; I am leaving out the relevant namespace declarations). It should be directly obvious that we can define an OMDoc sublanguage that is isomorphic to DITA. Indeed I think that this is an exercise that would be worth doing. After all, there was a message from Bryce Nordgren  about opening oup a Math domain in DITA (see http://openmath.org/pipermail/om/2009-February/001203.html for details), which could use this isomorphism as a guiding light.

Of course DITA not only has topics, but also topic maps, let me again use an example from Christine’s thesis.

<map title="title">
 <topichead navtitle="navi-title" audience="math"/>
 <topicref href="A.dita" collection-type="sequence">
 <topicref href="A1.dita"/>
 <topicref href="A2.dita"/>
 </topicref>
 <reltable>
 <relrow>
 <relcell>A.dita</relcell>
 <relcell>B.dita</relcell>
 </relrow>
 </reltable>
</map>

The first part of this map is just what we have always thought of as a narrative structure in our NarCon approach in OMDoc. So we can directly represent it as something like

<omdoc>
 <metadata>
 <dc:title>title</dc:title>
 <link rel="dita:audience" resource="something:math"/>
 <link rel="dita:navtitle" resource="navi-title"/>
 </metadata>
 <omgroup xml:id="A.narrative" type="sequence">
 <ref type="include" href="A1.omdoc"/>
 <ref type="include" href="A2.omdoc"/>
 </omgroup>
</omdoc>

I must confess that I do not really understand what the href on the top-level topicref means, so I have left it out. Note that I am only interested in the general compatibility of the formats and not the details of the translation, which will have to be worked out. That leaves us with the reltable, which (as far as I can understand it a way to specify cross-references that is a better alternative to <related-links>, since it is more portable and attached to DITA maps (which we can think of as discourse-level presentation of the content structure given by the graph of DITA topics). So I would just add the following metadata section to the <omgroup> element:

<metadata>
 <link rel="dita:related-link" resource="http://example.com/nats.html"/>
</metadata>

OK, that ends our little comparison exercise. There are a couple of conclusions I would like to draw from this:

1. OMDoc can do topic-oriented writing quite nicely
2. the OMDoc1.3-style metadata help significantly
3. rather than develop a DITA ontology (hinted at with the dita: namespace prefixes) we should develop ontologies that describe the various aspects of topic-based writing in generality and find the respective markup primitives. For instance dita:audience seems weird, there must be an ontology in the eLearning realm that already formalizes this.
4. The OMDoc-1.6 idea of leaving out the <metadata> element and freely intermixing the metadata <link>, <resource> and <meta> with the OMDoc content will make the translation much simpler and direct, e.g. for the <reltable> and <related-link> elements from DITA which are situated at the end in the original.

OK, that is all I have to say at the moment, please give me feedback.