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.

Use Oxygen Feedback to ask us anything about this video.

Products

Features

Shop

Resources

Support

Company

© 2002-2024 SyncRO Soft SRL. All rights reserved.

This website was created & generated with <oXygen/>®XML Editor