I will soon add a section on customizing rules and reports.
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
- Extract the zip and copy org.ditanauts.qa to [dita-ot]\plugins folder.
- Run startcmd.bat (win) or startcmd.sh (mac)
- Run ant -f integrator.xml
Running the Plugin
dita -f qa -i docsrc/userguide-book.ditamap -o out -l log/log.txt -Dsetchunk true
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:
- 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…
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
Thanks Malcolm! I forgot the integrator step.
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
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?
What does the rule look like in XSL?
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:
And tested against content that contained:
a professionally-managed project
environment by vetted contributors, & tested thoroughly
Are you usig ‘&’ or ‘& ;’ in your rule? Which is in your content?
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?
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.
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