DCLWiki | Client Area  
DCL  

representational space

   Refer a friend  Email this Page
   Print friendly version Print-Friendly
   Request Information Request Information
   Subscribe  Subscribe

          LinkedInTwitterFacebook

representational space
Services
Content Reuse
Document Conversion
Quality Assurance
Rendering & Publishing
SPL Labeling
Source Formats
   - Word Processors
   - Publishing Systems
   - PDF
   - Other Formats
Target Formats
   - XML & SGML
   - ePub
   - DITA
   - Military DTDs
   - NLM
   - Public DTDs
   - S1000D
   - Other Standards
Other Services »
representational space
Memberships

Convert to DITA

Everything you wanted to know (but were afraid to ask) (Part 2)

To get your handy DITA pocket guide, click here

As you may recall, in last month's DCLnews we had Part 1 of SiberLogic's DITA Desktop reference. That article (linked here) covered topic 1, topic 2, topic 3, and topic 4. Here is the continuation of that article.

Architectural Attributes

Class

The class attribute identifies the specialization module for the element type as well as their ancestor element types and the specialization modules.

Domain

The domains attribute lists the names of the domains in use by the current document type, and the ancestry for each domain.

Example

In this example, the task allows the use of tags for describing user interfaces (ui-d), software (sw-d), and also C++ programming (cpp-d).

The Concept Topic <concept>

The <concept> element is the top-level element for a topic that answers the question "what is?" Concepts provide background information needed to successfully work with a product or interface. Often, a concept is an extended definition of an abstraction such as a process or function.

Structure

The Concept-type topic is the simplest specialization in DITA and is derived from the Topic-type. The <conbody> element is the main body-level element for a concept. Like the body element of a general topic, <conbody> allows paragraphs, lists, and other elements as well as sections and examples. But <conbody> has a constraint that a section or an example can be followed only by other sections or examples.

This example of a concept task provides an overview topic for a larger collection about tools. The concept body (<conbody>) contains a paragraph and list of useful tools. A handy tip is also provided.

Example

The Task Topic <task>

Tasks are the essential building blocks for providing procedural information. A task topic provides step-by-step instructions detailing what to do and the order in which to do it. The task topic includes sections for describing the context, prerequisites, expected results, and other aspects of a task.

Structure

The <taskbody> element is the main body-level element in a task topic. A task body has a specific structure, with the following optional elements in this order: <prereq>, <context>, <steps>, <result>, <example> and <postreq>. Each step in a task must contain a command <cmd> element which describes the particular action the user must do to accomplish the overall task and may contain other elements such as <info> and <choices>.

Example

In this example, the task lays out the context for the procedure and then lists the steps to perform.

The Reference Topic <reference>

In technical information, reference topics are used to layout highly structured data for quick reference. Reference topics can hold anything that has regular content, such as command references, bibliographic lists, and catalogs. This information typically supplements tasks a user must perform.

Structure

The <refbody> element holds the main content of the reference topic. Reference topics limit the body structure to tables (both simple and standard), property lists, syntax sections, and generic sections and examples.

Example

This reference topic (<reference>) lists product specifications of drill bits in a simple table (<properties>). Note that in this case, the <proptype> is not restated in the second property fragment. The result is a simple, three-column, two-row table listing the bit sizes in the collection.

The DITA Map <ditamap>

DITA maps are documents that collect and organize references to DITA topics to indicate the relationships among the topics. They can also serve as outlines or tables of contents for DITA deliverables and as build manifests for DITA projects. DITA maps can be nested for easy reuse.

Structure

The <topicref> elements are the basic elements of a map. A topicref can point to a DITA topic, map, or to any other resource that can be processed or linked to. These elements can be nested to create a hierarchy, which can be used to define print output, online navigation, and parent/child links. The <topichead> element can be used for nodes in the hierarchy that provide containers without equivalent topics.

Example

This DITA map brings together a collection of five DITA topics about tools. It is organized into two chapters, "Intro to Tools" and "Using your Drill". Note that the topic, "Bit Specification" is included in the map but not referenced in the table of contents.

