Providing DITA plugins in an Oxygen project directory?

[chrispitude]

Hi all,

Is it possible to provide a DITA plugin in an Oxygen project directory?

From Radu's post in this thread (post53923.html?hilit=dita%20framework#p53824), the answer is currently no. But what would it take to make this work?

Our DITA books and PDF Chemistry publishing files are all stored in a Github repo that any writer can sync to their laptop. As we update the CSS files, all writers inherit the updates for the XML Author editor and the PDF output.

We would really like to have our DITA plugins (primarily the grammar plugin) also stored in the Git repo, so updates are synchronized to the writers' machines automatically -- without the need to manually copy them to modify the Oxygen XML Author installation directory.

On Windows, I wonder if an NTFS filesystem link could serve the purpose... It would still require a one-time creation, but then updates would be automatic. I'll try it and report back!

[Radu]

Hi Chris,

In the DITA Open Toolkit there is a configuration file:

OXYGEN_INSTALL_DIR\frameworks\dita\DITA-OT3.x\config\configuration.properties

in which the paths to all plugin folders are specified:

Code: Select all

plugindirs = plugins;demo

So whatever plugin folders are there, when you run the DITA OT integrator, those plugins will be installed and taken into account for publishing.
This is all the publishing engine provides.

If your writers do not actually need to publish, you can just distribute your DITA OT specialization plugin inside the project and unconnected to a DITA OT.
Then in the Oxygen Preferences->"XML / XML Catalog" page you can add a reference to the catalog.xml from the plugin folder. The reference can use the ${pdu} editor variable and you can switch the entire "XML Catalog" page to "Project options" so that once they open the "project.xpr" in Oxygen they get this already set up.
This will make validation and content completion work, the publishing will not work unless the publishing engine knows about this plugin.

Another approach:
Take an entire DITA OT distribution and include it in the Git Project. Change the Oxygen Preferences->"DITA" page to point to that custom DITA OT distribution from the project, save the page at project level.

Regards,
Radu

[chrispitude]

Hi Radu,

I was able to get NTFS filesystem links to work! (And linux filesystem works should work equally well.)

I created a

Code: Select all

link_to_oxygen.bat

file in my project directory (in

Code: Select all

${pd}/prj/

, where I store other miscellaneous project resources). My DITA plugin directory is in this directory.

The batch file (1) makes a filesystem link from the plugin to the Oxygen installation's DITA-OT directory, then (2) integrates it into Oxygen's DITA-OT:

Code: Select all

mklink /J "c:\Program Files\Oxygen XML Author 21\frameworks\dita\DITA-OT3.x\plugins\com.synopsys.docshell" "dita_plugins\com.synopsys.docshell"

