Working with Modular XML Files in the Main Files Context

Oxygen helps you edit XML modules referenced using XInclude or external entities. By customizing the XML Main File, Oxygen provides a context to address module validation, ID referencing, understanding how modules are connected to each other, or using the Content Completion Assistant to edit content.

A Detect Main Files contextual menu action is available on the project root file that allows you to define the XML Main Files.

In the following illustration, you can see how the structure of a book project may look like, where chapters and sections are organized as distinct modules. Setting the root file as the Main File allows you to edit the modules in the correct context.

The Structure of a Documentation Project

XML Module Validation

When you validate an XML document, Oxygen automatically determines the Main Files that reference that module and validates the entire hierarchy of the assembled modules. This is especially useful, for example, when a module references IDs that are declared in another part of this hierarchy.

XML Module Editing

The Content Completion Assistant uses the schema declarations from the Main Files and only proposes elements and attributes that are valid in a particular editing context.

An XML module does not ordinarily have a schema associated with it, which means the Content Completion Assistant cannot offer element proposals. By defining the Main Files for a module, Oxygen automatically uses the schemas declared in the Main Files, making it easier to edit a module since the Content Completion Assistant proposes the elements that are valid in its context.

Also, after defining the Main Files, Oxygen proposes entities declared in the main files, both in the Content Completion Assistant and the Entities view.

Search/Refactor Support for ID/IDREFS

The Main Files defined for the current module determines the scope of search and refactoring actions for ID/IDREFS values and for updating references when renaming or moving a resource. Oxygen performs search and refactoring actions in the context that is determined by the Main Files, improving the execution speed.

Read more about the ID/IDREFS support here: Search/Refactoring Support for ID/IDREFS.

Search and Refactor Support for ID/IDREFS

Module Connections Overview

The Resource Hierarchy/Dependencies view allows you to visualize and understand the relationship between XML resources that are referenced using XInclude and external entity mechanisms.

For example, if you edit a book that is composed of multiple modules, Oxygen displays the structure of the book in a dedicated side view where all the modules are arranged in a tree-like structure. You can see what chapters are referenced from the book and what sections make up each chapter. You can also easily navigate through this hierarchy by double-clicking any of the modules.

Modules Connections Overview

Renaming or Moving an XML Module Updates its References

Oxygen automatically updates all the references to a module when the module is renamed or moved in the Project or Resource Hierarchy/Dependencies view.

When you move or rename a file or a folder from the Project view the references to its resources are changed automatically. For example, if you rename a folder, the references to its resources are also updated in a Preview window. The changes for each of the modified files are highlighted and you can choose to accept or reject them.

Oxygen uses the Main Files support to define the scope for rename or move operations invoked at project level, improving the speed of execution.

Preview the Rename or  Move Operation