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 plugin 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 plugin helps you manage those relationships. Depending on how your topics are related, you can use the tools provided in Oxygen XML Editor plugin, along with the features of DITA, in a variety of ways.

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.

Creating a Map

To add topics to a map, you must first create the map. A map is an XML document, similar to a topic. To create a map, select File ⇒ New ⇒ Other ⇒ Oxygen XML Editor plugin, or click the New button on the toolbar, select New from Templates, go to Framework templates ⇒ DITA Map ⇒ map and select the type of map you want to create. Oxygen XML Editor plugin 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, but 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.

DITA Maps Manager View

Adding Topics to a Map

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 the DITA map in the DITA Maps Manager view and choose Reference to the currently edited file from the Append child or Insert After submenus. This opens the Insert Reference dialog box with all of the required fields already filled in for you. You can fill in additional information in the various tabs in this dialog box or add it to the map later. When you select Insert and close, a reference to your topic is added to the map.

Insert Reference Dialog Box

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

As you add topics to your map, you may want to make a topic the child or sibling of another topic. This is usually done at the map level. To create a child topic reference, right-click the parent topic in the DITA Maps Manager view and choose Append child. To create a sibling topic reference, right-click a topic in the DITA Maps Manager view and choose Insert After. From either of these submenus you can then choose one of the following options:

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

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

• Reference to the currently edited file - Opens the Insert Reference dialog box that helps you to easily create a reference to the file that is currently opened in the editor.

You can also change the order and nesting of topics in the DITA Maps Manager view by doing either of the following:

• Select the topic to move while holding down the Alt key and use the arrow keys to move it around.
• Use the mouse to drag and drop the topic to the desired location.

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 maps, each with different organization and configuration options to produce a variety of 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 submaps. A submap 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 the parent DITA 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 plugin provides a validation function for DITA maps that does more than simply validating that the XML is well formed. 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.

Validate and Check for Completeness

Publishing Your Topics

As noted previously, in DITA standards you usually do not publish output from an individual topic. Instead, you create published output by 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 plugin uses the transformations provided by the DITA Open Toolkit for publishing to various 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 plugin 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 box.

Configure Transformation Scenarios Dialog Box