Explain how plugins can be developed and kept outside of DITA OT folder
raducoravu opened this issue · 5 comments
In the folder "DITA-OT3.x\config" there is a "configuration.properties" which has a key called "plugindirs" which refers to an enumeration of plugin folders. You can add more "plugins" folder paths there. Running the DITA OT integrator will still make changes to the resources in the DITA OT folder.
I learned this from one of @robander 's presentations but I did not find anything in user's guide about this.
This was added when we still had demo directory. That was removed ages ago and I think we don't have any tests that this still works. It should, but at least I haven't tested this lately.
I used to use this regularly but ran in to some really odd issues that I never managed to track down. I am pretty sure it was something odd in IBM Java that caused the integrator to run very slightly differently. It was something like - running dita --install once made it aware of that directory, but didn't actually install anything; I had to run twice to get it to work. I can't remember exactly and I know that was when we were running 2.5. There could easily have been something else going on too.
When I upgraded our plugins to 3.x I moved everything into plugins/ just because it removed that extra variable. I still like the idea of separating them when I have a large group of plugins for one purpose. But ... I also like keeping things simple so that weird Java quirks don't cause problems.
This property is described as follows in the topic on the configuration.properties file:
A semicolon-separated list of directory paths that DITA-OT searches for plug-ins to install; any relative paths are resolved against the DITA-OT base directory. Any immediate subdirectory that contains a
plugin.xmlfile is installed.
It would probably make sense to expand this explanation to explain the use case in greater detail.
I actively use this mechanism locally to test the plug-in examples in the docs by adding docsrc/samples/plugins to the list of plug-in directories, and can confirm that it still works in recent versions.
For me, it's always been enough to pop the stash in my local clone of the core repo to enable this change, then run dita --install once to bulk-install all the sample plug-ins from the docs. When I'm done testing, I just discard the configuration.properties change and re-run dita --install to remove the sample plug-ins from the default configuration.
Sorry I did not find the mention, I first searched for probably something like “multiple plugins folders”, possibly I should have also searched for “external plugins folder”. Then I searched directly for “configuration.properties” but probably I mistyped because I did not find the topic.
This feature is useful to develop plugins outside plugins folder in a separate version controlled project.