Master Files Support in DITA
Edit online

Oxygen XML Editor plugin includes a feature that allows you to define Master Files at project level. This feature is typically used in Oxygen XML Editor plugin for XML documents to determine the context for operations such as validation, content completion, refactoring, searches, or displaying components collected from various modules. For DITA projects, this feature has a more limited purpose in Oxygen XML Editor plugin since it is mainly used to provide the means for updating references to moved or renamed resources.

Since you can move or rename DITA resources (such as topics and maps) in the DITA Maps Manager, the root map is used as the scope to update all the references to the moved or renamed resources. However, you do not have this option for non-DITA resources (such as folders, images, HTML files, audio, video, text files, Markdown documents) since they do not appear in the DITA Maps Manager. Also, when moving DITA resources in the DITA Maps Manager, you have to do it one at a time.

You can use the Master Files support in DITA to update all the references to moved or renamed resources in the scope of the Master Files, and since the root map will be set as the Master File, you achieve the same result as if you were moving or renaming them in the DITA Maps Manager. It also allows you to move multiple DITA resources (or entire folders) at once in the Navigator view, instead of the DITA Maps Manager, while still giving you the option of updating all the references.

How to Enable Master Files Support in DITA

To use the Master Files support in DITA, follow these steps:
  1. Go to the Navigator view and select Enable Master Files Support from the contextual menu of the project root folder.
  2. Add the main DITA map (root map) to the Master Files folder by doing one of the following:
    • Right-click the project root folder or the Master Files folder and select Detect Master Files from Project.
    • Manually add the root map to the Master Files folder by right-clicking a file from your project and selecting Add to Master Files from the contextual menu (or simply drag and drop it into the Master Files folder).
    Tip: You can set multiple maps in the Master Files folder and all of them will automatically be added to the list of root maps you can select from the drop-down menu in the DITA Maps Manager toolbar.

Moving or Renaming Non-DITA Resources and Updating the References to Them

With the Master Files support enabled, you can move or rename non-DITA resources (such as folders, images, HTML files, audio, video, text files, Markdown documents) or move multiple normal DITA resources (or entire folders) in the Navigator view and Oxygen XML Editor plugin will offer the option of updating all the references to the moved or renamed resources in the scope of the Master Files (in this case, the main DITA map (root map)).

To move or rename non-DITA resources (or move multiple DITA resources) and update the references to them, follow these steps:
  1. Enable Master Files support and add your root DITA map to the Master Files folder as described in the How to Enable Master Files Support in DITA section above.
  2. Go to the Navigator view, and use one of the following methods to move or rename the resources:
    Moving Resources
    To move resources in the Navigator view, do one of the following:
    • Simply drag and drop the resource to the new location in the tree structure.
    • Use the Move action (or Copy and Paste actions) from the contextual menu.
    • Right-click the resource and select Refactoring > Move resource action from the contextual menu. Note that this method also allows you to specify a new name and destination path in the Move resource dialog box.

    Result: In all cases, a Move resource dialog box will be presented.

    Renaming Resources
    To rename resources in the Navigator view, do one of the following:
    • Select the resource and press F2, or simply left-click again, until the in-place editor allows you to change the file name.
    • Right-click the resource and select Rename or Refactoring > Rename resource .

    Result: In all cases, a Rename resource dialog box will be presented.

  3. Make sure the Update references of the moved resource(s) option is selected in the resulting Move or Rename dialog box and keep the scope as master files to make sure all the references to the moved or renamed resource are updated.