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.

BASH

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:

CODE

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.

BASH

% 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] [ignoreelementsxpaths="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

CODE

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

CODE

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

CODE

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

CODE

% 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

CODE

% 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

CODE

% 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

ignoreelementsxpaths=”value”

This argument accepts a value of a string specifying an xpath that you want to ignore when checking two files. You can specify more than one xpath by seperating it with a comma.