Update 2005-04: For recent toolkit materials, see the SourceForge DITA Open Toolkit Project.

[June 24, 2003] An announcement from Don R. Day (IBM) describes the release of an updated version 1.1.2 toolkit for the Darwin Information Typing Architecture (DITA), available from IBM's developerWorks XML Zone. This is a stable version of the toolkit, representing "the culmination of the past year's testing and implementation of the DTDs in IBM's internal authoring and production workbench." The new release includes a 198-page formal DITA Language Reference featuring hyperlinked descriptions of DITA elements, attributes, valid contexts, and examples. An entirely new XML Schema instance of the DITA specialization architecture is supplied. Demonstrations are provided to illustrate specializations for 'FAQ' and 'element reference' info-types and for map-driven delivery contexts for aggregated topics and Eclipse helpsets. Updates to the XSLT transform support consistent usage of a shell interface mirroring the DTD structures. Also provided is documentation for processing parameters and transform tweaks. DITA is "an XML-based, end-to-end architecture for authoring, producing, and delivering technical information. This architecture consists of a set of design principles for creating information-typed modules at a topic level and for using that content in delivery modes such as online help and product support portals on the Web."

DITA Language Reference: Bibliographic Information

DITA Language Reference. Release 1.2. First Edition, May 2003. IBM Authoring Tools. Copyright (c) International Business Machines Corporation 2003. 198 pages.

DITA Language Reference Overview

"The design of the Darwin Information Typing Architecture (DITA) is based on deriving multiple information types, or info-types, from a common, generic topic. This language reference describes the elements that comprise the topic DTD and its initial, info-typed descendents: concept, reference, and task... In addition, this reference also describes elements that are used to manage DITA topics, either for convenience in editing or for production as sets of topics for particular kinds of deliverables..."

"The elements that make up the DITA design represent a set of different authoring concerns:

• The main components of a topic, concept, reference, or task document
• The common elements available for creating content within the body of a topic
• The elements that make up the two types of tables in DITA
• Elements that represent different subject domains
• Elements that appear in many contexts
• The elements contained in the prolog of a topic
• The elements contained in the related-links part of a topic
• Elements that are available for further specialization
• Commonly referenced descriptions
• Elements contained in a DITA map

DITA Toolkit Version 1.1.2 Highlights

Updates in this distribution include:

• The DITA Language Reference, a PDF description of DITA elements, attributes, valid contexts, and examples.

• The latest version 1.1.2 DTDs (version 1.1.1 was an internal version used last year for testing, and subsequently updated)

• A new XML Schema instance of the DITA specialization architecture

• Demonstrations of specializations for FAQ and element reference info-types

• Demonstrations of map-driven "delivery contexts" for aggregated topics and Eclipse helpsets

• XSLT transform updates:

  • Consistent usage of a shell interface mirroring the DTD structures
  • Documentation of processing parameters and transform tweaks
  • Bug fixes

• CSS updates:

  • Consistent usage of a shell interface mirroring the DTD structures
  • Provision of a specialization-enabled stylesheet that directly supports new specializations

From the Colophon

Appendix B of the new DITA Language Reference explains the '(re-)use by reference' methods employed for generating links and cross-references in the document production. Excerpts: "This document was composed by IBM's ID Workbench 3.8, an internal authoring and production system for IBM's user support information. It consists of an SGML IBMIDDoc 'shell' structure that supports book production structures, such as front matter and back matter. In turn, this shell uses the <xmlobj> element to embed a map of DITA topics as the main content of the book. The initial content and linking for the individual DITA Language Reference topics was done by running a DTD-parsing tool on the current DITA DTDs, which parsed the content model relationships and attribute information as links among topics. The attribute descriptions were all mapped by use of the conref attribute to a single topic that provides maintenance for the descriptions of all of DITA's attributes in a single location. Hence, common repeating structures such as the attribute definition for href are all the result of reuse by reference from a single definition. The content of the Purpose and Examples sections of each topic was then individually written and reviewed. In effect, the DTDs constructed everything but the descriptive information in each reference topic..."

The actual DTD used for element reference topics is itself a DITA specialization of the base reference.dtd and supports specialized section elements for the <purpose>, <contains>, <containedby>, <attributes>, and <examples> sections. The content of the attributes section is a specialization of <simpletable>, wherein each row represents the common defining parts of an attribute: name, type, content, default value, and requirability... These 200 or so reference topics were then assembled into a structured hierarchy to represent the body of this document, using a DITA map (nested topicref elements). A concept topic was written to introduce each major category... ID Workbench processing converts the topics into SGML IBMIDDoc elements on the fly so that the actual processing is making full use of legacy processing capabilities in order to be able to deliver DITA content with the same business rule constraints as existing IBM documentation. DITA content can be translated and produced in many national language versions using the same tools and processes..."

About DITA

"The Darwin Information Typing Architecture (DITA) is an XML-based, end-to-end architecture for authoring, producing, and delivering technical information. This architecture consists of a set of design principles for creating "information-typed" modules at a topic level and for using that content in delivery modes such as online help and product support portals on the Web."

"At the heart of DITA, representing the generic building block of a topic-oriented information architecture, is an XML document type definition (DTD) called 'the topic DTD.' The extensible architecture, however, is the defining part of this design for technical information; the topic DTD, or any schema based on it, is just an instantiation of the design principles of the architecture."

"Specializing topic types in DITA: The Darwin Information Typing Architecture (DITA) provides a way for documentation authors and architects to create collections of typed topics that can be easily assembled into various delivery contexts. Topic specialization is the process by which authors and architects can define topic types, while maintaining compatibility with existing style sheets, transforms, and processes. The new topic types are defined as an extension, or delta, relative to an existing topic type, thereby reducing the work necessary to define and maintain the new type."

"Specializing domain types in DITA: In current approaches, DTDs are static. As a result, DTD designers try to cover every contingency and, when this effort fails, users have to force their information to fit existing types. DITA changes this situation by giving information architects and developers the power to extend a base DTD to cover their domains..." [from the Executive Summary and Roadmap]