"c:\program files\oxygen xml author 21\jre/bin/java" -Dfile.encoding=UTF-8 -Xmx256m -classpath "C:\Program Files\Oxygen XML Author 21\tools\ant/lib/ant-launcher.jar" "-Dant.home=C:\Program Files\Oxygen XML Author 21\tools\ant" org.apache.tools.ant.launch.Launcher -lib "C:\Program Files\Oxygen XML Author 21\frameworks\dita\DITA-OT3.x\config" -lib "C:\Program Files\Oxygen XML Author 21\classes" -lib "C:\Program Files\Oxygen XML Author 21\lib\oxygen.jar" -lib "C:\Program Files\Oxygen XML Author 21\lib\oxygenAuthor.jar" -lib "C:\Program Files\Oxygen XML Author 21\lib\oxygenDeveloper.jar" -lib "C:\Program Files\Oxygen XML Author 21\lib\oxygenEclipse.jar" -lib "C:\Program Files\Oxygen XML Author 21\lib\oxygenAuthorEclipse.jar" -lib "C:\Program Files\Oxygen XML Author 21\lib\oxygenDeveloperEclipse.jar" -lib "C:\Program Files\Oxygen XML Author 21\lib\oxygen-basic-utilities.jar" -lib "C:\Program Files\Oxygen XML Author 21\lib\oxygen-editor-variables-parser.jar" -lib "C:\Program Files\Oxygen XML Author 21\lib\oxygen-patched-resolver.jar" -lib "C:\Program Files\Oxygen XML Author 21\lib\xml-apis.jar" -lib "C:\Program Files\Oxygen XML Author 21\lib\oxygen-patched-xerces.jar" -lib "C:\Program Files\Oxygen XML Author 21\lib\oxygen-patched-saxon-9.jar" -lib "C:\Program Files\Oxygen XML Author 21\lib\saxon9-sql.jar" -lib "C:\Program Files\Oxygen XML Author 21\lib\log4j.jar" -lib "C:\Program Files\Oxygen XML Author 21\frameworks\dita\DITA-OT3.x\plugins\com.oxygenxml.dost.patches\lib\oxygen-dost-patches.jar" -lib "C:\Program Files\Oxygen XML Author 21\frameworks\dita\DITA-OT3.x\lib\ant-apache-resolver-1.10.5.jar" -lib "C:\Program Files\Oxygen XML Author 21\frameworks\dita\DITA-OT3.x\lib\ant-launcher.jar" -lib "C:\Program Files\Oxygen XML Author 21\frameworks\dita\DITA-OT3.x\lib\ant.jar" -lib "C:\Program Files\Oxygen XML Author 21\frameworks\dita\DITA-OT3.x\lib\commons-io-2.6.jar" -lib "C:\Program Files\Oxygen XML Author 21\frameworks\dita\DITA-OT3.x\lib\dost-configuration.jar" -lib "C:\Program Files\Oxygen XML Author 21\frameworks\dita\DITA-OT3.x\lib\dost.jar" -lib "C:\Program Files\Oxygen XML Author 21\frameworks\dita\DITA-OT3.x\lib\guava-25.1-jre.jar" -lib "C:\Program Files\Oxygen XML Author 21\frameworks\dita\DITA-OT3.x\lib\icu4j-61.1.jar" -lib "C:\Program Files\Oxygen XML Author 21\frameworks\dita\DITA-OT3.x\lib\isorelax-20030108.jar" -lib "C:\Program Files\Oxygen XML Author 21\frameworks\dita\DITA-OT3.x\lib\jackson-annotations-2.9.0.jar" -lib "C:\Program Files\Oxygen XML Author 21\frameworks\dita\DITA-OT3.x\lib\jackson-core-2.9.8.jar" -lib "C:\Program Files\Oxygen XML Author 21\frameworks\dita\DITA-OT3.x\lib\jackson-databind-2.9.8.jar" -lib "C:\Program Files\Oxygen XML Author 21\frameworks\dita\DITA-OT3.x\lib\jing-20181222.jar" -lib "C:\Program Files\Oxygen XML Author 21\frameworks\dita\DITA-OT3.x\lib\logback-classic-1.2.3.jar" -lib "C:\Program Files\Oxygen XML Author 21\frameworks\dita\DITA-OT3.x\lib\logback-core-1.2.3.jar" -lib "C:\Program Files\Oxygen XML Author 21\frameworks\dita\DITA-OT3.x\lib\Saxon-HE-9.8.0-14.jar" -lib "C:\Program Files\Oxygen XML Author 21\frameworks\dita\DITA-OT3.x\lib\slf4j-api-1.7.25.jar" -lib "C:\Program Files\Oxygen XML Author 21\frameworks\dita\DITA-OT3.x\lib\xercesImpl-2.12.0.jar" -lib "C:\Program Files\Oxygen XML Author 21\frameworks\dita\DITA-OT3.x\lib\xml-apis-1.4.01.jar" -lib "C:\Program Files\Oxygen XML Author 21\frameworks\dita\DITA-OT3.x\lib\xml-resolver-1.2.jar" -f "C:\Program Files\Oxygen XML Author 21\frameworks/dita/DITA-OT3.x/integrator.xml" "-Dstrict=true" "-Dwebhelp.trial.license=no"

So basically, any user can clone our project's Git repo to their laptop, double-click this batch file, and begin editing and publishing our DITA files. Because the batch file is located in the local repo directory where the plugin is, the filesystem link is created properly no matter where the user places their local repo.

I don't like how long the integration command line is; I just copied it from a log window in Oxygen XML Author. I tried using the startcmd.bat script but it couldn't find java.exe, and I'm not very good with CMD.exe scripting.

[Radu]

Hi Chris,

One problem I see is that on most computers the path "C:\Program Files\Oxygen XML Author 21\" is a read-only folder path, editable only if somebody runs the script with administrative privileges. This means that running the DITA OT integrator would fail.
So you would need to instruct the end users to install Oxygen in a folder path where they have full write access (like in their user home).

Regards,
Radu

[chrispitude]

I'm glad you caught this! On my laptop, I had opened up permissions in the DITA-OT directory inside Oxygen's install directory.

I removed the plugin link and integrated to remove it, then removed my user permissions from the DITA-OT, then right-clicked the batch file and chose "Run as Administrator." It still worked - both the link and the plugin catalog update! And to prove that it overcame the permissions, Windows now won't let me delete the plugin link in the plugins/ folder without Administrator privileges.

[chrispitude]

Updated to fix some cases:

Code: Select all

