.
.
.
.

DITA and DocBook: An Overview and Demonstration

  1. What Is DocBook?
  2. What Is DITA?
  3. DITA Details
  4. DITA Demonstration
  5. Resources for further Exploration

By Steve Hoenisch | Slide 1 of 20        Return to beginning of the setBack to previousForward to nextJump to the end of the setInformationHome page of this set

.
.
.
.
.
.
.
.
.
V



.
.
.
.

What is DocBook?

  • DocBook is an OASIS standard that provides a system for writing structured documents in SGML or XML.
  • It is a large, robust, and easy-to-understand DTD, the main structures of which correspond to a book. There is also a small subset DTD, called simplified DocBook, for articles.
  • It is especially well-suited to books and papers about computer hardware and software, but not limited to them. Simplified DocBook is well-suited for shorter, article-length material.
  • DocBook has been widely adopted by a large community of authors and organizations.
  • It is supported by a number of authoring programs, including XMLMind, which you can install and play with for free (www.xmlmind.com).

By Steve Hoenisch | Slide 2 of 20        Return to beginning of the setBack to previousForward to nextJump to the end of the setInformationHome page of this set

.
.
.
.
.
.
.
.
.
V



.
.
.
.

DocBook Fragment in XMLMind on MacOS X



By Steve Hoenisch | Slide 3 of 20        Return to beginning of the setBack to previousForward to nextJump to the end of the setInformationHome page of this set

.
.
.
.
.
.
.
.
.
V



.
.
.
.

DocBook Fragment in XMLMind on Linux



By Steve Hoenisch | Slide 4 of 20        Return to beginning of the setBack to previousForward to nextJump to the end of the setInformationHome page of this set

.
.
.
.
.
.
.
.
.
V



.
.
.
.

What Is DITA?

  • DITA stands for Darwin Information Typing Architecture.
  • Initially developed by IBM, the DITA DTD is now an OASIS standard.
  • DITA defines
    1. A set of document types for authoring and organizing topic-oriented information in XML.
    2. A set of mechanisms for combining and extending document types using a process called specialization.
  • DITA is best suited for writing modular, topic-oriented documents.
  • This presentation is structured in an old version of DITA.

By Steve Hoenisch | Slide 5 of 20        Return to beginning of the setBack to previousForward to nextJump to the end of the setInformationHome page of this set

.
.
.
.
.
.
.
.
.
V



.
.
.
.

DITA Basics

  • DITA is an architecture for creating topic-oriented, information-typed content that can be reused and single-sourced in a variety of ways.
  • It is also an architecture for creating new topic types and describing new information domains based on existing types and domains.
  • The process for creating new topic types and domains is called specialization.

By Steve Hoenisch | Slide 6 of 20        Return to beginning of the setBack to previousForward to nextJump to the end of the setInformationHome page of this set

.
.
.
.
.
.
.
.
.
V



.
.
.
.

Information Typing

  • Information typing is the practice of identifying types of topics that contain distinct kinds information, such as concepts, tasks, and reference information.
  • Information typing is part of the general authoring approach called structured writing, used across the technical writing to improve information quality.
  • Topics that answer different kinds of questions can be categorized as different information types.
  • The base topic types provided by DITA ( a generic topic, plus concept, task, and reference ) can be adopted for immediate authoring or extended through specialization.

By Steve Hoenisch | Slide 7 of 20        Return to beginning of the setBack to previousForward to nextJump to the end of the setInformationHome page of this set

.
.
.
.
.
.
.
.
.
V



.
.
.
.

Generic Topic



By Steve Hoenisch | Slide 8 of 20        Return to beginning of the setBack to previousForward to nextJump to the end of the setInformationHome page of this set

.
.
.
.
.
.
.
.
.
V



.
.
.
.

Concept, Task, Reference

Concept topics answer ″What is...″ questions. They include a body-level element with a basic topic structure, including sections and examples.
Task topics answer ″How do I?″ questions. They have a well-defined structure that describes how to complete a procedure to accomplish a specific goal.
Reference topics describe regular features of a subject or product, such as commands in a programming language.

By Steve Hoenisch | Slide 9 of 20        Return to beginning of the setBack to previousForward to nextJump to the end of the setInformationHome page of this set

.
.
.
.
.
.
.
.
.
V



.
.
.
.

Specialization

Specialization allows the creation of specific, targeted document type definitions while still sharing common output transforms and design rules developed for more general types and domains.
For example, elementref is a specialization based on DITA's default reference topic. It is a DTD that describes a structure for documenting a schema or DTD:


Because the elementref DTD shares output transforms developed for the reference type, a new XSLT stylesheet need not necessarily be created to transform it to HTML.

By Steve Hoenisch | Slide 10 of 20        Return to beginning of the setBack to previousForward to nextJump to the end of the setInformationHome page of this set

.
.
.
.
.
.
.
.
.
V



.
.
.
.

Domains

