Edit online

Main Files Support in DITA

Oxygen XML Author includes a feature that allows you to define Main Files at project level. This feature is typically used in Oxygen XML Author 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 Author 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 Main Files support in DITA to update all the references to moved or renamed resources in the scope of the Main Files, and since the root map will be set as the Main 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 Main Files Support in DITA

To use the Main Files support in DITA, follow these steps:
  1. Go to the Project view and enable Main Files support with one of the following methods:
    • Select Enable Main Files Support from the Settings menu in the top-right corner.
    • Select Enable Main Files Support from the contextual menu of the project root folder. If a disabled Main 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 Main Files support is disabled. Clicking the Read more link takes you to the user guide. Clicking the Enable button opens the Enable Main Files dialog box. This dialog box contains general information about the Main Files Support and allows you to enable it.
      Warning: Once you close this window tip, Oxygen XML Author hides it for all projects. You can make the window tip reappear by resetting Oxygen XML Author 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 Main Files folder by doing one of the following:
    • Right-click the project root folder and select Detect Main Files.
    • Right-click the Main Files folder and select Detect Main Files from Project.
    • If you enabled the Main 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 main files from the current project.
    • Manually add the root map to the Main Files folder by doing one of the following:
      • Right-click a file from your project and select Add to Main Files from the contextual menu (or simply drag and drop it into the Main Files folder).
      • Select Add Files or Add Edited File from the contextual menu of the Main Files folder.
    Tip: You can set multiple maps in the Main 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.
  3. [Alternative] If you have a defined DITA Open Toolkit project XML file you can add it to the Main Files folder. Once you do that the application will know the dependencies between all resources directly and indirectly referenced from the project file, including DITA maps, topics, binary resources and DITAVAL filter files.

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

With the Main 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 Author will offer the option of updating all the references to the moved or renamed resources in the scope of the Main 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 Main Files support and add your root DITA map to the Main Files folder as described in the How to Enable Main 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 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 main files to make sure all the references to the moved or renamed resource are updated.