pushd %~dp0
rmdir "c:\Program Files\Oxygen XML Author 21\frameworks\dita\DITA-OT3.x\plugins\com.synopsys.docshell" 2> nul
mklink /J "c:\Program Files\Oxygen XML Author 21\frameworks\dita\DITA-OT3.x\plugins\com.synopsys.docshell" "dita_plugins\com.synopsys.docshell"
popd

"c:\program files\oxygen xml author 21\jre/bin/java" -Dfile.encoding=UTF-8 -Xmx256m -classpath "C:\Program Files\Oxygen XML Author 21\tools\ant/lib/ant-launcher.jar" "-Dant.home=C:\Program Files\Oxygen XML Author 21\tools\ant" org.apache.tools.ant.launch.Launcher -lib "C:\Program Files\Oxygen XML Author 21\frameworks\dita\DITA-OT3.x\config" -lib "C:\Program Files\Oxygen XML Author 21\classes" -lib "C:\Program Files\Oxygen XML Author 21\lib\oxygen.jar" -lib "C:\Program Files\Oxygen XML Author 21\lib\oxygenAuthor.jar" -lib "C:\Program Files\Oxygen XML Author 21\lib\oxygenDeveloper.jar" -lib "C:\Program Files\Oxygen XML Author 21\lib\oxygenEclipse.jar" -lib "C:\Program Files\Oxygen XML Author 21\lib\oxygenAuthorEclipse.jar" -lib "C:\Program Files\Oxygen XML Author 21\lib\oxygenDeveloperEclipse.jar" -lib "C:\Program Files\Oxygen XML Author 21\lib\oxygen-basic-utilities.jar" -lib "C:\Program Files\Oxygen XML Author 21\lib\oxygen-editor-variables-parser.jar" -lib "C:\Program Files\Oxygen XML Author 21\lib\oxygen-patched-resolver.jar" -lib "C:\Program Files\Oxygen XML Author 21\lib\xml-apis.jar" -lib "C:\Program Files\Oxygen XML Author 21\lib\oxygen-patched-xerces.jar" -lib "C:\Program Files\Oxygen XML Author 21\lib\oxygen-patched-saxon-9.jar" -lib "C:\Program Files\Oxygen XML Author 21\lib\saxon9-sql.jar" -lib "C:\Program Files\Oxygen XML Author 21\lib\log4j.jar" -lib "C:\Program Files\Oxygen XML Author 21\frameworks\dita\DITA-OT3.x\plugins\com.oxygenxml.dost.patches\lib\oxygen-dost-patches.jar" -lib "C:\Program Files\Oxygen XML Author 21\frameworks\dita\DITA-OT3.x\lib\ant-apache-resolver-1.10.5.jar" -lib "C:\Program Files\Oxygen XML Author 21\frameworks\dita\DITA-OT3.x\lib\ant-launcher.jar" -lib "C:\Program Files\Oxygen XML Author 21\frameworks\dita\DITA-OT3.x\lib\ant.jar" -lib "C:\Program Files\Oxygen XML Author 21\frameworks\dita\DITA-OT3.x\lib\commons-io-2.6.jar" -lib "C:\Program Files\Oxygen XML Author 21\frameworks\dita\DITA-OT3.x\lib\dost-configuration.jar" -lib "C:\Program Files\Oxygen XML Author 21\frameworks\dita\DITA-OT3.x\lib\dost.jar" -lib "C:\Program Files\Oxygen XML Author 21\frameworks\dita\DITA-OT3.x\lib\guava-25.1-jre.jar" -lib "C:\Program Files\Oxygen XML Author 21\frameworks\dita\DITA-OT3.x\lib\icu4j-61.1.jar" -lib "C:\Program Files\Oxygen XML Author 21\frameworks\dita\DITA-OT3.x\lib\isorelax-20030108.jar" -lib "C:\Program Files\Oxygen XML Author 21\frameworks\dita\DITA-OT3.x\lib\jackson-annotations-2.9.0.jar" -lib "C:\Program Files\Oxygen XML Author 21\frameworks\dita\DITA-OT3.x\lib\jackson-core-2.9.8.jar" -lib "C:\Program Files\Oxygen XML Author 21\frameworks\dita\DITA-OT3.x\lib\jackson-databind-2.9.8.jar" -lib "C:\Program Files\Oxygen XML Author 21\frameworks\dita\DITA-OT3.x\lib\jing-20181222.jar" -lib "C:\Program Files\Oxygen XML Author 21\frameworks\dita\DITA-OT3.x\lib\logback-classic-1.2.3.jar" -lib "C:\Program Files\Oxygen XML Author 21\frameworks\dita\DITA-OT3.x\lib\logback-core-1.2.3.jar" -lib "C:\Program Files\Oxygen XML Author 21\frameworks\dita\DITA-OT3.x\lib\Saxon-HE-9.8.0-14.jar" -lib "C:\Program Files\Oxygen XML Author 21\frameworks\dita\DITA-OT3.x\lib\slf4j-api-1.7.25.jar" -lib "C:\Program Files\Oxygen XML Author 21\frameworks\dita\DITA-OT3.x\lib\xercesImpl-2.12.0.jar" -lib "C:\Program Files\Oxygen XML Author 21\frameworks\dita\DITA-OT3.x\lib\xml-apis-1.4.01.jar" -lib "C:\Program Files\Oxygen XML Author 21\frameworks\dita\DITA-OT3.x\lib\xml-resolver-1.2.jar" -f "C:\Program Files\Oxygen XML Author 21\frameworks/dita/DITA-OT3.x/integrator.xml" "-Dstrict=true" "-Dwebhelp.trial.license=no"

