Edit online

Main Files Support in DITA

Oxygen XML Author Eclipse plugin includes a feature that allows you to define Main Files at project level. This feature is typically used in Oxygen XML Author Eclipse 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 Author Eclipse 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 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 Explorer 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 Explorer view and select Enable Main Files Support from the contextual menu of the project root folder.
  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 or the Main Files folder and select Detect Main Files from Project.
    • Manually add the root map to the Main Files folder by right-clicking a file from your project and selecting Add to Main Files from the contextual menu (or simply drag and drop it into 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 Explorer view and Oxygen XML Author Eclipse plugin 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 Explorer view, and use one of the following methods to move or rename the resources:

    Moving Resources
    To move resources in the Project Explorer 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 Project Explorer 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.