Your First DITA Topic

Understanding DITA Topics

It is important to understand the role that a DITA topic plays in a DITA project. A DITA topic is not associated with a single published document. It is a separate entity that can potentially be included in many different books, help systems, or websites. Therefore, when you write a DITA topic you are not writing a book, a help system, or a website. You are writing an individual piece of content. This affects how you approach the writing task and how Oxygen XML Editor works to support you as you write.

Most of your topics are actually related to other topics, and those relationships can affect how you write and handle things such as links and content reuse. Oxygen XML Editor helps you manage those relationships. Depending on how your topics are related, you can use the tools provided in Oxygen XML Editor, along with the features of DITA, in a variety of different ways.

The Role of Maps

The basic method that DITA uses to express the relationship between topics is through a DITA map. Other relationships between topics, such as cross references, generally need to be made between topics in the same map. DITA uses maps to determine which topics are part of any output that you create. While customized DITA solutions can use other mechanisms, generally DITA is not used as a way to publish individual topics. Output is created from a map and includes all the topics referenced by the map.

A publication is not always represented by a single map. For instance, if you are writing a book, you might use a map to create each chapter and then organize the chapters in another map to create the book. If you are writing help topics, you might use a map to combine several DITA topics to create a single help topic and then create another map to organize your help topics in a help system. This allows you to reuse the content of a map in multiple projects.

Adding Your Topic to a Map

To add your topic to a map, you must first create the map. A map is an XML document, similar to a topic. To create a map, choose File > New... > Framework templates > DITA Map > map and select the type of map (for example, Map or Bookmap). Oxygen XML Editor asks if you want to open your map in the editor or in the DITA Maps Manager. Usually, opening it in the DITA Maps Manager is the best choice. You can also open the map in the editor from the DITA Maps Manager.

The DITA Maps Manager presents a view of the DITA map that is similar to a table of contents. To add a topic to a map, add a topic reference to the map using a topicref element. The easiest way to do this is to open the topic in the editor, then right-click on DITA Topic Map in the DITA Maps Manager view and choose Append child > Reference to the currently edited file.... This opens the Insert Reference dialog with all of the required fields already filled in for you. You can fill in additional information here or add it to the map later. When you select Insert and close, a reference to your topic is added to the map.

If you want to see what the resulting map looks like in XML, save your map and then double-click on DITA Topic Map in the DITA Maps Manager view. The XML version of the map opens in the editor.

Child Topics

As you add topics to your map, you may want to make a topic the child of another topic. Making it a child of another is usually done at the map level. To create a child topic reference, right-click on the parent topic in the DITA Maps Manager view and choose Append child. You can then choose one of the following options:

• New topic... - Opens the New file wizard for creating a new topic.

• Reference... - Opens the Insert Reference dialog that allows you to create a reference to an existing topic.

• Reference to the currently edited file... - Creates a reference to the file that is currently opened in the editor.

The way your parent and child topics are organized in any particular output depends on both the configuration of those topics in the map and the rules of the output transformation that is applied to them. Do not assume that your topics must have the same organization for all output types. The map defines the organization of the topics, not the topics themselves. It is possible to create a variety of different maps, each with different organization and configuration options to produce a variety of different outputs.

Child Maps

If you have a large set of information, such as a long book or extensive help system, a single map can become long and difficult to manage. To make it easier to manage, you can break up the content into smaller maps. A smaller map might represent a chapter of a book, a section of a user manual, or a page on a website.

To build a publication out of these smaller maps, you must add them to a map that represents the overall publication. To add a child map to the current map, right-click on the title of the map (for example, DITA Topic Map) and choose Append child > Map reference....

Validating a Map

Just as it is with your individual topics, it is important to validate your maps. Oxygen XML Editor provides a validation function for DITA maps that does more than simply validating that the XML is correct. It also does the following:

• Validates all of the relationships defined in the maps.
• Validates all of the files that are included in the map.
• Validates all of the links that are expressed in the files.

Validating the map that describes your entire publication validates all the files that make up the publication and all of the relationships between them. To validate a map, click the Validate and Check for Completeness button in the DITA Maps Manager view.

Publishing Your Topics

As noted previously, in DITA standards you usually do not publish output from an individual topic. Instead, you create published output bu running a DITA transformation on a map. This collects all the topics that are referenced in the map, organizes them, and produces output in a particular format. By default, Oxygen XML Editor uses the transformations provided by the DITA Open Toolkit for publishing to a variety of different output formats (such as PDF, WebHelp or EPUB). Your organization may have created various custom transformations or modified the built-in DITA Open Toolkit transformations. In either case, Oxygen XML Editor manages them by using transformation scenarios.

To publish output for a map, select the transformation scenario you want to run and set any of the parameters it requires. To select a transformation, click the Configure Transformation Scenario(s)... button in the DITA Maps Manager view. This opens the Configure Transformation Scenario(s) dialog.