DeltaXML’s XML Compare product includes a Document Comparator, specially enhanced for comparing XML documents with predominantly narrative content. To get the best results from DeltaXML’s XML Document Comparator, you can tailor its configuration, both for specific input document types and for specific outputs. This article shows how to develop the Document Comparator Pipeline (DCP) configuration file using features from DeltaXML’s free XSLT/XPath extension for the popular Visual Studio Code editor. For the rest of this article, I’ll refer to Visual Studio Code as ‘VS Code’ and assume this extension is installed.
Editing DCP with embedded XPath expressions in VS Code
DeltaXML’s DCP format is defined in an XML Schema (1.0 and 1.1 XSD versions are included).
An XML-Schema 1.1 compatible XML editor like OxygenXML (which many of our customers use) is more than sufficient if you are developing a relatively basic DCP file for DeltaXML’s Document Comparator, perhaps with just one or two ‘pipeline parameters’.
VS Code’s DCP editing features provides the same basic features as other such editors, however, it comes into its own when you need a more adaptable DCP configuration, possibly with embedded XPath expressions and a number of pipeline parameters. This might be the case for example, when you’re using the Document Comparator’s REST API.
In Visual Studio Code, create a new file and save it as ‘test.dcp’. The ‘.dcp’ filename extension is recognised and causes ‘DCP’ to be shown in the ‘Language Mode’ part of the status bar at the bottom of the editor.
At the top of the new file editor, enter ‘<' (as you would normally do when adding a new XML element), you will be presented with a list of available ‘code snippets, select ‘Standard Configuration DCP’ from the list. A basic element-structure for a standard DCP is inserted into the editor, with the ‘id’ attribute of the 'documentComparator’ element pre-selected so you can edit this directly. You now have a valid DCP file that you can save again and then invoke from the command-line using the given 'id’ value.
In the editor, type ‘<' to see a list of available DCP snippets
As you edit the DCP file, you will be presented with auto-completion options according to the element or attribute context. If an element-name, attribute-name or attribute-value is invalid, a warning will be shown.
Note: With other XML editors like OxygenXML you can also get this behaviour, you will just need to copy our DCP schema to your file-system and then either create a ‘validation scenario’ or add the relevant xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" namespace and xsi:noNamsepaceLocation attribute declarations.
VS Code’s context-aware auto-completion list
The DCP format supports stringParameter and booleanParameter elements, each with a name attribute. These elements have default attributes with values that can be overriden from the GUI or Command-line user-interfaces or from our REST or Java APIs.
If the Parameter element is declared but the name is not referenced within the DCP, then the name attribute is shown grey-out.
Any DCP element that corresponds to a DocumentComparator setting or an XSLT filter parameter can have one of three attributes: literalValue, parameterRef or xpath.
The VS Code editor will mark as invalid any parameterRef attributes that do not match the name of the appropriately typed (string or boolean) Parameter element. Other XML editors can show associated XML Schema 1.1 assertion error messages but they cannot highlight the specificparameterRef attributes at fault.
DocumentComparator or XSLT filter parameters can be set with an xpath attribute, other attributes (like name on stringParameter and file elements) allow XPath expressions to be enclosed within curly-braces in the same way as XSLT’s attribute-value-templates (AVTs).
For XPath expressions within the DCP, the VS Code editor provides special syntax-highlighting, basic XPath syntax-checking, variable-reference checking and auto-completion.
To help navigate larger DCP files, the Outline View in the Explorer pane shows a tree-view of the DCP file, with special highlighting for parameters etc. Several other VS Code navigation features have been extended with specific support for DCP.
XSLT filters can be inserted into specific parts of the Document Comparator pipeline with the DCP format. XSLT filters for user-defined files or built-in resources are declared as file or resource elements within an element representing a specific ‘extension-point’ in the pipeline.
To add a new XSLT file to the pipeline, enter the relative path for the XSLT in the path attribute that is added with auto-completion. If the XSLT file does not exist, a squiggly-line appears under the path, hover over this to show an ‘action popup’ and then click ‘Follow Link’ on the popup and then click on the ‘Create File’ button.
Click on the ‘Follow Link’ popup-action to create a new XSLT file
You can choose to edit the XSLT filter within VS Code with full XSLT language support from DeltaXML’s extension (see our XSLT/XPath User Guide) or use your own preferred XSLT editor. In VS Code, an XSLT snippet creates a boiler-plate ‘identity transform’ XSLT filter that can be quickly modified to suit your requirement.
The Document Comparator is distributed with a set of built-in XSLT resources. When inserting a built-in XSLT resource, auto-completion is provided for the name attribute of the resource element. The auto-completion list is populated with the names of all built-in XSLT resources.
Choosing an XSLT filter resource-name from the auto-completion list
This article has outlined how DeltaXML’s VSCode extension supports XSLT and DCP language features, providing a dedicated environment to help manage the configuration of a Document Comparator Pipeline. If you want to try it out please install the extension from the VS Code MarketPlace or directly from VS Code.
https://www.deltaxml.com/wp-content/uploads/2024/02/DITA-Table-comparison.png
565
697
Mark Thomas
https://www.deltaxml.com/wp-content/uploads/2021/05/deltaxml-header-logo.png
Mark Thomas2024-02-16 18:11:442024-04-26 15:46:10Mastering Complex Table Comparisons Within Your Technical Documentation
https://www.deltaxml.com/wp-content/uploads/2024/02/DeltaJSON-3-years-2.png
565
697
Sasha Hayden
https://www.deltaxml.com/wp-content/uploads/2021/05/deltaxml-header-logo.png
Sasha Hayden2024-02-13 08:42:202024-04-26 15:45:42Simplifying Your JSON Management Experience with DeltaJSON
https://www.deltaxml.com/wp-content/uploads/2023/12/aviation-changes.png
565
697
Sasha Hayden
https://www.deltaxml.com/wp-content/uploads/2021/05/deltaxml-header-logo.png
Sasha Hayden2023-12-18 11:00:002024-04-26 15:45:06Navigating XML Change in Aviation
https://www.deltaxml.com/wp-content/uploads/2023/09/File-formats-4.png
565
697
Tristan Mitchell
https://www.deltaxml.com/wp-content/uploads/2021/05/deltaxml-header-logo.png
Tristan Mitchell2023-09-28 13:51:562024-04-26 15:44:32File Formats and ConversionQA Functionality
https://www.deltaxml.com/wp-content/uploads/2023/09/INTRO-CQA.png
565
697
Tristan Mitchell
https://www.deltaxml.com/wp-content/uploads/2021/05/deltaxml-header-logo.png
Tristan Mitchell2023-09-27 15:21:372024-04-26 15:44:15Introducing ConversionQA
https://www.deltaxml.com/wp-content/uploads/2023/08/Table-merging.png
565
697
Tristan Mitchell
https://www.deltaxml.com/wp-content/uploads/2021/05/deltaxml-header-logo.png
Tristan Mitchell2023-08-31 03:18:002024-04-26 15:43:56Mastering Table Comparison & Merging: What’s New in XML Merge 11.0.0
https://www.deltaxml.com/wp-content/uploads/2023/08/MTD.png
565
697
Richard Lane
https://www.deltaxml.com/wp-content/uploads/2021/05/deltaxml-header-logo.png
Richard Lane2023-08-14 15:47:532024-04-26 15:43:36Making Tax Digital: Embracing XML Technology for HMRC Compliance
https://www.deltaxml.com/wp-content/uploads/2023/07/sysadmin.png
565
697
Sasha Hayden
https://www.deltaxml.com/wp-content/uploads/2021/05/deltaxml-header-logo.png
Sasha Hayden2023-07-27 08:22:232024-04-26 15:43:19Best Practices for Managing XML Configurations in System Administration
https://www.deltaxml.com/wp-content/uploads/2023/07/ATC-thumbnail.png
565
697
Sasha Hayden
https://www.deltaxml.com/wp-content/uploads/2021/05/deltaxml-header-logo.png
Sasha Hayden2023-07-06 13:24:022024-04-26 15:43:05The Crucial Role of XML and JSON in Modern Air Traffic Control OperationsSign up to the DeltaXML newsletter to get the latest on DeltaXML and other company news.
WHERE CHANGE MATTERS
From ISO Quality Services Ltd.
Save Yourself the Effort of a PhD!
Scroll to top
