History | Edit

Oxygen XML Editor includes a feature that allows you to define Master Files at project level. This feature is typically used in Oxygen XML Editor 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 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 Project 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 Project view and enable Master Files support with one of the following methods:
    • Select Enable Master Files Support from the Settings menu in the top-right corner.
    • Select Enable Master Files Support from the contextual menu of the project root folder. If a disabled Master Files folder exists, you can also select that option from its contextual menu.
    • Click the Enable button in the tooltip located at the bottom. This tooltip window is displayed when the Master Files support is disabled. Clicking the Read more link takes you to the user guide. Clicking the Enable button opens the Enable Master Files dialog box. This dialog box contains general information about the Master Files Support and allows you to enable it.
      Warning: Once you close this window tip, Oxygen XML Editor hides it for all projects. You can make the window tip reappear by resetting Oxygen XML Editor to its default settings. However, doing so will result in you losing your customized options.
  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 and select Detect Master Files.
    • Right-click the Master Files folder and select Detect Master Files from Project.
    • If you enabled the Master Files support from the tooltip at the bottom of the Project view, you can also use the Detect and Enable button in the resulting dialog box to detect the master files from the current project.
    • Manually add the root map to the Master Files folder by doing one of the following:
      • Right-click a file from your project and select Add to Master Files from the contextual menu (or simply drag and drop it into the Master Files folder).
      • Select Add Files or Add Edited File from the contextual menu of the Master Files folder.

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 Project view and Oxygen XML Editor 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 Project view, and use one of the following methods to move or rename the resources:
    Moving Resources
    To move resources in the Project view, do one of the following:
    • Simply drag and drop the resource to the new location in the tree structure (the Enable drag-and-drop in Project view option must be selected in the View preferences page).
    • Use the Cut, 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 Project 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 title.
    • 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.