Installing and Customizing the QA Plugin

I’ve done a poor job of documenting the QA Plugin. This is my attempt to begin rectifying that mistake. In this article, you’ll find information on installing, running, and customizing the QA Plugin. Our next release will have significant changes; I’ll be sure to post new documentation here and on sourceforge.

Plugin Components

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.
  • dita2jit_pie_chart.xsl, which creates a javascript file used to generate the element count pie chart.
  • jit-yc.js, which…
  • log.xsl, which styles the toolkit build log when the qa report is run from an ant command
In com.citrix.qa\qachecks, you’ll find a number of xsl stylesheets that define QA checks. We have stylesheets that check or product terminology, general terminology, attributes, language standards, and more. We have well over 100 checks, and counting. You can edit, add to, or remove any of these checks to suit your needs.

Installation

  1. Extract the zip and copy com.citrix.qa to [dita-ot]\plugins folder.
  2. Run startcmd.bat (win) or startcmd.sh (mac)
  3. Run ant -f integrator.xml
If you get a build successful message, then you should be good to go.

Running the Plugin

First, make sure the map you are running the plugin against has chunk=”to-content”. The plugin will not work correctly unless this is set. To test the plugin, type the following at the command line:
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:

  1. Edit qascript.xsl to remove any unwanted checks by deleting <xsl:include> statements. (Click the image to embiggin.)
  2. Import any custom check files you have created into qascript.xsl by writing new <xsl:include> statements.
  3. 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

Let’s look at an example qa check:
<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::*[1][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:

  1. Copy the plugin to “Oxygen XML Editor 13\frameworks\dita\DITA-OT\plugins”
  2. Set up a new transformation scenario, using
    1. type = xhtml
    2. name = QA Report
  3. On the parameters tab, set:
    1. name = transtype
    2. value = qa

From that point, I think you can run the transform via Oxygen. I think…

10 thoughts on “Installing and Customizing the QA Plugin

  1. Setup for Oxygen XML Editor
    1. Copy the “com.citrix.qa” folder into DITA-OT/plugins
    2. Execute the “Run DITA OT Integrator” ANT transformation
    3. Create new User defined scenario based on the DITA XHTML DITA predefined scenario, I used Name = “QA Report Topic” and a new parameter with Name=transtype and Value=qa
    4. Execute the “QA Report Topic” User defined scenario to generate the report

  2. For some reason, the excludes don’t seem to be working? I have an example rule that keeps getting flagged:
    Do not use the ampersand character (&) in text. It can be used in a table or title if there are space restrictions.

    Here’s my sample content:
    // Set example parameters
    // Check if authentication is enabled
    if (&authentication);
    }

    The rule is getting triggered and I’m getting a message in the output. I thought that the exclude would not have checked the codeblock though?

      • For example:
        xsl:if test=”.//*[$excludes]/text()[contains(.,'&')]“><li class=”warning”>Do not use the ampersand character (&) in text. It can be used in a table or title if there are space restrictions.

        • Hi Scott, I am not able to reproduce this issue. I added the following rule:

        • Do not use the ampersand character (&) in text. It can be used in a table or title if there are space restrictions.
        • And tested against content that contained:
          a professionally-managed project
          environment by vetted contributors, & tested thoroughly

          Are you usig ‘&’ or ‘&amp ;’ in your rule? Which is in your content?

  3. I followed your Oxygen integration instructions and made sure the bookmap had chunk=”to-content”. The plug-in runs fine, but the summary page is not created. Can you please advise?

    Thanks,
    Jason

    • What IS created?

      I have seen cases where the bookmap or nested map refers to topics outside the “root” directory, in which case the resulting summary page is not directly in the out directory, but nested in the same way as the input folder structure. I hope that makes sense.

      • I am using the out of the box plug-in.

        When integrated with our CMS, we get the expected output.

        When running from Oxygen (default plug-in with no mods), I get one HTML file per topic but no summary page.

        The DITA OT lodges no complaints, and I have experimented with turning chunking on and off. Same result. Since our CMS works fine, I know the plug-in works as designed. It’s just figuring out why Oxygen can’t render the summary page that I need to accomplish. I will check the default settings that it has, but I would welcome your feedback.

        • I’ve seen this issue occur with Oxygen when the transtype is set twice in the ant command generated by Oxygen. In the check-args section of the log, the transtype should be listed as qa, and not xhtml for example.

          My other suggestion would be to try to run the transform outside of Oxygen on your local system. You should be able to do this by:

          1. Going to “C:\Program Files\Oxygen XML Editor 13\frameworks\dita\DITA-OT”
          2. double-click startcmd.bat
          3. type the following command:

          ant -Dargs.input=[yourpath].ditamap -Dtranstype=qa

          The result will be in the C:\Program Files\Oxygen XML Editor 13\frameworks\dita\DITA-OT\out folder.

Leave a Reply

Your email address will not be published. Required fields are marked *

*


*

You may use these HTML tags and attributes: <a href="" title=""> <abbr title=""> <acronym title=""> <b> <blockquote cite=""> <cite> <code> <del datetime=""> <em> <i> <q cite=""> <strike> <strong>