Converting DITA Topics to Another Type

DITA Conversion Refactoring Operations for DITA

The following conversion operations are available:

Convert Nested Topics to New Topics (Available from the contextual menu of editable maps/nodes in the DITA Maps Manager): Use this operation on topics that contain nested <topic> elements to convert each nested topic to a new topic. Also, the new topics are added in the DITA Maps Manager as the first child topics of the original topic.
Convert Sections to New Topics (Available from the contextual menu of editable maps/nodes in the DITA Maps Manager): Use this operation on topics that contain multiple sections to convert each section to a new topic. Also, the new topics are added in the DITA Maps Manager as the first child topics of the original topic.
Note: As long as the DITA topic is of the type topic, concept, or reference, the new topics that will be created from the inner sections will retain the same topic type as the original topic.
Convert to Concept: Use this operation to convert a DITA topic (of any type) to a DITA Concept topic type (for example, Topic to Concept).
Convert to General Task: Use this operation to convert a DITA topic (of any type) to a DITA General Task topic type (for example, Task to General Task). A DITA General Task is a less restrictive alternative to the Strict Task information type.
Convert to Reference: Use this operation to convert a DITA topic (of any type) to a DITA Reference topic type (for example, Topic to Reference).
Convert to Task: Use this operation to convert a DITA topic (of any type) to a DITA Task topic type (for example, Topic to Task).
Convert to Topic: Use this operation to convert a DITA topic (of any type) to a DITA Topic (for example, Task to Topic).
Convert to Troubleshooting: Use this operation to convert a DITA topic (of any type) to a DITA Troubleshooting topic type (for example, Topic to Troubleshooting).

Methods for Accessing the DITA Conversion Refactoring Operations

To access the conversion operations, use one of the following methods:

Single Document Method: With the document opened in the editor, right-click anywhere in the main editing pane (or right-click the topic reference in the DITA Maps Manager), go to the Refactoring submenu, and choose whichever operation is appropriate for your needs.
Multiple Documents At Once Method: Select XML Refactoring from the Tools menu (or from the Refactoring submenu when you right-click one or more documents in the Project viewor the DITA Maps Manager view). Then select whichever operation is appropriate for your needs.

XML Refactoring Wizard Dialog Box

When you select any of the operations, Oxygen XML Author proceeds to the XML Refactoring Wizard. If you used the Multiple Documents At Once Method, the wizard page allows you to choose a scope for the operation and some filtering options:

Scope - Select from a variety of options to define the scope that will have resources affected by the operation. For example, you can choose to affect all resources in the Project, All opened files, Current DITA map hierarchy, Selected reference, and others depending on the context.
Filters section
- Include files - Specifies files to be excluded from the operation. You can specify multiple files by separating them with commas and the patterns can include wildcards (such as * or ?).
- Restrict to known XML file types only - Excludes non-XML file types from the operation.
- Look inside archives - If this option is selected, the scope of the operation will include files inside archives.

If you used the Single Document Method, the scope will be the current file so the scope and filtering options are not displayed.

You can then use one of the following buttons to proceed with the operation:

Preview: You can use the Preview button to open a comparison panel where you can review all the changes that will be made by the refactoring operation before applying the changes.
Warning: It is always recommended to use the Preview button to make sure the operation is not going to do something unexpected and after you click the Finish button, any Undo action will only revert changes on the current document.
Finish: When you use the Finish button, behind the scenes Oxygen XML Author maps the structure of the previous DITA document type to a structure that fits the new type. In some cases, especially when the previous structure was very complex, the conversion might result in an invalid structure and some manual adjustments might be required.

Handling Special Characters When Generating New File Names

For refactoring operations that generate a new file, if special characters are detected in an element that will be used to generate the new file name, the special characters will automatically be replaced with their ASCII equivalents (for example, Ä is changed to AE). If an ASCII equivalent does not exist, it will be replaced with an underline character ( _ ). The purpose of this functionality is to avoid generating invalid file names.

It is possible to customize the list of replaceable symbols by editing the following XSLT character map file:

[OXYGEN_INSTALL_DIR]/frameworks/dita/refactoring/utils/character-map.xsl.

Converting To and From DITA Specialization Document Types

If you use your own DITA specialization document type, you can modify mappings for the predefined conversion operations to work with your specialization.

To use the conversion operations with your DITA specialization, follow these steps:

Locate the conversion stylesheets in the following directory (and its subdirectories): [OXYGEN_INSTALL_DIR]/frameworks/dita/refactoring/.
Note: The stylesheets for converting entire files (from one type to another) are located in the dita-files-conversion-stylesheets folder. Each of these conversion operations has a stylesheet with the word entrypoint at the end of its name. Edit the appropriate *-entrypoint.xsl file (for example, to modify the Convert to Task operation, edit the convert-resource-to-task-entrypoint.xsl file).
Depending on whether you use a DTD, XML Schema, or Relax NG-based specialization, you can:
1. Modify the values of the declared root-element, public-literal-target, and system-literal-target variables to match your specialization's DTD information.
2. Modify the value of the declared schema-location variable to match the location of your specialization's XML schema.
3. Modify the value of the declared xml-model-location variable to match your Relax NG specialization.
For the Convert Nested Topics to New Topics and Convert Sections to New Topics operations, if your DITA specialization uses your own custom URN or DOCTYPE, you can replace the default mappings in the [OXYGEN_INSTALL_DIR]/frameworks/dita/refactoring/utils/dita-formats.xsl stylesheet with your own values for the DOCTYPE or xml-model.
If you want to change the name of the operation that will be displayed in Oxygen XML Author, follow these substeps:
1. Locate the resource XML file for the same conversion operation in the following directory: [OXYGEN_INSTALL_DIR]/frameworks/dita/refactoring/ (for example, for the Convert to Task operation, it is convertResource2Task.xml).
2. Edit that XML file and change the name attribute to match whatever you want to be displayed for that operation (for example, name="Convert to My DocType").
Save your changes to all modified files.
Restart Oxygen XML Author

Result: You should now see your changes when accessing the conversion operations.