VideosWorking with XML Modules

Overview

In this demonstration, you will see how Oxygen helps you to edit modular XML files that are referenced using external entities.

Transcript

00:00:07Large documentation projects sometimes require a certain degree of modularization by breaking
00:00:13up the projects into functional smaller modules.
00:00:16This approach brings a series of advantages:
00:00:19increased flexibility, improved re-usage degree, and ultimately reduced overall project costs.
00:00:26Thus, a documentation project might have a structure like the following one:
00:00:31... where chapters and even sections are organized as distinct modules.
00:00:36All of them are assembled in a book that refers them using either XInclude and external entity
00:00:44references.
00:00:45However, editing a module might need a larger context to solve issues like module connection
00:00:51overview (understanding how modules are connected with
00:00:55each other),
00:00:57module validation,
00:00:58editing using the content completion assistant or ID referencing.
00:01:02 helps you to do all these using the Master Files support.
00:01:07In this demonstration we will see how helps you to edit modular XML files that are
00:01:13referred using external entities.
00:01:16We have already defined a project containing two user guides for two phone models.
00:01:21As you can see some of the content is different, here highlighted with red and some content
00:01:28is shared between the two user guides.
00:01:36The main file refers chapters of the manual using External Entities and each chapter refers
00:01:43different sections of the manual.
00:01:45oXygen helps you to visualize the structure of the manual in a dedicated side view where
00:01:50all the modules are arranged in a tree-like fashion.
00:01:54To open this side-view, use the Resource Hierarchy action from project's contextual menu.
00:02:00Now it is easier to see what chapters are referred from the manual, and what sections
00:02:06that make up each of the chapters.
00:02:08Also, you have easy access to any of the modules that compose this hierarchy. Double click
00:02:13a module to open it in the editor view.
00:02:17The next step is to edit the module.
00:02:19The Making a call.xml cannot be validated as a standalone module because it does not
00:02:24have a schema associated with it.
00:02:28Note the error mesage displayed in the Results View.
00:02:33Also the content completion assistant does not offer any element proposal.
00:02:37Now, if we open another file, lets say Making a conference call.xml, this file cannot be
00:02:43validated as a standalone module because it does not have a schema associated with it
00:02:49and also refers entities that are not defined in this module.
00:03:00In order to edit these modules in the context of the user manual, you need to enable the
00:03:05master files support and add the user manual file as a master file.
00:03:11First , we press the Enable button.
00:03:13The application displays an information dialog with more information about Master Files support.
00:03:19We choose to allow oXygen to Detect the possible master files in the current project.
00:03:25Here we choose to detect the possible master files for XML resources.
00:03:30After the detection phase is complete, oXygen presents a tree with the hierarchy of the
00:03:34files detected in the project.
00:03:36On the first level we have the possible master files, which are the user manuals that refer
00:03:42the chapters and sections.
00:03:44We set both files as master files.
00:03:49In the last wizard page you can preview the master files that will be added in your project.
00:03:56oXygen added links to the selected resources in the Master Files folder from the Project
00:04:01view.
00:04:02oXygen uses the hierarchy of these files to determine the editing context for a specific
00:04:08module.
00:04:13Now the validation of a module will be done in the context of the main files...
00:04:17Let's try to validate one of the files that was previously found as invalid...
00:04:22As you can see, now the validation is successfull.
00:04:25Also the content completion assistant uses the schema declarations from the master files.
00:04:30We can easily edit the module because the content completion assistant proposes only
00:04:35elements valid in the current context.
00:04:37After defining the Master files, oXygen also presents in a module the entities declared
00:04:43in the main files.
00:04:44We start the content completion assistant and start typing an entity name.
00:04:51Also, the Entities view presents in a tabular form the entities defined in the master file.
00:05:01Double click an entity name to insert it at the current caret position.
00:05:05Now we close this file and focus on Making-a-conference-call.xml
00:05:11Similarly, it also becomes valid because it is now validated in the context of the main
00:05:18files.
00:05:24Next ... we'll take a look at oXygen's capabilities of handling IDs.
00:05:27The content completion assistant presents all the IDs that can be referred in the current
00:05:32context.
00:05:33The id's are collected from the entire file hierarchy starting from the master files.
00:05:39To determine where the "makingACall" ID is declared, press and hold the Ctrl key and
00:05:45click the ID name.
00:05:47The file that contains the ID's declaration is open and the ID is highlighted to make
00:05:52it more visible.
00:05:54Also the Quick Assist support helps you rename the ID and search an ID reference or a declaration
00:06:01in the scope determined by the master files.
00:06:03We will use the "Rename in" action to modify the ID from "makingACall" to "initiatingACall".
00:06:11Also you can preview the modifications before accepting them.
00:06:15Note that both the declaration and the reference of the ID are modified.
00:06:20We accept the modifications.
00:06:28The Master Files are used also to define the scope for the Rename and Move operations invoked
00:06:34at project level.
00:06:36As an example, we will move the Making a call.xml file into the Getting Started folder.
00:06:46Just drag the file and drop it into the target folder.
00:06:49The confirmation dialog allows you to update also the references to the moved resource.
00:06:55Before finishing the operation, you can preview the modifications.
00:06:59We note that the file is referred in two resources.
00:07:04We accept the modifications.
00:07:06Also if we rename or move a folder you can choose to update also the references to the
00:07:12resources from the folder.
00:07:14For example if we rename "Phone-Basics" to "Phone-Basic-Operations"...
00:07:18we note in the preview dialog that all the reference to the files from this folder are
00:07:31updated.
00:07:35So far, this demonstration highlighted oXygen's ability of editing XML modules referred using
00:07:49external entities.
00:07:50Similarly, you can use oXygen to edit XML modules using XInclude references.
00:07:54The Master Files support is a very effective and powerful feature but adding too many files
00:08:01in the Master Files folder may impact on the application performance, unless you apply
00:08:06the following three simple rules:
00:08:09- Add only the top level files, each of them being the root of a tree of modules
00:08:15- Keep the file set to a minimum - Do not add standalone files in the Master
00:08:22Files folder
00:08:23And this concludes our demonstration.
00:08:25Thanks for watching.