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…