VideosSchematron Quick Fixes
Table of Contents
- Introduction02:11
- Apply Quick Fixes02:27
- SQF Language02:01
- Associate Schematron with Embedded SQF01:55
Overview
Duration: 08:27
This video demonstrates how Schematron Quick Fixes can help you resolve errors
in XML documents. It shows you how to apply these quick fixes in Oxygen and also
explains some more advanced features, specifically for developers.
Transcript
00:00:07Oxygen XML Editor provides support for Schematron Quick Fixes (SQF).
00:00:14They help you resolve errors that appear in XML documents that are validated against Schematron
00:00:19schemas by offering you solution proposals.
00:00:22The Schematron Quick Fixes are an extension
of the Schematron language and they allow
00:00:27you to define fixes for Schematron error messages.
00:00:31Specifically, they are associated with assert
or report messages.
00:00:36As an example, let's consider that a company
hired a group of technical writers to write
00:00:42the documentation for a line of products.
00:00:46The team needs a set of rules to help them
maintain a common writting style throughout
00:00:51the entire documentation project.
00:00:53To help them with this, they use:
00:00:56a set of schemas to maintain the structure
of the XML documents that hold the information
00:01:02and a spell checker to fix all spelling errors.
00:01:06The company also imposes a specific style
guide.
00:01:10However, authors may find difficult to remember
all styling rules they need to apply when
00:01:15working on a large documentation project.
00:01:18Instead they can be automatically enforced
by a set of Schematron rules.
00:01:24For example, the rules range from very simple
ones, such as do not add styling inside a
00:01:31topic title, to more complex ones such as
ensuring the layout integrity of a table.
00:01:37Some users might not know how to solve all
the reported problems or they do not provide
00:01:43a consistent fix.
00:01:45Even more advanced users might need guidance
in solving an issue.
00:01:49So detecting an issue without offering a fix
is not that helpful.
00:01:54It's like having a spellchecker that reports
problems but does not offer proposals.
00:02:01Starting with version 17, oXygen offers a
solution for information architects to define
00:02:06hints and fixes for all of these issues.
00:02:12For our use case, we created a set of fixes
for the style rules applied by the company.
00:02:17All issues are highlighted in the document.
00:02:20Depending on their severity, they are highlighted
with either yellow or red.
00:02:25When you place the caret in an affected area,
if a fix is available a red light bulb icon
00:02:31is displayed in the left side of the editor
area.
00:02:34If you click that icon and the proposals are
shown.
00:02:38Now, let's solve some issues from this document.
00:02:41- The first issue reports the use of bold
styling that is not allowed inside a topic's title.
00:02:47Click the affected area to see if there are
any fixes available for this issue.
00:02:52Click the red light bulb ... and we see that
the proposed fix to remove the bold styling.
00:02:59We apply the QF and the warning dissapears.
00:03:02- The next warning reports the improper use
of semicolons at the end of the list items.
00:03:08Note that a quick fix can be also invoked
from the context menu or by pressing the Alt+1
00:03:14key on your keyboard.
00:03:16The Quick Fix removes the semicolons from
all the list items.
00:03:21- The next error reports that the format attribute
is required for an external link.
00:03:28The Quick Fix helps us to easily add the attribute
by presenting the in-place attribute editor.
00:03:37Moving on...an external link should always
start with the http or https protocol prefix.
00:03:46So we will solve that one as well.
00:03:55Next, we have several fixes that perform more
complex operations.
00:04:02The first one fixes the table layout by adding the missing cells.
00:04:09The next error reports the improper use of
ordered lists in the documentation.
00:04:16There is also a fix for this too, that converts
an ordered list into an unordered one.
00:04:23Notice that the quick fixes doesn't just provide
you a way to fix the problem, they also help
00:04:28you to understand it and helps prevent you
from doing the same mistake in the future.
00:04:34All problems are now fixed and the document
is valid.
00:04:42Now it's time to look under the hood to see
how the fixes are implemented.
00:04:47They are developed in a Schematron extension
language, called SQF (Schematron Quick Fix).
00:04:54The structure of a quick fix is very simple,
it has an ID, a title, a description, and
00:05:01the actual operations.
00:05:03The ID is defined by the id attribute from
the fix element and must be unique in the
00:05:09current context.
00:05:11It is used to refer the quick fix from a report
or assert element.
00:05:16The name of the quick fix is defined by the
title element.
00:05:20The description is represented by the content
of the paragraph elements and it is shown
00:05:25in the yellow tooltip displayed when you select
a fix.
00:05:29Next we have the operations that will be performed
by the current fix.
00:05:36There are four types of operations:
00:05:38 - Used to add a new node or fragment
in the document.
00:05:43 - To remove a node from the document.
00:05:47 - To replace a node with another
node or fragment.
00:05:52 - To replace text content
with other text or a fragment.
00:05:59You can reference the quick fixes from the
assert or report elements in the values of
00:06:04the sqf:fix attribute.
00:06:10Note that you can reference multiple quick
fixes.
00:06:17So far we've seen in this example how you
can develop quick fixes for a DITA document
00:06:23and apply them in the Author editing mode.
00:06:26However, quick fixes can be developed for
any type of XML document and can be applied
00:06:32both in Author and Text mode.
00:06:42To associate the Schematron schema that contains
the quick fixes with your XML document you
00:06:48can either configure a validation scenario
or create a persistent association in the document.
00:06:55To add a new validation scenario for our XML
file we invoke the "Configure Validation Scenarios"
00:07:02action from the Validate menu.
00:07:05Here we can create a new validation scenario
by pressing the New button or, in our case,
00:07:12we'll edit an existing scenario and add a
new
00:07:15validation rule that will validate our XML
document against the Schematron schema.
00:07:38Now the validation will use the new rule added
in the validation scenario.
00:07:43An alternative approach involves the creation
of a persistent association of the Schematron
00:07:48schema in our XML document.
00:07:51To do this, we invoke the "Associate Schema"
action and choose our Schematron schema.
00:08:06Note that the XML document is now modified
with the addition of a processing instruction.
00:08:12This will instruct the validation engine to
apply our Schematron rules and provide quick
00:08:18fixes when needed.
00:08:19And this concludes our demonstration.
00:08:22Please follow the links below for more related
information.
00:08:26Thanks for watching.
Related Videos
|
Use Oxygen Feedback to ask us anything about this video.