A DITA domain defines a set of elements associated with a particular subject area or authoring requirement regardless of topic type.
The elements in a domain are defined in a domain module that can be integrated with a topic type to provide access to the domain elements within the topic type structure.
DITA's default domains:
  • Typographic
  • Programming
  • Software
  • User interfaces
  • Utilities
You may define your own domains.

By Steve Hoenisch | Slide 11 of 20        Return to beginning of the setBack to previousForward to nextJump to the end of the setInformationHome page of this set

.
.
.
.
.
.
.
.
.
V



.
.
.
.

Transclusion Mechanism

  • DITA includes a transclusion mechanism that is validated under DTD processing rules: an element "can replace itself with the content of a like element elsewhere, either in the current topic or in a separate topic that shares the same content models."
  • Conref is stricter than XInclude: Only equivalent content can be incorporated.
  • If there is a mismatch between the reusing and reused element types, the reference is not resolved.
  • It also goes beyond standard entity reuse: It allows the reused content to be in a valid XML file with a DTD.
  • The upshot is that reused content gets validated at authoring time, rather than at reuse time, catching problems when they can most easily be fixed.

By Steve Hoenisch | Slide 12 of 20        Return to beginning of the setBack to previousForward to nextJump to the end of the setInformationHome page of this set

.
.
.
.
.
.
.
.
.
V



.
.
.
.

DITA Maps

  • DITA maps organize references to DITA topics and specify the relationships among them.
  • They can also serve as outlines or tables of contents for DITA deliverables and as build manifests for DITA projects.
  • The maps represent the architecture of an information set – the topics that are needed and their relationships to one another.
  • Maps describe the context in which the topics will be read – the audience, platform, or other requirements of the information set.
  • Maps provide a mechanism that allows DITA documents to become relatively context-free, enabling them to be more easily reused in different contexts.

By Steve Hoenisch | Slide 13 of 20        Return to beginning of the setBack to previousForward to nextJump to the end of the setInformationHome page of this set

.
.
.
.
.
.
.
.
.
V



.
.
.
.

Basic Map Elements and Attributes



By Steve Hoenisch | Slide 14 of 20        Return to beginning of the setBack to previousForward to nextJump to the end of the setInformationHome page of this set

.
.
.
.
.
.
.
.
.
V



.
.
.
.

Layer Provides Scalable Reuse

Maps allow scalable reuse of content across multiple contexts, including
  • Defining an information architecture or online navigation
  • Defining audience-specific document sets
  • Defining sets of related links
The map's layer of abstraction provides a central file from which you can build, manage, and publish, with a single command, the content and navigational structures for an entire web site or a section of one.

By Steve Hoenisch | Slide 15 of 20        Return to beginning of the setBack to previousForward to nextJump to the end of the setInformationHome page of this set

.
.
.
.
.
.
.
.
.
V



.
.
.
.

Key Metadata Qualification Constructs

audience attribute: The type, job, experience level, and other characteristics of the reader for the topic. The audience element can elaborate values used by audience attributes.
category element: A classification of the topic content, equivalent to both Dublin Core Coverage and Dublin Core Subject.
DITA's metadata attributes and elements can be used to create audience- or subject-specific document subsets from a given document set.

By Steve Hoenisch | Slide 16 of 20        Return to beginning of the setBack to previousForward to nextJump to the end of the setInformationHome page of this set

.
.
.
.
.
.
.
.
.
V



.
.
.
.

Processing Maps

  • The DITA package includes XSLT stylesheets that enable you, with a single command, to transform all the documents referenced by a map to HTML and build a table of contents that links to all of them.
  • The package also includes a stylesheet for merging all the documents referenced by a map into a single DITA file.

By Steve Hoenisch | Slide 17 of 20        Return to beginning of the setBack to previousForward to nextJump to the end of the setInformationHome page of this set

.
.
.
.
.
.
.
.
.
V



.
.
.
.

Authoring Software that Supports DITA

  • XMetal by Blast Radius
  • Epic Editor by Arbortext

By Steve Hoenisch | Slide 18 of 20        Return to beginning of the setBack to previousForward to nextJump to the end of the setInformationHome page of this set

.
.
.
.
.
.
.
.
.
V



.
.
.
.

DITA Demonstration

  1. Specialization example: DTD element reference.
  2. Example document: Raw XML transformed to HTML.
  3. Example: DITA map.
  4. Example: Using map to transform all documents referenced by it and output a table of contents linking to all of them.
  5. Example: Merge all topics into single XML document and transform to HTML.

By Steve Hoenisch | Slide 19 of 20        Return to beginning of the setBack to previousForward to nextJump to the end of the setInformationHome page of this set

.
.
.
.
.
.
.
.
.
V



.
.
.
.

Resources for Exploration

By Steve Hoenisch | Slide 20 of 20        Return to beginning of the setBack to previousForward to nextJump to the end of the setInformationHome page of this set

.
.
.
.
.
.
.
.
.
V