http://norman.walsh.name/2005/10/21/dita 8 136 2005-10-21T12:51:25-04:00 $Date: 2005-10-21 13:59:54 -0400 (Fri, 21 Oct 2005) $ Norman Walsh 2005 Norman Walsh Implementing the Darwin Information Typing Architecture for DocBook. I've been trying to get my head around DITA for a while now. The trouble is, DocBook isn't my day job, and the DITA spec is fairly hefty, so it's taken rather longer than I would have liked. I've also been struggling with an emotional impediment: DocBook has never really had any competition before and I don't relish the thought fighting with anyone about it. But like it or not, DocBook and DITA are competitors, at least to the extent that both are aimed at the technical documentation market. At the end of the day, though, the markup vocabulary you choose is your business and I don't suffer if you choose not to use DocBook. That said, I think I've got my head around DITA now and if you line DocBook and DITA up, I think DITA can point to four technical differences that are arguably features in its favor: A topic-oriented authoring paradigm. A cross-referencing scheme that's more practical than XML's flat ID space. SGML's conref, reinvented. An extensibility model based on “specialization”. Well, heck, if that's all DITA has going for it, DocBook can do those things. :-)

DocBook's legacy is certainly big, linear documents: it even has the word “book” in it's name. But there's nothing that prevents you from writing modern, topic-oriented, highly modular documentation in DocBook. Nothing except, perhaps, the emotional weight of the tag names. “Book”, “Chapter”, “Section” all sound like monolithic, linear structures. Even “Article” feels a little bit like ink on dead trees. Fine. I can invent a “Topic” element to fix that: dita.topic = element topic { dita.topic.attlist, dita.topic.info, db.all.blocks*, db.section*, } The topic element is only half the story, though. DITA also has a complicated system for combining topics together based on map files. A map file identifies the topics that are part of a given deliverable (set of web pages, help system, etc., even a book). No problemo. I can have map files too: dita.map = element map { dita.map.attlist, dita.map.info, dita.topicref+ } dita.topicref = element topicref { dita.topicref.attlist, dita.topicref* } There's a bit more to DITA map files than topicrefs, but I think that's the most significant part. Other parts, such as the mechanism for tabulating relationships between topics, are equally easy to construct.

XML IDs are required to be globally unique. In a system for reusable, modular documentation, that can be a real drag. Even assuming you can manage globally unique IDs across a large number of independent topic files, reuse can break the flat ID space. Consider a unit of content that you might want to reuse, a note or table or something. If it has an ID, and if you pull that element into several different topics and those topics get pulled together by the map file, you're guaranteed to have the same ID appearing several times in your final, combined set of topics. The DITA solution is clever: scoped IDs. Given that the topic is the unit of documentation, I can say that topics must have globally unique IDs, but that every other element will be referenced within the scope of its containing topic. This is accomplished by inventing a fragment identifier syntax. Consider this topic: <topic xml:id="topic1"> <info> <title>Example Topic 1</title> </info> <para>Some topic content.</para> <note xml:id="usefulnote"> <para>This note isn't really useful, but pretend it is. </para> </note> </topic> The ID/IDREF way of referring to that note would be with its ID value: <link linkend="usefulnote">this note</link>. But that's ambiguous if the note appears in more than one topic, so instead I use: <link xlink:href="#topic1/usefulnote">this note</link>. The semantics of this fragment identifier syntax are straightforward: find the second ID (usefulnote) inside the topic with the first ID (topic1). Then if I say that this is the fragment identifier syntax for documents in this system (i.e. with some media type that I still have to invent), I've closed the loop (web-) architecturally. Now, in theory, I've still got the technical problem that I have multiple xml:id attributes with the same value in the combined set of topics. I could only avoid this by using a different attribute name. But I actually think it's better to ignore this theoretical problem. In practice, what this means is that the validator will check the uniqueness of IDs as long as I validate individual topics. That's going to catch cut-and-paste errors, and I think that's worth bending the rules slightly at build time. I can implement this system by adjusting the stylesheets to understand these fragment identifiers and by turning off ID/IDREF linking: db.linkend.attribute = notAllowed db.linkends.attribute = notAllowed db.endterm.attribute = notAllowed There. That was easy.

