From ba62f186f019b1c40019e33c4adda00195949fe8 Mon Sep 17 00:00:00 2001
From: Tom Schraitle <tom_schr@web.de>
Date: Sun, 13 Aug 2023 08:59:53 +0200
Subject: [PATCH] First skeleton of issue #212

---
 src/guide/xml/guide.xml     |  1 +
 src/guide/xml/migration.xml | 37 +++++++++++++++++++++++++++++++++++++
 2 files changed, 38 insertions(+)
 create mode 100644 src/guide/xml/migration.xml

diff --git a/src/guide/xml/guide.xml b/src/guide/xml/guide.xml
index 39e48a7318..80e7e2836b 100644
--- a/src/guide/xml/guide.xml
+++ b/src/guide/xml/guide.xml
@@ -55,6 +55,7 @@ contained herein.</para>
 <xi:include href="ch04.xml"/> <!-- implementation -->
 <xi:include href="ch05.xml"/> <!-- building  -->
 <xi:include href="ver2.xml"/>
+<xi:include href="migration.xml"/><!-- Migration from XSLT 1 -> 3 -->
 <xi:include href="glossary.xml"/>
 <xi:include href="references.xml"/>
 <xi:include href="ackno.xml"/>
diff --git a/src/guide/xml/migration.xml b/src/guide/xml/migration.xml
new file mode 100644
index 0000000000..25696d8b05
--- /dev/null
+++ b/src/guide/xml/migration.xml
@@ -0,0 +1,37 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<appendix xmlns="http://docbook.org/ns/docbook"
+	 xmlns:xlink="http://www.w3.org/1999/xlink"
+	 version="5.0" xml:id="migration">
+  <info>
+    <?db filename="ch-preface"?>
+    <title>Migration from XSLT 1.0 to XSLT 3.0</title>
+  </info>
+
+<!--
+This is the migration chapter for issue #212
+
+Some ideas to cover:
+
+* 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?)
+
+-->
+
+  <para>TBD</para>
+</appendix>
\ No newline at end of file