The first step to customizing the plugin is to understand the components that comprise it. The plugin follows a typical structure–in the com.citrix.qa folder, you’ll find:
- plugin.xml, which simply gives the plugin an ID, sets the transformation type, and points to the build file.
- build_qa.xml, which specifies the build targets that control the toolkit processing.
- ant_cmd.txt, which provides example syntax for building using ant and java commands.
In com.citrix.qa\xsl, you’ll find these files:
- qascript.xsl, which creates the report’s HTML framework, calculates pass/fail values, imports stylesheets for each category of checks, and calls qa check templates.
- jit-yc.js, which…
- log.xsl, which styles the toolkit build log when the qa report is run from an ant command
- Extract the zip and copy com.citrix.qa to [dita-ot]\plugins folder.
- Run startcmd.bat (win) or startcmd.sh (mac)
- Run ant -f integrator.xml
Running the Plugin
ant -Dargs.input=doc/userguide-book.ditamap -Dtranstype=qa -Douter.control=quiet -logger=org.apache.tools.ant.XmlLogger -logfile=out/qalog.xm
The report should be output to the [dita-ot]\out folder, and called userguide-book.html. If you do not get a successful build running the ant command, try:
java -jar lib\dost.jar /transtype:qa /i:doc/userguide-book.ditamap
You won’t get the nicely-styled ant log, but the rest of the report will work.
Customizing the Plugin
There are a few things you’ll need to do to customize the plugin to meet your needs:
- Edit qascript.xsl to remove any unwanted checks by deleting <xsl:include> statements. (Click the image to embiggin.)
- Import any custom check files you have created into qascript.xsl by writing new <xsl:include> statements.
- Edit any of the provided check files (com.citrix.qa\xsl\qachecks\_*.xsl) to change, remove, or add checks. The checks all work pretty much the same way, using xsl:if statements.
XSL:IF Example Breakdown
<xsl:if test=".//*[$excludes]/text()[contains(.,'client device')]"> <li>client device should be "user device"</li></xsl:if>
The xsl:if statement defines the check; the <li> sets the message displayed to the user. This statement says, “if you find any text, except in the elements I’ve excluded, that contains the string ‘client device’, then tell the user what I’ve specified in the list item.”
You can get a long ways simply copying an xsl:if statement and changing just the ‘client device’ string and the message inside the list item. The $excludes parameter is defined at the top of the stylesheet as:
<xsl:variable name="excludes" select="not (codeblock or draft-comment or filepath or shortdesc or uicontrol or varname)"/>
This means that codeblock, draft-comment, etc are not included in any of the QA checks defined within _general_terms.xsl. To add additional elements, simply append ‘ or ‘ and an element name after varname.
In addition to checking for specific terms, we have checks for tagging. For example:
<xsl:if test=".//b"><li>Do not use typographic markup b</li></xsl:if>
This test simply looks for the use of the <b> tag, and if it is found, tells authors not to use it. In this way, you can add checks for any tag you don’t want authors to use at all. But there may be some elements that are OK to use, but not in every context. For example, we don’t like authors to nest lists inside paragraphs. Hence:
<xsl:if test=".//p//ol/li"><li>OL embedded in P element</li></xsl:if>
You can get even more complicated, like in the following example where we look for topics that do not have the xml:lang attribute set:
<xsl:if test="ancestor::*[not(@xml:lang)]"><li> Topic does not have xml:lang attribute set on element: <xsl:value-of select="./@xtrc"/></li></xsl:if>
Because the stylesheet is working in the context of the body element (conbody, taskbody, or refbody), the test looks for the first ancestor (which must be a concept, task, or reference) that lacks the xml:lang attribute. In the error message, we then use the value of the offending node’s xtrc attribute, which resolves to the element name.
As you can see, there is a lot that can be done with xpath to verify the structural markup and language used in your DITA documents.
Setting Up a Transformation Scenario in Oxygen
I typically run the transform from the command line, so these instructions may not be perfect. Please leave a comment if I’ve made a mistake! To configure Oxygen:
- Copy the plugin to “Oxygen XML Editor 13\frameworks\dita\
- Set up a new transformation scenario, using
- type = xhtml
- name = QA Report
- On the parameters tab, set:
- name = transtype
- value = qa
From that point, I think you can run the transform via Oxygen. I think…