Conceptually, “conref” (or content reference) is a kind of cross reference. But instead of pointing to its content, it transcludes it. The practical benefit of conref is that it replaces some uses of entities or XInclude. DITA's reinvention of conref has a couple of interesting features: It transcludes the content of the element it points to, but not the element itself. This means you can reuse an element without reusing it's ID or other attribute values. A conref must point to an element of the same type. In other words, you can conref from one para to another, but not from a para to a note. Consider the useful note from above. If I wanted to reuse it in a new topic, how would I do it? I could put it in an entity and reference it in both places, or I could use XInclude. But neither of these would have the features above, so instead, I use a new conref attribute: <note conref="#topic1/usefulnote"/> That's easy to add to DocBook: db.common.attributes &= dita.conref.attribute? db.common.idreq.attributes &= dita.conref.attribute? An additional semantic of conref is that an element with a conref attribute must be empty. Although RELAX NG could be persuaded to enforce that constraint, it seems tedious to do so for a common attribute. Instead, I'll eventually rely on Schematron assertions to test for that (I haven't written them just yet). In the meantime, I've made the stylesheet that performs the transclusion enforce that constraint.

DITA's extensibility mechanism is perhaps its most clever invention. While it's easy to extend DocBook, for example, to add a new element, doing so introduces an interoperability problem. Suppose you invent a new kind of list, a product list. Imagine that the important semantic of a product list on your system is that products named in a product list are automatically verified against a manifest. In all other respects, it's just a regular ordered list. The DocBook way to do this in a portable manner is with the role attribute: <orderedlist role="productlist"> <listitem><para>1 <productname>oscillation overthruster</productname> </para></listitem> <listitem><para>4 <productname>#11 screws</productname> </para></listitem> <listitem><para>1 <productname>watermelon</productname> </para></listitem> </orderedlist> The problem is, if the reason you're inventing the new kind of element is to give it a slightly different content model, this approach doesn't really work. (In fact, you can make it work in RELAX NG, but it'd be really ugly for authors.) What you'd like to do instead is just invent a new tag, productlist, and use that: <productlist> <listitem><para>1 <productname>oscillation overthruster</productname> </para></listitem> <listitem><para>4 <productname>#11 screws</productname> </para></listitem> <listitem><para>1 <productname>watermelon</productname> </para></listitem> </productlist> Now the problem is, if you want to format that element, you have to modify the stylesheets and if you want to interchange your topics with others, they all have to have your stylesheet customizations too. DITA overcomes this by describing extensions in terms of specialization or subtyping. When you invent a new element, you also say what kind of element it specializes. When the stylesheets (or other tools) don't know what to do with your special element, they can automatically treat it as if it was the more general element that it specializes. The DITA mechanism for accomplishing this is an ingenious, if elaborate, system of fixed attribute values in the DTD. This leads to odd looking stylesheets that almost exclusively use patterns of the form: <xsl:template match="*[contains(@class, 'some/value ')]"> ... </xsl:template> In addition to a sort of baroque scheme for implementing this in DTDs, DITA also appears to have the limitation that specializations must be isomorphic to something in the base system. That, in turn, forces some of the elements in the base system to have…interesting content models. Consider DITA's topic for example. The content model of a topic body is “(p|note|...|section|example)*”. On the face of it, that allows topics to contain a free mixture of sections and paragraphs, which one wouldn't ordinarily consider a good thing. I gather that this is necessary so that some specialization of topic can have an element that's required to occur last (after section), that is itself a specialization of p. But I could be wrong about that. Anyway, the idea of specialization is useful and interesting, and I can accomplish the same thing on top of DocBook by taking advantage of annotations in the schema. In broad strokes: I add annotations to the RELAX NG grammar for the extensions. These annotations describe how to transform each new element back to some base element in DocBook. I add a parameter to the stylesheets so that they can know what schema is being used for the document. This is conceptually no different than the DITA case where the DTD for the extension is, in practice, required. The stylesheets already have a “normalization” phase that adjusts content in the source document; I extended that phase to include handling “unknown” elements by mapping them back to DocBook as described by the annotations. So all you have to do is add the annotation to your extension: dita.productlist = [ r:remap [ db:orderedlist [] ] ] element productlist { dita.productlist.attlist, dita.productlist.info, db.all.blocks*, db.listitem+ } And you're done. A productlist will be treated exactly like an orderedlist. Although I didn't show it above, this technique is used in the definition of topic to map topics back to sections. And for my DITA experiment, where I created DocBook task, concept, and reference specializations of topic, I used exactly the same technique. A task is remapped to a topic if there's no template for task, which is, in turn, remapped to a section, if there's no template for topic. Using the annotation technique, there's no requirement that extensions be isomorphic to something already in DocBook, though that's the simplest case. Consider the DITA relatedlinks tag that can occur at the end of a topic. Suppose you wanted to turn this list of links into a section with a default title? You can use a slightly more complicated remap annotation to accomplish that: dita.relatedlinks = [ r:remap [ db:section [ role="dita-relatedlinks" db:info [ db:title [ "Related Links" ] ] db:para [ r:content [] ] ] ] ] element relatedlinks { dita.relatedlinks.attlist, dita.relatedlinks.info, db.link.inlines+ } That annotation will wrap the body of the relatedlinks element inside a para inside a section with the title “Related Links”. The extent of the transformations that you can do today is fairly limited (isomorphism or wrapping the content in some structure). But if I imagine a world in the not too distant future where there's a standard XML Pipeline language for processing a sequence of transformations, it's easy to imagine that XSLT templates could be used as annotations, giving extension writers almost complete freedom.

With a couple of hours of hacking, I've implemented on top of DocBook the four key features of DITA that I could identify. (If there are more, bring them on, DocBook can do them too!) In doing so, I've attempted to remain true to the spirit of DocBook, so my content models aren't exactly the same as the DITA models, but I think the analogies are sound. That means the choice of which vocabulary to use, DocBook or DITA, comes down simply to the actual terms in the vocabulary, the elements and attributes provided, their semantics, and their relationships to each other. On that score, I think DocBook is the hands-down winner. But I was bound to say that, wasn't I?

My experiment to implement DITA on top of DocBook includes: A schema (RNG or RNC) The schema is a DocBook 5.0 extension that defines a new top-level element, the topic. In the interest of modelling DITA, it also defines a task with the same general structure as a DITA task, a concept, and a reference as specializations of topic. I really don't understand the structure of a DITA task with its body elements that are just like paragraphs. How a technical vocabulary could expect every task to have pre- and post-requisites, a context, a result, and (a single!) example such that each fits into a single paragraph is beyond me. If there's ever a move to standardize my DITA customizations of DocBook, I think task can be done better. (There's also the issue of the existing, distinct task element already in DocBook, but that's a different problem.) A stylesheet The stylesheet is a customization of the DocBook XSLT2 Stylesheets. It handles the semantics of the simple map files I outlined above, supports conref, and implements the DITA fragment identifier syntax. I incorporated the schema support into the base stylesheets. An example My example is just a toy, but it has several parts: a map, a “main” topic, a “subordinate” topic, and a task. Run them through the stylesheets and you get a “normalized” document which is formatted as you'd expect. Of all the pieces involved, supporting a more robust map file is probably the most interesting. But it wouldn't be difficult.