timeout 20

If anyone knows the minimum DITA-OT command line to run integration, please let me know!

[Radu]

Hi Chris,

This should also work:

OXYGEN_INSTALL_DIR\frameworks\dita\DITA-OT3.x\bin\dita --install

https://www.dita-ot.org/dev/topics/plug ... lling.html

As the "dita.bat" will by default use the JAVA_HOME editor variable maybe you can set that in your script to the Java bundled with Oxygen so that even if people do not have Java installed separately the bat will still work.

Regards,
Radu

[chrispitude]

Hi Radu,

Good suggestion! This works much better:

Code: Select all

set OXYGEN_HOME=c:\Program Files\Oxygen XML Author 21

pushd %~dp0
rmdir "%OXYGEN_HOME%\frameworks\dita\DITA-OT3.x\plugins\com.synopsys.docshell" 2> nul
mklink /J "%OXYGEN_HOME%\frameworks\dita\DITA-OT3.x\plugins\com.synopsys.docshell" "dita_plugins\com.synopsys.docshell"
popd

set JAVA_HOME=%OXYGEN_HOME%\jre
call "%OXYGEN_HOME%\frameworks\dita\DITA-OT3.x\bin\dita.bat" --install

timeout 20

I also filed an Ant enhancement request (https://bz.apache.org/bugzilla/show_bug.cgi?id=63577) to suppress the tools.jar warning message when the DITA-OT is run with a JRE instead of a JDK.

[Radu]

Hi Chris,

Great, I added a comment on your new issue.

Regards,
Radu

[chrispitude]

Here is a greatly improved script with error checking and support for both Author and Editor installations.

Code: Select all

@rem chrispy - 2/13/2020
@echo off

net session >nul 2>&1
if %ERRORLEVEL% neq 0 (
 echo Error: You must run this script by right-clicking and choosing "Run as administrator".
 timeout 20
 EXIT /b 1
)

if exist "c:\Program Files\Oxygen XML Author 22\oxygenAuthor22.0.exe" (
 call :install_plugin "c:\Program Files\Oxygen XML Author 22"
)

if exist "c:\Program Files\Oxygen XML Editor 22" (
 call :install_plugin "c:\Program Files\Oxygen XML Editor 22"
)

if not exist "c:\Program Files\Oxygen XML Author 22\oxygenAuthor22.0.exe"
if not exist "c:\Program Files\Oxygen XML Editor 22" (
 echo No Oxygen XML Author or Oxygen XML Editor installations found.
)

timeout 20
exit /b



:install_plugin
set OXYGEN_HOME=%1
set OXYGEN_HOME=%OXYGEN_HOME:"=%

echo Installing DITA-OT plugins in %OXYGEN_HOME%...
echo (ignore the "no tools.jar found" message)^


pushd %~dp0
rmdir "%OXYGEN_HOME%\frameworks\dita\DITA-OT3.x\plugins\com.synopsys.plugin1" 2> nul
rmdir "%OXYGEN_HOME%\frameworks\dita\DITA-OT3.x\plugins\com.synopsys.plugin2" 2> nul
mklink /J "%OXYGEN_HOME%\frameworks\dita\DITA-OT3.x\plugins\com.synopsys.plugin1" "dita_plugins\com.synopsys.plugin1"
mklink /J "%OXYGEN_HOME%\frameworks\dita\DITA-OT3.x\plugins\com.synopsys.plugin2" "dita_plugins\com.synopsys.plugin2"
popd

set JAVA_HOME=%OXYGEN_HOME%\jre
call "%OXYGEN_HOME%\frameworks\dita\DITA-OT3.x\bin\dita.bat" --install