Skip to content

Commit

Permalink
New blog post about sharing schematron business rules
Browse files Browse the repository at this point in the history
  • Loading branch information
@raducoravu
raducoravu committed Feb 7, 2017
1 parent 4637025 commit aeab7ba
Showing 1 changed file with 90 additions and 0 deletions.
90 changes: 90 additions & 0 deletions DITA/blogPosts/sharing_schematron_validation_rules.dita
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,90 @@
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE topic PUBLIC "-//OASIS//DTD DITA Topic//EN" "topic.dtd">
<topic id="sharing_schematron_validation_rules">
<title>Sharing Schematron Validation Rules</title>
<body>
<p>Custom <b>Schematron</b> rules are a great way to ensure consistency of the edited XML
structure, especially when there is a larger team working on the same set of documents.
You can use <b>Schematron</b> for lots of use cases, to make sure that certain elements
are not used at all, to impose restrictions on the amount of text for an element or to
impose restrictions on certain elements based on various attribute values or text
content set in other elements. Furthermore, you can define quick fixes for each
<b>Schematron</b> rule to give the technical writer proposed solutions for the
reported problem. In a previous blog post I described how we're using <b>Schematron</b>
for our <b>Oxygen User's Manual</b> to impose restrictions when editing DITA content:
<xref
href="http://blog.oxygenxml.com/2015/05/schematron-checks-to-help-technical.html"
format="html" scope="external"/>.</p>
<p>Once you define the <b>Schematron</b> rules, they can be shared with the other members of
your team via a document type <b>framework configuration</b>: <xref
href="http://blog.oxygenxml.com/2014/08/the-oxygen-sdk-part-2-frameworks.html"
format="html" scope="external"/>.</p>
<p>In this post I'm going to give some precise steps to share a set of Schematron rules with
a <b>DITA</b> framework extension.</p>
<p>Instead of making changes directly to the <b>DITA</b> framework configuration folder
(located in <b>OXYGEN_INSTALL_DIR\frameworks\dita</b>), modifying and distributing it
you can choose to extend the <b>DITA</b> framework and distribute the extension. In this
way, you will benefit of new functionality added to the base framework by newer Oxygen
versions and still use your customizations.</p>
<p> The steps below describe how an extension of the <b>DITA</b> framework which adds an
additional Schematron rules file:</p>
<ol id="ol_d23_5x1_wy">
<li>Create somewhere on your disk, in a place where you have full write access a folder
structure like: <b>custom_frameworks/dita-extension</b>. </li>
<li>In that new folder structure create another folder
<b>custom_frameworks/dita-extension/rules</b> which will contain all your custom
Schematron files.</li>
<li>Create a new <b>ISO Schematron</b> file called for example
<b>additionalRules.sch</b> containing inside the additional rules you want to
add. For example this Schematron reports an error if the <b>@scale</b> attribute is
used on an
image:<codeblock outputclass="language-xml">&lt;schema xmlns="http://purl.oclc.org/dsdl/schematron" queryBinding="xslt2"
xmlns:sqf="http://www.schematron-quickfix.com/validator/process">
&lt;pattern>
&lt;rule context="*[contains(@class, ' topic/image ')]">
&lt;assert test="not(@scale)">
Dynamically scaled images are not properly displayed, you
should scale the image with an image tool and keep it within
the recommended with and height limits.
&lt;/assert>
&lt;/rule>
&lt;/pattern>
&lt;/schema></codeblock></li>
<li>In the Document Type Association / Locations preferences page add in your
<b>Additional frameworks directories</b> list the path to your
<b>custom_frameworks</b> folder.</li>
<li>In the <b>Document Type Association</b> preferences page select the <b>DITA</b>
document type configuration and use the <b>Extend</b> button to create an extension
for it.</li>
<li>Give a custom name to the extension, for example <b>DITA - Custom</b> and then
change its <b>Storage</b> to <b>external</b>, then save it to a path like:
<b>path/to/.../custom_frameworks/dita-extension/dita-extension.framework</b>.</li>
<li>Make changes to the extension, go to the <b>Validation</b> tab, edit the default
<b>DITA</b> validation scenario and add an extra validation stage to it, stage
which uses your custom <b>Schematron</b> schema. More details about validation
scenarios can be found here: <xref
href="https://www.oxygenxml.com/doc/versions/18.1/ug-editor/tasks/dg-validation-scenarios.html"
format="html" scope="external"/>.</li>
<li>Click <b>OK</b> to close the dialog and then either <b>OK</b> or <b>Apply</b> to
save the preferences changes.</li>
</ol>
<p>After you perform the steps above you will have in the <b>dita-extension</b> folder a
fully functioning framework extension which can be shared with others.</p>
<p> The framework can then be shared with the others in several ways: <xref
href="https://www.oxygenxml.com/doc/versions/18.1/ug-editor/topics/author-document-type-extension-sharing.html"
format="html" scope="external"/>.</p>
<p>After your team members install the framework they can check in Document Type Association
preferences page in the list of Document Types to see if the framework is present and if
it appears before the bundled <b>DITA</b> framework (meaning that it has higher
priority).</p>
<p>You can use the framework extension mechanism to customize lots of aspects of the
<b>DITA</b> functionality in Oxygen. For example you can remove various elements
from the content completion list: <xref
href="http://blog.oxygenxml.com/2015/08/document-type-extension-sharing.html"
format="html" scope="external"
>http://blog.oxygenxml.com/2015/08/document-type-extension-sharing.html</xref>. Or
you can distribute custom new file templates: <xref
href="http://blog.oxygenxml.com/2015/12/sharing-new-custom-file-templates-for.html"
format="html" scope="external"/>.</p>
</body>
</topic>

0 comments on commit aeab7ba

Please sign in to comment.