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 Author Eclipse plugin also supports numerous other specialized topic types that you will find templates for in the various folders 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 DITA map types such as Glossentry, Troubleshooting, Questions and Answers, Bookmap, and Subject Scheme Map.

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

In the DITA Maps Manager, right-click the node in the current map where you want to add the new topic.
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 Before > New - Select this action to insert the new topic as a sibling to the current node, before it. 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, after it. 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.
  Note: The value of the root ID is generated taking the Use the file name as the value of the root ID attribute option from the DITA > Topics preferences page into account. When the option is deselected, a unique ID is generated.
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.
Save the DITA map.

Creating a New DITA Topic Using the New File Wizard

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.

Figure 1. 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. Once you select a template, the other options will appear below the preview pane.

Tip: You can use the text filter field at the top of the dialog box to search for a specific 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.

New Topics Preferences

Pressing this button opens the DITA New Topics preference page.

Save as

Use this option to specify a file name and path for the new file. You can specify the path by using the text field, the history drop-down, or the browsing actions in the

Browse drop-down menu.

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.

Other Ways to Create a New DITA Topic

In addition to the methods described above, Oxygen XML Author Eclipse plugin also provides other ways to create DITA topics, including the following:

Fast Create Topics - You can use the Fast Create Topics feature to quickly create multiple skeleton topics at once and you can specify their hierarchical structure within the DITA map.
Extract Topic From Selection - When editing a DITA topic in Author mode, an Extract Topic From Selection action is available in the contextual menu (and the DITA menu). It creates a new DITA topic from a selection of content in the current topic.