Version 19.1: plugin integrator fails

[qqzx2kp]

After copying my plugin files into DITA-OT2.x/plugins I attempted to run the integrator using:

bin\dita -install

which failed with the message:

Error: net/sf/saxon/trans/XPathException

I'm using an Administrator command prompt, so that is not the issue. A similar failure occurs when running startcmd.bat and typing "bin\ant -f integrator.xml"

After some experimenting I found that copying saxon-9.1.0.8.jar and saxon-9.1.0.8-dom.jar into the lib folder from a 2.5.2 OT solved the problem.

I presume that either these jars (or equivalent) should have been included in the build, or that dita.bat should have been modified to find them elsewhere.

I'm using version 19.1, build 2017121318. This problem did not occur in version 19.0.

[cosmin_andrei]

Hello,

The DITA-OT that comes bundled with Oxygen is tailored to be used only from inside Oxygen. As it is a customized distribution it might miss some libraries/jars required when using the DITA-OT outside of Oxygen.

In case you specifically need to use the DITA-OT from command line, you should download an external distribution from the official DITA-OT website:
http://www.dita-ot.org/download

Please note that even you decide to run the integrator from inside Oxygen (using the "Run DITA-OT Integrator" predefined scenario), you should still make sure that you start Oxygen with Administrator rights. After you successfully integrate the plugin, you can restart Oxygen with normal user privileges.

[qqzx2kp]

What we want to do is automate the installation of the plugin. Forcing users to install and maintain a separate instance of the OT is not an attractive option.

In version 19.0 the integrator functioned correctly for both DITA-OT and DITA-OT2.x. In version 19.1 it works for DITA-OT, but fails for DITA-OT2.x. Is this change in behaviour intentional? If so, what is the rationale? If not, do you agree that it is a bug that should be fixed?

[Radu]

Hi,

So:

What we want to do is automate the installation of the plugin. Forcing users to install and maintain a separate instance of the OT is not an attractive option.

Having a script which makes automated changes inside the Oxygen installation folder also does not look as an attractive option for me.
In Oxygen 20 we will have a new plugin type capable of contributing a custom DITA OT to Oxygen. So you will be able to create a custom Oxygen plugin contributing a custom DITA OT and then pack this plugin as an add-on and deliver it from your web server. People will be able to install it from the "Help" menu->"Install new add-ons..."

In version 19.0 the integrator functioned correctly for both DITA-OT and DITA-OT2.x. In version 19.1 it works for DITA-OT, but fails for DITA-OT2.x. Is this change in behaviour intentional? If so, what is the rationale? If not, do you agree that it is a bug that should be fixed?

If you use Oxygen's Tools menu->"Compare Directories" utility to compare this folder "OXYGEN_INSTALL_DIR\frameworks\dita\DITA-OT2.x\lib" with a similar folder from a DITA OT 2.5 kit directly from their web site, there are 4 JAR libraries which are missing in the DITA OT 2.x bundled with Oxygen:

icu4j-57.1.jar
saxon-9.1.0.8-dom.jar
saxon-9.1.0.8.jar
xercesImpl-2.11.0.jar

If you manually (or automatically) copy the missing Saxon related JAR libraries to the "OXYGEN_INSTALL_DIR\frameworks\dita\DITA-OT2.x\lib" folder then the "dita -install" should start working again.
So why did "dita -install" work with Oxygen 19.0? Oxygen 19.0 came bundled with DITA OT 2.3.3. DITA OT 2.3.3 did not need the Saxon libraries when the "dita -install" was run.
Oxygen 19.1 comes with the newer DITA OT 2.5.2 which now requires the Saxon libraries when "dita -install" is manually run. This is a change in the publishing engine code that we do not have control over.

We will release Oxygen 20 in about a couple of weeks. Oxygen 20 will come bundled with DITA OT 2.5.4 and will have all the JAR libraries present in it, allowing you to again run "dita -install" inside it without the need of extra libraries.

Regards,
Radu

[qqzx2kp]

Having a script which makes automated changes inside the Oxygen installation folder also does not look as an attractive option for me.

For the record I feel is should correct this, as it could give the impression we are attempting something unsupported or undocumented. The script copies files into the plugin directory of the OT instance and runs the integrator exactly as described in the OT documentation.

If your concern is about third-party scripts making changes in the installation folder that might compromise the behaviour of the editor, that is perfectly understandable. If so, the best solution is to move the bundled OT instances into one of the areas provided by Windows for exactly this purpose. For example, %PROGRAMDATA% or %APPDATA%.

Relocating the OT instances would also remove the ongoing problem of having to run the editor with elevated privileges. Some users are understandably reluctant to select "Run as Administrator", and some may have local policies set by their IT department that disable this option.

The new option for version 20 sounds interesting. Note that if the OT instance is still in a protected area it will need to launch a new process to request elevated privileges.

[Radu]

Hi,

Please see some comments below:

If your concern is about third-party scripts making changes in the installation folder that might compromise the behaviour of the editor, that is perfectly understandable. If so, the best solution is to move the bundled OT instances into one of the areas provided by Windows for exactly this purpose. For example, %PROGRAMDATA% or %APPDATA%.

The problem with us copying the DITA OT in the user's home automatically when the application is installed is that once a new Oxygen version appears and needs to be installed (and it contains a newer DITA OT) we'll have no idea if the end user wants to keep the old DITA OT, if they made changes to the old DITA OT, how we should merge the new DITA OT with the older one and so on.
So we prefer to ship Oxygen with a tested and bundled DITA OT. Once the end user wants to make changes to it, they can also copy it manually outside of Oxygen, set it as the default DITA OT in the "Preferences->DITA" pag and maintain it there.

Relocating the OT instances would also remove the ongoing problem of having to run the editor with elevated privileges. Some users are understandably reluctant to select "Run as Administrator", and some may have local policies set by their IT department that disable this option.

Right.

The new option for version 20 sounds interesting. Note that if the OT instance is still in a protected area it will need to launch a new process to request elevated privileges.

Such an installed add-on would come with a full DITA OT distribution bundled. Oxygen has special functionality for copying add-on related data (the entire DITA OT in this case) to its special folder in the user's home (%APPDATA%\com.oxygenxml\extensions where Oxygen has full access rights), it can update the add-on if a new version is released on the server side and also when a new Oxygen version is installed and started it will ask the end users if they want to keep using the add-ons installed in the previous version with the newer Oxygen version.

Regards,
Radu