Schematron Rules Development Guidelines

Keep the following guidelines in mind when developing Schematron rules.

Performance Guidelines

Be as specific as possible when you define tests and contexts for your rules

<!-- Prerequisites, Postrequisites, Step Example, Step Result, Example, Result, and Context elements should not contain introductory text. The text is generated automatically (Specific to: heretto_pdf, color_pdf, gray_pdf publishing scenarios) -->
<pattern id="STRUCTURE_10">        
    <rule context="prereq/p[1]">
        <report test="matches(., '^[Bb]before\s*you\s*[Bb]egin')">Remove the introductory text. The
            text is generated automatically.</report>
        <report test="matches(., '^[Bb]efore\s*you\s*[Ss]tart')">Remove the introductory text. The
            text is generated automatically.</report>
        <report test="matches(., '^[Pp]rerequisites')">Remove the introductory text. The text is
            generated automatically.</report>
    </rule>

    <!-- ... -->

    <rule context="context/p[1]">
        <report test="matches(., '^[Cc]ontext')">Remove the introductory text. The text is
            generated automatically.</report>
    </rule>
</pattern>

If you decide to develop a rule that validates the language layer of your content, specify the regular expression matches in the rule context rather than in the report or assert test
```

<pattern id="STYLE_07">
    <rule context="text()[matches(.,'[Dd]isplay(s|ing)?\W')]">
        <report test=".">Replace "display" with "show" or "appear". </report>
    </rule>
</pattern>
```
If you need to implement a significant number of rules (50 or more) that validate the language layer of your content, consider integrating your Heretto CCMS instance with a dedicated language-validation tool (for example, HyperSTE)

Stylistic Guidelines

Be consistent with your assert or report warnings

<!-- Each topic root element should have an @xml:lang attribute assigned -->
<pattern id="STRUCTURE_02">
    <rule context="concept|task|reference|topic|troubleshooting">
        <assert test="@xml:lang">Each root topic element should have an @xml:lang attribute
            assigned.</assert>
    </rule>
</pattern>

<!-- Each topic should contain a Short Description element -->
<pattern id="STRUCTURE_03">
    <rule context="concept|task|reference|topic|troubleshooting">
        <assert test="shortdesc|abstract/shortdesc">Each topic should contain a Short
            Description element.</assert>
    </rule>
</pattern>

For rules that validate the language layer of your content, ensure to mention the word or phrase that needs to be replaced in a specific node

Rule example mentioning the word or phrase to be replaced

<!-- Replace "desire" with "want" -->
<pattern id="STYLE_19">
    <rule context="text()[matches(.,'[Dd]esire(s)?\W')]">
        <report test=".">Replace "desire" with "want".</report>
    </rule>
</pattern>

Categorize your rules and apply consistent ID values to patterns
For example, you can use the following categories or come up with your own:
- Structure
- Style
- Grammar
- Branding
- Length
- Numbers

Implementation Guidelines

Develop a map with topics that provide tests to trigger each rule
Thoroughly test your rules before implementing them into your production instance
To maintain a version history of your SCH file with Schematron rules, store the file in a source control repository

Gretyl's Portal

Heretto Help

Schematron Rules Development Guidelines

Performance Guidelines

Stylistic Guidelines

Implementation Guidelines

Footer Section

Our Support Team is here to help