VideosWorking with XML Modules
Table of Contents
- Introduction02:55
- Detect Master Files01:13
- Master File Support Benefits01:09
- Working with IDs01:04
- Refactory / Rename02:04
Overview
Duration: 08:27
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
00:01:07In this demonstration we will see how
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.
Related Videos
|
Use Oxygen Feedback to ask us anything about this video.