Installing and Customizing the QA Plugin

Posted on by

In this article, you’ll find information on installing and running the QA Plugin for use with the DITA Open Toolkit 2.0.

I will soon add a section on customizing rules and reports.

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 org.ditanauts.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_qadata.xml, which specifies the build targets that control the toolkit processing.
  • readme.txt, which provides release notes and basic usage instructions.

In org.ditanauts.qa\xsl, you’ll find:

  • qadata.xsl, which generates a data file, written in DITA, that contains all of the error messages for each topic. Subsequent transforms to .csv and .html run against this data file.
  • qacsv.xsl, which transforms the data file into a .csv file that contains each error, its location, and the suggested fix
  • qareport.xsl, which transforms the data file into the .html report. The report uses Google Charts to summarize the number and type of errors generated
  • log.xsl, which styles the toolkit build log when the qa report is run from an ant command
  • css, fonts, and js folders used by the report html
In org.ditanauts.qa\qachecks, you’ll find a single xsl stylesheet that defines the QA checks to run against the input map. We check for 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 org.ditanauts.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

The plugin requires that the input map have chunk=”to-content”. Fortunatley, the plugin sets chunk automatically on the temp copy of the input map — your original source file is not touched.
In DITA OT 2.0, test the plugin with the following at the command line:
dita -f qa -i docsrc/userguide-book.ditamap -o out -l log/log.txt -Dsetchunk true
To test the plugin with earlier OT versions, type the following at the command line:
ant -Dargs.input=doc/userguide-book.ditamap -Dtranstype=qa
-Douter.control=quiet -Dsetchunk=true -logger=org.apache.tools.ant.XmlLogger
-logfile=out/qalog.xml

The report should be output to the [dita-ot]\out folder, and called report.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 Checks and Reports

You can customize which checks are run against your content by editing the xsl:if statements in xsl\qachecks\_qa_checks.xsl. You can customize the included report by editing xsl\qareport.xsl or create your own stylesheet to transform the .dita data file.

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…

11 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

    Reply ↓

  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?

    Reply ↓

      • 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.

        Reply ↓

        • 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?

          Reply ↓

  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

    Reply ↓

    • 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.

      Reply ↓

      • 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.

        Reply ↓

        • 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.

          Reply ↓

  4. I just downloaded and tried to install the latest version in oXygen 20.1. I ran the integrator and created a transform. I got errors about not finding the net.sxon in the java calls that processed the output to build the reports. I swapped those out to use the xslt call and it worked. Here is what I replaced the java calls with

    Reply ↓

Leave a Reply

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

CAPTCHA Image

*