Useful Schematron checks for DITA authoring

chrispitude
Posts: 263
Joined: Thu May 02, 2019 2:32 pm

Useful Schematron checks for DITA authoring

Post by chrispitude » Wed Mar 18, 2020 10:11 pm

Hi all,

I wanted to start a discussion thread where we can share useful Schematron checks for DITA authoring.

Here's a check that reports text elements that begin/end with spaces:

Code: Select all

  <rule context="p|ph|codeph|filename|indexterm|xref|user-defined|user-input" role="warning">
    <let name="firstNodeIsElement" value="node()[1] instance of element()"/>
    <let name="lastNodeIsElement" value="node()[last()] instance of element()"/>
    <report test="(not($firstNodeIsElement) and matches(.,'^\s',';j')) or (not($lastNodeIsElement) and matches(.,'\s$',';j'))">Textual elements should not begin or end with whitespace.</report>
  </rule>
You can set the context to the list of elements to check. This check has some extra machinery to avoid false reporting of elements like this:

Code: Select all

<p><xref ...> provides more information on this.</p>
where the <xref> resolves as empty and the space after the <xref> causes it to report.

Radu
Posts: 7201
Joined: Fri Jul 09, 2004 5:18 pm

Re: Useful Schematron checks for DITA authoring

Post by Radu » Thu Mar 19, 2020 9:33 am

Hi Chris,

Adding a reference to the Schematron rules we use in the Oxygen User's Guide:

https://github.com/oxygenxml/userguide/ ... DITA/rules

Most of our Schematron rules are here:

https://github.com/oxygenxml/userguide/ ... vanced.sch

Besides Schematron rules we also have a style guide, a separate DITA Map with topics in which our technical documentation writers write rules about how to write the documentation.
An older blog post describes some of the rules:

https://blog.oxygenxml.com/topics/SchematronBCs.html

Also George Bina created this project:

https://github.com/oxygenxml/dim

which has some sample rules contributed by Comtech and attempts to produce the Schematron rules using XSLT from DITA topics which describe them.

Regards,
Radu
Radu Coravu
<oXygen/> XML Editor
http://www.oxygenxml.com

chrispitude
Posts: 263
Joined: Thu May 02, 2019 2:32 pm

Re: Useful Schematron checks for DITA authoring

Post by chrispitude » Tue Mar 31, 2020 4:09 pm

Here is a check that reminds writers to populate cross-book links with reference text:

Code: Select all

<pattern id="refs">
  <rule context="link|xref" role="error">
    <report test="not(node()) and contains(@keyref, '.')">Empty cross-book reference; please add the target text.</report>
  </rule>
</pattern>

Radu
Posts: 7201
Joined: Fri Jul 09, 2004 5:18 pm

Re: Useful Schematron checks for DITA authoring

Post by Radu » Wed Apr 01, 2020 8:31 am

Hi,

It's a good rule if you use key scopes only for cross publication references. If you use them for internal links then it would show errors even if the processor is able to come up with by itself with titles for links.

Regards,
Radu
Radu Coravu
<oXygen/> XML Editor
http://www.oxygenxml.com

Post Reply