|
|
Convert to DITA
Everything you wanted to know (but were afraid to ask)
(Part 2)
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:
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
|
|
|
|
