Editing DITA Content References

Oxygen XML Editor plugin also includes some actions that allows you to quickly edit existing content references. When the element that contains a content reference (conref or conkeyref) is selected, the following actions are available in the DITA menu and the Reuse submenu of the contextual menu:
Edit Content Reference
This action is available for elements with a conref or conkeyref attribute. it opens the Edit Content Reference dialog box that allows you to edit the source location (or key) and source element of a content reference (or content key reference), and the reference details (conref/conkeyref and conrefend attributes). For more information, see Reuse Content Dialog Box.
Replace Reference with content
Replaces the referenced fragment (conref or conkeyref) at the cursor position with its content. This action is useful if you want to make changes to the content in the currently edited document without changing the referenced fragment in its source location.
Remove Content Reference
Removes the content reference (conref or conkeyref) inside the element at the cursor position.

Converting Conrefs to Conkeyrefs

Oxygen XML Editor plugin includes a DITA refactoring operation called Convert conrefs to conkeyrefs that will find all content references (that reference content outside the current document) and convert them to content key references. You can also use it to quickly convert all content references in the current document or multiple documents at once.

To access the Convert conrefs to conkeyrefs operation, 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 Convert conrefs to conkeyrefs.
Multiple Documents At Once Method
Select XML Refactoring from the XML Tools menu (or from the Refactoring submenu when you right-click a document in the Navigator viewor the DITA Maps Manager view). Then select Convert conrefs to conkeyrefs from the DITA section and click Next.
Either method will proceed 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.

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:
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.
When you use the Finish button, the operation will be processed and all content references will be converted to content key references (either all content references in the current document or all content references in all of the documents specified in the scope). The file name for each converted document is used as the value for its new key. However, the operation does NOT automatically add the key to the DITA Map, so you still need to manually define each key in your DITA map.