The first enhancement I want to talk about is the QA check compiler.
Writing a QA script in PowerShell was a pretty keen idea even if I do say so myself. Moving to an Open Toolkit plugin was an even better idea with better execution. One of the drawbacks to the OT mechanism, however, is how complicated the expression of a simple check is.
For example, let’s say you want to flag occurrences of utilize and suggest use instead. This is the expression you have to write:
<xsl:if test="descendant::*[not($excludes)]/text()[matches(.,'utilize', 'i')]"> <data type="msg" outputclass="term mmstp" importance="recommended">Found "utilize". Use "use".</data> </xsl:if>
The contents of the matches call and the value and attributes of the data element are all significant and also very repetitive. As we all know, repetition leads to errors.
Authoring Checks for use with the Compiler
With the QA check compiler, you author the checks in an abbreviated form. The checks go inside a properties table inside a DITA reference topic. To express the example rule above, just add a row to a properties table to specify the severity, expression, and message.
The QA compiler, executed by the compilechecks target, takes care of the converting the rows in the properties tables to checks that the plugin can execute.
- The propdesc becomes the message for the check.
- The propvalue becomes the argument to the matches function in the XPath expression.
- The proptype becomes the @importance.
- The @id of the parent properties table becomes the @outputclass of the check.
You can have as many properties tables as you want. If the @id is term_mmstp the resulting category will be term mmstp. (Spaces aren’t allowed in @id, so an underscore is necessary but then replaced with a space in the output.) These categories are unconstrained–you can make them whatever you want.
The proptype element is limited to the values for @importance: default, deprecated, high, low, normal, obsolete, optional.
Enabling the QA Compiler
The result of the QA compiler isn’t enabled by default. To do so, uncomment the xsl:include call in xsl/qa_checks/_qa_checks.xsl and also remove the term template from that stylesheet. The QA compiler produces a template called term to make it easy to integrate, and you can’t have two templates with the same name. Once the result is included, you can start adding and modifying checks in tools/qacompiler/qa_checks_r.dita, which is a DITA reference topic. Don’t forget to run ant compilechecks after editing the DITA topic.
The results of the plugin are great. It works well with the taskbook.ditamap in the samples directory of the DITA-OT 2.1.0-M1. Unfortunately it fails in our environment. It seems, it faisl when using specialized topics.
I get some errors like:
[DOTX031E][ERROR]: The file xxx.dita is not available to resolve link information
or
[exec] [mappull] Recoverable error on line 58 of mappullImpl.xsl:
[exec] [mappull] FODC0002: java.io.FileNotFoundException:
or
[exec] [conref] Error on line 682 of conrefImpl.xsl:
[exec] [conref] Failed to transform document: An empty sequence is not allowed as the first argument of conref:isValid()
[exec] [conref] Recoverable error on line 185 of conrefImpl.xsl:
Should the reports work in environments with specialized topics as well?
Thanks for your great work
Yes, the plugin should work with specialized topics as long as you’ve integrated your specialization with the OT. If you can send me your sample content offline, I’ll take a look at the errors.
Stefan, thanks for your comment. My content set uses constrained (though not specialized) document types without any trouble. At any rate, the plugin is supposed to work with specialized topics.
mappullImpl.xsl and conrefImpl.xsl are not part of the QA plugin. I believe that the QA plugin leverages the HTML transformation bundled with the OT. The first thing I’d suggest is to convert this same map to HTML to make sure that succeeds.
If it doesn’t, you might need to file a bug with the OT developers and go back to the stable version of OT 2.0. If the conversion to HTML does succeed…I’m not sure. We’d need to get your specializations and samples to be able to reproduce.