Consider a migration guide from XSLT 1.0 -> 3.0

[tomschr]

Situation

I brought up this idea in the docbook-apps mailinglist. Not sure if this is the appropriate place as docbook/docbook is solely for the schema. Feel free to move it or close it.

DocBook and the DocBook XSLT 1.0 stylesheets are mature systems. Over time, possibly a lot of people created customization layers to adapt the output to their needs. However, although the DocBook schema got updated, the XSLT 1.0 stylesheets were written for DocBook 4 in mind. Although they support DocBook 5 as well, some features are still missing.

The xslTNG stylesheets are a great project to get a more modern approach and to support more features of DocBook 5. If this is the future, we probably should tell our users how to migrate from an existing XSLT 1.0 code base to the new 3.0 stylesheets.

Possible solutions

I kindly ask for some kind of "migration guide". If this could be a chapter in an existing guide, a separate guide, or just a checklist is to be defined. I could anticipate that such a "guide" could cover the following topics:

• The benefits of moving to the new stylesheets (that's probably mostly covered in this project already)
• Target groups (probably developers that already wrote customization layers?)
• Requirements:
  • Skills needed (certainly some XSLT/XPath 3.0 would be useful)
  • Software (perhaps Saxon9-12. Other XSLT 3.0 processors aren't available at the moment, right?)
  • System (the necessary dependencies, Docker images, or other requirements etc.)
• Migration considerations
• Tips and recommendations
• Best practices
• Traps or things to avoid (for example, how to migrate extension elements/functions from other XSLT processors, like exsl:node-set)
• Testing
  The xslTNG stylesheets contains test cases which is really great! How can we use this for a migration project?
• Costs
  Not so from a financial aspect, but more about:
  • Speed (is it slower/faster than the DocBook XSLT 1.0 stylesheets with xsltproc? By what factor? What can we do to speed up things?)
  • Time (how much effort is it to move an existing code base? I know, that's hard to answer, but maybe there are some experiences?)
  • Complete rewrite? (when it is useful to just throw away the existing code base and start from scratch? Any experience?)

So these are just some ideas that came into my mind. I think, this would answer a lot of questions that someone might have and ease the migration.

Thank you!

[ndw]

I think this is a great idea, but I haven't looked at or thought about the 1.0 stylesheets in maybe a decade or 15 years. I'd be very happy to answer questions and make suggestions, but I think we'd need someone else to volunteer to take on the task.

[tomschr]

Thank you Norm for your answer, much appreciated.

I have a very basic understanding yet, but once I get more familiar with the new stylesheets and get some experience I'm happy to write something for you. However, it can take some time.

[frank-steimke]

The xref/@xrefstyle attribute is not supported by the xslTNG Stylesheets. There are two more or less sophisticated techniques for the use of this attribute with the select: or the template: keyword, see Customizing cross references in the XSL 1.0 Guide from Bob Stayton.

If the xslTNG Stylesheets won't support this attribute in the Future, then this would be a subject for a migration Guide. @tomschr, did you start with the guide? Maybe i can contribute?

[tomschr]

Hi @frank-steimke, 👋

I haven't started with such a guide yet. Thanks for the reminder! So I've started the above PR #405 as a playground. It doesn't contain anything useful yet apart from the first skeleton and the comment of all ideas. The "guide" is basically an appendix for the time being.

If you like, we can add your ideas in the migration.xml file that is mentioned in the PR.

Would that work?

[frank-steimke]

Hi Tom,

sure, i am happy to contribute if i can.

I think the first section in the guid should be: why should we need a migration guide?

DocBook is just a markup language, why can't you switch the stylesheet to product HTML or PDF in a minute? Where are the differences, what does migration really mean?

• different tools. For PDF with Version 1 you need a FOP Processor which is available for free from apache. For PDF with version 3 you need a CSS Renderer. I know only of commercial products (Antenna House, Prince).
• migration of customization layers. If you have done more than just basic customization for layout, corporate design, integration of Logo, titlepages and so on, you have to move from FO to CSS pages media. There are excellent documents (and videos from XML Prague events) from Antenna House for FO vs paged media comparison
• different use of docbook. The xref/@xrefstyle issue that i mendioned is of this catecory