learning the DITA-OT using Oxygen's XSLT debugger

[chrispitude]

Hi all,

I'd like to learn more about how the DITA-OT works internally, so I can contribute new features and bug fixes back to the project. (In particular, I would like to develop a publishing solution for cross-book links.)

I have a very basic knowledge of XSLT. Currently I am hand-making small DITA testcases and sprinkling <xsl:message> elements around the DITA-OT preprocess and output files, but this is simply not working.

I would like to be able to pick a particular named processing stage (preprocessing, XHTML, HTML5) and explore its operation in Oxygen's XSLT debugger. What is needed to make this happen? Do I need to hand-modify Ant files to save copies of input files and/or XSLT command lines?

Here is a recent DITA-Users message on this topic:

https://dita-users.groups.io/g/main/message/44954

I think if we unlock the exploration of the DITA-OT internals, it will greatly help the community. Probably the automation of such exploration is a worthy goal in itself.

[Radu]

Hi Chris,

Our XSLT debugger is for pure XSLT processing.
The DITA OT processing is a pipeline set up in ANT build files which mixes Java and XSLT stages, each stage performing a change to a set of resources. There is no way to debug this as a whole, your custom XSLT is applied usually in the last stage, after all the pre-processing which has applied the filtesrs, has resolved conrefs and keyrefs ends. So what you can debug in Oxygen would be the application of an XSLT stylesheet over a temporary XML document representing a topic with all keys and conrefs expanded.
I had a procedure about how to do this for the classic PDF transformation:
https://www.oxygenxml.com/doc/versions/ ... ation.html

One more thing which might be useful would be to look in the DITA OT console view, the ANT build file displays the name of each executed target, so it may give you a better idea about the sequence of targets. I think there should be also in the DITA OT documentation some information about the processing architecture.

Regards,
Radu

[chrispitude]

Hi Radu,

The picture I had in my head was that the processing stages at

https://www.dita-ot.org/dev/reference/p ... ssing.html

were applied one at a time. And if you made a copy of the working directory between the steps, you'd have a series of snapshot directories that you could diff -- or rerun the transforms manually -- to more closely investigate what's going on in that step.

(This would apply to output-side stages after preprocessing too.)

I guess I should buy a book on Ant so I can try to see how all this is controlled.

[Radu]

Hi Chris,

Yes, so all these stages are applied sequentially, the first stage takes the files from the input folder and moves them to the temporary files folder, all the other stages except for the last one read and write the files directly from and into the temporary files folder.
Most of the pre-processing is done with Java code called from the ANT build files. Ideally developers who customize the DITA OT would only work with the XSLT stylesheets which are applied after all the heavy stuff (resolution of conrefs, keyefs, filtering) has been done.

Regards,
Radu