The Relationship Tables <reltable>

Another function of the DITA map is to organize related links between topics. Relationship tables are used to manage links for a given information product, rather than hard coding related links directly in topics. This provides a high degree of reuse for topics in different collections that may not include all of the same related topics.

Structure

Relationship tables are defined with the <reltable> element. Relationship tables can be used to define relationships among the topics in different cells of the same row. In a relationship table, the columns define common attributes or metadata for the topics in that column. The rows define relationships, with each cell representing a different role in the relationship.

Example

The following table represents the relationships between a small assortment of topics in one DITA map . Links can also optionally be defined as unidirectional or link multiple sibling topics within the same cell of the relationship table.

In this example, related links will be generated at the bottom of the topic drillbits.dita to spade.dita. Both tools.dita and shoveling.dita have links to each other as well as to snowfall.dita and traction.dita. Both snowfall.dita and traction.dita will only link to tools.dita and shoveling.dita.

Mechanics

Domain Specialization

Adding Subject-Area Vocabularies

Specialization

Specialization is used to define new varieties of information (new structures or domains), while reusing as much of existing infrastructure as possible. This minimizes effort for interchange, migration, and maintenance of content. DITA specialization can be used to make changes to prescribed structures for the sake of richer, more consistent semantic markup or to manage specific needs for output that cannot be addressed using the current data model. Two methods of specialization built into the DITA specification include:

  • Structural Specialization used to create new topic types; and

  • Domain Specialization used to create new semantic elements.

Both structural and domain specializations have been applied to the base DITA structures. The mechanisms are in place to allow architects to apply further specializations as required.

Domain Specialization

While structural specialization is used to introduce new information types, domain specialization is used to introduce domain-specific vocabularies. DITA has several domain specializations available in the standard DTD and schema including:

  • Typography - introduces typographical elements such as bold, italic, etc.

  • Programming - domain elements are used to define the syntax and to give examples of programming languages.

  • Software - domain elements describe the operation of a software program.

  • User Interface - domain elements describe the software program UI features.

  • Utility - non-semantic elements used for document image maps.

Publishing

DITA can be published in a number of ways. Common approaches include:

DITA Open Toolkit 1.3

The DITA Open Toolkit is an implementation of the OASIS DITA Technical Committee's specification for Darwin Information Typing Architecture (DITA) DTDs and Schemas. Version 1.3 M2 was released July 28, 2006. The Toolkit transforms DITA content (maps and topics) into deliverable formats.

Source: http://sourceforge.net/projects/dita-ot/

DocBook Transformations

Other solutions capitalize on existing transformations for DocBook. The DITA content and topic maps are first transformed to DocBook and then on to their final form using the DocBook transformations.


End Note

6 Linking DITA Topics through Relationship Tables, Bruski, Center for Information-Development Management, Newsletter, November 2005.

Editor's Note: Materials for this guide were developed by SiberLogic, Inc. To get the complete version of this documentation in a handy desk-top reference format, visit http://www.siberlogic.com/dita_dcl/ to request your copy.

DCLnews Editorial
September 2007

 
“Socially Enabling Documentation
in the Cloud“
Watch now!

“Content Strategy: It's Not About Technology“
“Converting to S1000D: What you need to know before, during and after“
DCL Library
Articles, fact sheets, presentations and white papers
Events

RSuite 2011 User Conference
October 25, 2011
Philadelphia, PA

LAVA-Con
November 13-16, 2011
Austin, TX

Digital Book World
January 23-25, 2012
New York, NY

More Events »
News

The Optical Society Selects Data Conversion Laboratory (DCL) For Major Publishing Project


Data Conversion Laboratory Completes eBook Projects For Information Today And Plexus Publishing

Data Conversion Laboratory and Alexander Street Press Collaborate on METS/ALTO Implementation

          More News »

representational space representational space representational space representational space representational space representational space representational space


Corporate office:
61-18 190th Street, 2nd Floor, Fresh Meadows, NY 11365
718-357-8700
Data Conversion Lab
Copyright © 1997-2011  Data Conversion Laboratory, Inc. All rights reserved.