Command Line Tool Guide
Introduction
In addition to the Java API which can be used to embed ConversionQA in internal or OEM applications, evaluators may wish to quickly experiment using a command line tool.
The deltaxml-conversion-qa-x.y.z.jar
file included in the distribution may be invoked from a command line terminal on all supported platforms, allowing similar input options to the Java API to be specified.
Replace x.y.z with the major.minor.patch version number of the release that you are using e.g. deltaxml-conversion-qa-1.0.1.jar
Requirements
The minimal requirement to run the command line tool is to have a Java Runtime Environment (JRE) version 8 or higher installed on your computer.
To ensure maximum performance from the Java Virtual Machine (JVM) please ensure that the JRE you install matches your computer architecture. This is especially applicable to computers powered by Apple Silicon CPUs.
General Usage
To invoke the deltaxml-conversion-qa-x.y.z.jar
on macOS or Windows, first open the Terminal application. Change directory to the location where you unzipped the distribution
DeltaXML-Conversion-QA-x.y.z_j.zip
file.
cd DeltaXML-Conversion-QA-x_y_z_j
Note that all the jar files plus the “dita-ot-x.y.z” folder included in the distribution are required to be either kept in the same directory as the deltaxml-conversion-qa-x.y.z.jar
(recommended) or made available to Java via the Java classpath.
The general format to invoke the deltaxml-conversion-qa-x.y.z.jar
is:
java -jar deltaxml-conversion-qa-x.y.z.jar command arguments
If you invoke the deltaxml-conversion-qa-x.y.z.jar
without specifying any arguments, it will display product information and an overview help message.
% java -jar deltaxml-conversion-qa-x.y.z.jar
DeltaXML ConversionQA x.y.z
Released 2023-08-17
Copyright (c) 2023 Deltaman Group Ltd. All rights reserved.
Usage:
java -jar deltaxml-conversion-qa.jar license
java -jar deltaxml-conversion-qa.jar describe <inputType> to see a description of the required input format for the specified check type
java -jar deltaxml-conversion-qa.jar check <input-A-type> <input-A-arguments> <input-B-type> <input-B-arguments> [resultlocation=value] [resultprefix=value]
Available Input Types:
====================================================
Input Type | Short Description
====================================================
ditamap | A DITA document passed as a zip file, which must contain a master map file with '.ditamap' extension
docx | A Microsoft Word document file with extension '.docx'
xml | A non-specific XML format file
====================================================
Commands
Each invocation of the ConversionQA command line tool will require a command, optionally followed by a subcommand, command-options, and arguments.
The commands are listed here.
Command | Description |
---|---|
check | Used to perform a conversion check given two inputs, which we shall call input A and input B. Input A is typically the original document, and Input B is typically the document content which has been converted to a different format. The inputs can be of various different document format input types which must be specified with a sub command. |
describe | Provides a description of required sub commands and arguments for each type of check command. |
license | Provides information about what type of license is being used. This provides an easy way to check that your license file is valid and being correctly located by ConversionQA. |
Command Arguments
check
The check
command takes two input type sub-commands, the first representing input A and the second representing input B, each followed by arguments that are specific to the input type.
Examples
To check a conversion from a Word document to a DITA map document
java -jar deltaxml-conversion-qa-x.y.z.jar check docx --file mydoc.docx ditamap --file mydoc.zip --mapfile mydoc/mydoc.ditamap
To check a conversion from a XML file to a Word document
java -jar deltaxml-conversion-qa-x.y.z.jar check xml -f doc.xml docx -f doc.docx
To check a conversion from a DITA map document to a single generic XML document
java -jar deltaxml-conversion-qa-x.y.z.jar check ditamap -m doc/doc.ditamap -f doc.zip xml --file doc.xml
Note that you can use either long e.g. --file
or short -f
switches for the sub command options and specify them in any order for each input type sub-command.
describe
This describes the expected arguments for each of the input types.
Examples
Used with no input sub command
% java -jar deltaxml-conversion-qa-x.y.z.jar describe
DeltaXML ConversionQA x.y.z
Released 2023-08-17
Copyright (c) 2023 Deltaman Group Ltd. All rights reserved.
The 'describe' command lists the parameters available for a specific input type
when 'describe' is followed by one of these input types:
'ditamap' - A DITA document passed as a zip file
'docx' - A Microsoft Word document file
'xml' - A non-specific XML format file
To find out about docx input type
% java -jar deltaxml-conversion-qa-x.y.z.jar describe docx
DeltaXML ConversionQA x.y.z
Released 2023-08-17
Copyright (c) 2023 Deltaman Group Ltd. All rights reserved.
Docx Input Type Description
====================================================
Use this input type to specify a Microsoft Word document file, typically with file extension '.docx'
Available Options for 'docx':
====================================================
Option | Short Description
====================================================
--file (-f) | Specify a path to a Microsoft Word document file with extension '.docx'
====================================================
To find out about ditamap input type
% java -jar deltaxml-conversion-qa-x.y.z.jar describe ditamap
DeltaXML ConversionQA x.y.z
Released 2023-08-17
Copyright (c) 2023 Deltaman Group Ltd. All rights reserved.
DITA Input Type Description
====================================================
Use this input type to specify a DITA document.
The document must be a ZIP file containing the dita files and a specified master map file
Available Options for 'ditamap':
====================================================
Option | Short Description
====================================================
--file (-f) | Specify a path to a ZIP file containing a multi-file DITA document
--mapfile (-m) | Specify a path within the ZIP file to the master map file with extension '.ditamap'
====================================================
Input Types
Each of the two inputs can be any of the following input types.
Please also refer to the page Input Types for ConversionQA for a more detailed description of them.
docx
This input type accepts Microsoft Word documents that are in the Office Open XML international standard for Office documents. The file must have a file extension of .docx
.
ditamap
This input type accepts only DITA map documents. When specifying the ditamap input type you need to provide two pieces of information; the path to a zip file containing all the DITA maps and Topics that make up the document, and the relative path of the root DITA map of the document within the zip file.
xml
This input type is for any other format of single file XML document.
Optional Arguments
You can optionally set the location of the directory for the results to be written into. Additionally, set the result prefix as a unique identifier for the result file.
resultLocation=value
This argument accepts a value that will be a string location of the directory you want the results to be written to
resultPrefix=value
This argument accepts a value of string prefix for the result file