Running with Oxygen

XSpec is integrated with the SyncRO Soft Oxygen XML Editor since version 14.0. Check out its official Oxygen documentation.

SyncRO Soft published a webinar on testing XSLT and Schematron with XSpec:

Running the Latest Version of XSpec with Oxygen

Sometimes you may want to run the latest version of XSpec instead of the built-in version. There are several ways to do that:

• Loading XSpec via Oxygen Add-on
• Loading XSpec via Oxygen Project
• Loading XSpec via Oxygen Global Preferences
• Configuring XSpec Transformation Scenario
• Overwriting the Built-In XSpec (not recommended)

Select one of them best suited to your needs.

Note that if you're using XSpec Helper view add-on, its companion framework add-on takes precedence over most of the proposed ways. Only Configuring XSpec Transformation Scenario will work. The other ways proposed here will not take effect.

Loading XSpec via Oxygen Add-on

This approach lets you automatically stay up-to-date with a recent snapshot of the master branch of this repository.

To take this approach, you install an Oxygen add-on published from this repository.

1. Oxygen menu - Help - Install new add-ons.

2. Specify https://github.com/xspec/xspec/raw/master/oxygen-addon.xml in Show add-ons from box.

3. Check XSpec and click Next.

4. Check I accept all the terms... and click Install.

5. "Not all selected add-ons have valid signatures..." warning pops up. Click Continue anyway.

6. "To apply these changes, you must restart..." notification pops up. Click OK.

7. Restart Oxygen. It may take some time.

That's it. From now on, XSpec installed by the add-on always takes effect. The add-on will automatically notify you whenever a notable change is made to the master branch and let you update the add-on.

Loading XSpec via Oxygen Project

This approach has a limited impact on your Oxygen environment. In this approach, the latest version of XSpec takes effect only when you're working with a specific project file opened.

To take this approach, you clone this repository and configure Oxygen project level options to load the cloned XSpec.

1. Extract the source code archive file of the latest master branch, or alternatively clone this repository. For example, clone it into /test/xspec/ (Linux/macOS) or C:\test\xspec\ (Windows).

   Linux/macOS:

   git clone https://github.com/xspec/xspec.git /test/xspec

   Windows:

   git clone https://github.com/xspec/xspec.git C:\test\xspec

2. In Oxygen, open your existing project file, if you have one, or create a new project file by selecting Project - New Project.

3. With your project opened, select Options - Preferences.

4. In Preferences - Document Type Association - Locations, select Project Options. (By default, Global Options is selected.)

5. Click Add to add the repository root directory (/test/xspec or C:\test\xspec) to Additional frameworks directories.

6. Click OK to close Preferences.

That's it. From now on, the cloned version of XSpec takes effect only when you're working with the configured project file opened. When you switch to another project, the built-in version XSpec takes effect.

This repository has a project file preconfigured in a way similar to the above steps. To try out the preconfigured project file, just select Project - Open Project to open /test/xspec/xspec.xpr or C:\test\xspec\xspec.xpr and the cloned XSpec should take effect.

Loading XSpec via Oxygen Global Preferences

This approach has a global impact on your Oxygen environment, and the latest version of XSpec always takes effect.

To take this approach, you clone this repository and configure Oxygen global options to load the cloned XSpec.

1. Extract the source code archive file of the latest master branch, or alternatively clone this repository. For example, clone it into /test/xspec/ (Linux/macOS) or C:\test\xspec\ (Windows).

   Linux/macOS:

   git clone https://github.com/xspec/xspec.git /test/xspec

   Windows:

   git clone https://github.com/xspec/xspec.git C:\test\xspec

2. In Oxygen menu, select Options - Preferences.

3. In Preferences - Document Type Association - Locations, make sure Global Options is selected.

4. Click Add to add the repository root directory (/test/xspec or C:\test\xspec) to Additional frameworks directories.

5. Click OK to close Preferences.

6. Restart Oxygen.

That's it. From now on, the cloned version of XSpec always takes effect.

Configuring XSpec Transformation Scenario

This approach has the least impact on your Oxygen environment. In this approach, the latest version of XSpec takes effect only when you run a specific Transformation Scenario. The latest version of the XSpec schema does not take effect in your Oxygen editing environment.

To take this approach, you duplicate the built-in transformation scenario and specify an external XSpec to use with your copy of the transformation scenario.

1. Extract the source code archive file of the latest master branch, or alternatively clone this repository. For example, clone it into /test/xspec/ (Linux/macOS) or C:\test\xspec\ (Windows).

   Linux/macOS:

   git clone https://github.com/xspec/xspec.git /test/xspec

   Windows:

   git clone https://github.com/xspec/xspec.git C:\test\xspec

   Make sure you now have /test/xspec/build.xml or C:\test\xspec\build.xml.

2. In Oxygen, open your .xspec file.

3. In the Transformation Scenarios pane, duplicate Run XSpec Test.

4. In the Options tab of Edit Ant Scenario dialog, specify /test/xspec or C:\test\xspec in Working directory.

5. In the Parameters tab, set xspec.project.dir = /test/xspec/ or C:\test\xspec.

6. If the catalog parameter uses ${pdu}, replace it with ${pd}.

   XSpec v2.x: You may want to discard the current value in catalog and just set ${xmlCatalogFilesList}.

7. XSpec v2.x: If the catalog parameter is ${xmlCatalogFilesList}, the catalog.is.uri parameter must be true. If the parameter is missing, click New to add it.

8. Depending on your Oxygen version, you may need to edit or add more parameters such as test.type or xspec.fail.

9. If you normally customize the standard Run XSpec Test scenario, such as to specify additional libraries, JVM options, or saxon.custom.options, do that now. ( Upcoming v3.2) You can also select a color palette for HTML reports, such as blackwhite (default; black on white), whiteblack (white on black), or classic (earlier green/pink design), using xspec.html.report.theme on the Parameters tab.

10. Click OK to close the Edit Ant Scenario dialog.

11. Apply the new transformation scenario.

Oxygen runs XSpec and opens the test result report HTML in your default browser.

Overwriting the Built-In XSpec

Copying this repository over to the built-in [Oxygen installation]/frameworks/xspec folder would work, but this is not recommended.