History | Edit

Oxygen XML Editor includes a features that allows you to convert an existing DITA document to a different topic type. For example, if you want to convert a DITA Task to a DITA Topic, or vice versa. There are several ways to access these refactoring actions and you can choose a scope for the operation and some filtering options.

DITA Conversion Refactoring Operations for DITA

The following conversion operations are available:
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 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 Editor 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 for which resources will be affected by the operation. For example, you can choose to affect all resources in the Project, All opened files, Current DITA map hierarchy, or just the Current file.
  • 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 Editor 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.