How to migrate DocBook XSLT 1.0 stylesheets to 3.0?

[Thomas Schraitle <tom_schr@web.de>]

Hi,

the DocBook XSLT 1.0 stylesheets served us very well over the years. However,
as more and more features are implemented in DocBook 5, the more difficult
becomes it to add them into the XSLT 1.0 code base.

As far as I see, the new XSLT 3.0 stylesheets[1] tries to create the foundation
for this. Luckily, Norman provided a very detailed documentation[2] how to use
them. I'm very grateful for this and it's very helpful. Thank you very much!

I played a bit around with them. However, I'm more interested in how to
_migrate_ from the older XSLT 1.0 stylesheets to the new ones. If I'm not
mistaken, there is no such documentation yet, right? I hope this question could
serve as a starting point to collect some ideas and to amend the documentation.

Currently, we use an extensive customization layer of the DocBook XSLT 1.0
stylesheets which support HTML and PDF through XSL-FO. We use xsltproc to
transform them. We even created a tool chain to help us with profiling etc.
This works quite well and we are happy with this.

However, as XSLT 1.0 has some limitations and needs workarounds, I'm searching
for a way if this code base could be migrated somehow. Therefor I'm looking for
some tips and tricks, best practices, or recommendations.

How would you proceed with this? I suppose it isn't easy and needs a complete
rewrite?

Before I start that task, I have some specific questions which hopefully helps
me to understand this better:

1. Compatibility mode in Saxon11?
   As we currently use xsltproc, would it make sense to gradually replace the
   XSLT processor with Saxon 11 and still using the XSLT 1.0 stylesheets?
   Just to get some experiences etc.
   I suppose Saxon 11 has a compatibility mode for XSLT 1.0. However, some
   extension functions and elements in the XSLT 1.0 stylesheets could be
   problematic as they don't exist in Saxon 11, right?

2. Speed?
   When we tried Saxon 6, we measured it is ~3x slower than xsltproc.
   This is probably not a surprise (Java versus C).

   We have quite an extensive DocBook code base. To build all product
   documentation for HTML and PDF takes a long time. If we multiply it by
   a factor N it takes even longer. So that's an important point for us.

   I've read somewhere that the slower start up time is due to the Java
   engine. Once it is started it is more or less comparable with xsltproc.
   Is it correct?

   Can we start Saxon 11 in a kind of "background mode" where it waits
   and listens to some transformation requests? Would that be possible?

3. How to deal with XSL-FO?
   Currently, the xslTNG stylesheets don't support XSL-FO (yet).
   Nowadays it's recommended to use some (print) CSS to create PDF.
   There are commercial offerings for this task, but we are looking
   for an open source solution. Would a browser engine sufficient too?
   Or are there any other tools recommendations?

   The other option would be to implement XSL-FO. However, I think, that
   would be quite a big task, wouldn't it? Is it planned to implement
   it?

   What would you use to provide PDF?

4. Recommendations? Best practices?
   Are there any recommendation to follow, traps to avoid etc.?


Thanks for all your ideas and thoughts! :-)


--- References
[1] https://github.com/docbook/xslTNG
[2] https://xsltng.docbook.org/

--
GruÃ/Regards
  Thomas Schraitle