Creating a New DITA Topic

The basic building block for DITA information is the DITA topic. DITA provides a variety of specialized topic types, the most common of which are:

• Topic - The base topic type from which all other topic types are specialized. Typically, it is used when a more specialized topic type is inappropriate.
• Task - For procedural information such as how to use a dialog box.
• Concept - For general, conceptual information such as a description of a product or feature.
• Reference - For reference information.

Oxygen XML Editor plugin also supports numerous other specialized topic types that you will find templates for in the various folder in the New DITA file dialog box. They include DITA 1.3 specializations, Lightweight DITA templates, MathML composites, Markdown documents, and other DITA specialized topic and map types such as Glossentry, Troubleshooting, Bookmap, and Subject Scheme.

To create a new DITA topic and add a reference to it in your DITA map, follow these steps:

1. In the DITA Maps Manager, right-click the node in the current map where you want to add the new topic.
2. Select one of the following actions:
   • Append Child ⇒ New - Select this action to insert the new topic as a child of the selected node. This action opens a New file dialog box that allows you to select the type of document and assists you with naming it. After you have configured your new topic, click Create.
   • Insert After ⇒ New - Select this action to insert the new topic as a sibling to the current node. This action opens a New file dialog box that allows you to select the type of document and assists you with naming it. After you have configured your new topic, click Create.
   • Duplicate - Select this action to create a copy of the selected topic and insert it as a sibling. This action opens a dialog box that allows you to choose the file name and location for the newly created copy of the topic. After you have selected the name and path for your new topic, click OK.

   Step Result: The new topic is now referenced (as a topicref) in the DITA map at the location where you inserted it and the new topic is opened in the editor.

3. Save the DITA map.

New DITA File Dialog Box

The New DITA file dialog box allows you to create a new DITA topic using various types of DITA file templates and provides some options that help you to configure the new topic.

New DITA File Dialog Box

Note

The templates that appear in this dialog box include all templates that have an associated .properties file and the type property is set to dita, as well as templates that do not have an associated properties file or the type property is not defined. It will also include custom templates that you create using the procedures presented in Creating New Document Templates.

The New DITA file dialog box includes the following features and options:

Choose a file template

Use the template preview pane to select the appropriate type of DITA file you want to create. You can use the filter text box to search for a template.

Title

Depending on the selected file template, the value of the Title field is set in:

• the title element of a DITA topic file. The title element needs to be the first child of the root element.
• the glossterm element of a Glossentry file.

Use the title to generate the file name

Select this option to use the text entered in the Title field to automatically generate a file name. By default, the generated name will transform spaces into underscores (_), all illegal characters will be removed, and all upper case characters changed to lower case (the generated name can be seen in the Save as field). You can configure these rules by clicking the File name generation rules link.

Save as

Provide a file name and path in this field. You can specify the path by using the text field, the history drop-down, or the browsing tools in the Browse drop-down menu.

Use the file name as the value of the root ID attribute

Select this option to use the file name in the Save as field (without the file extension) as the value of the root id attribute for the new topic.

Create

When you click this button, a reference (topicref) to the new topic is added to the current DITA map and the new topic is opened in the editor.