From 91b5abcaed850639cde8808076cf76719b9cc669 Mon Sep 17 00:00:00 2001
From: Vivien Kraus <vivien@planete-kraus.eu>
Date: Thu, 6 Oct 2022 23:16:54 +0200
Subject: Add a new chapter to beautify listing inclusion in book.

---
 mped.xml | 107 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++--
 1 file changed, 104 insertions(+), 3 deletions(-)

diff --git a/mped.xml b/mped.xml
index 8739fcf..fb8c4d0 100644
--- a/mped.xml
+++ b/mped.xml
@@ -251,9 +251,7 @@
         makes cross-referencing easier.
       </para>
       <figure xml:id="tangle-mped-copy">
-        <title>
-          Insert literally a listing in another when tangling
-        </title>
+        <title>Insert literally a listing in another when tangling</title>
         <programlisting language="xml">
           <![CDATA[
 <xsl:template match="mped:copy" mode="copy-source-code">
@@ -315,4 +313,107 @@
       </figure>
     </section>
   </chapter>
+  <chapter>
+    <title>Displaying the source code: back to docbook!</title>
+    <para>
+      Now that the program is written, the mped tags are not required
+      anymore. We need to remove them, and embed their semantics into
+      docbook. For instance, the &lt;mped:copy&gt; tag that links to
+      other listings must be replaced with a comment instructing the
+      reader to insert the correct listing at this location.
+    </para>
+    <para>
+      To achieve this, we create a new stylesheet, that runs across
+      the document, and produces a list of templates to remove mped
+      elements.
+    </para>
+    <section>
+      <title>Clean program listings</title>
+      <para>
+        We need to replace the &lt;mped:copy&gt; tags within the
+        program listing, with the title of the listing as a
+        comment. See <xref linkend="insert-xml-co-comment" /> to put
+        the comment in the XML language, and <xref
+        linkend="insert-default-co-comment" /> for a default language
+        (do not put a comment).
+      </para>
+      <figure xml:id="insert-xml-co-comment">
+        <title>Insert a call-out comment in XML</title>
+        <programlisting language="xml">
+          <![CDATA[
+<xsl:template match="mped:copy[../@language = 'xml']">
+  <xsl:text>&lt;!-- </xsl:text>
+  <xsl:variable name="id" select="@linkend" />
+  <xsl:element name="xref"
+               namespace="http://docbook.org/ns/docbook">
+    <xsl:attribute name="linkend">
+      <xsl:value-of select="$id" />
+    </xsl:attribute>
+  </xsl:element>
+  <xsl:text> --></xsl:text>
+</xsl:template>
+        ]]>
+        </programlisting>
+      </figure>
+      <figure xml:id="insert-default-co-comment">
+        <title>Do not insert a call-out if the language comment syntax is unknown</title>
+        <programlisting language="xml">
+          <![CDATA[
+<xsl:template match="mped:copy" />
+        ]]>
+        </programlisting>
+      </figure>
+      <para>
+        Finally, all other elements must be copied as-is. This is why
+        the catch-all template <xref linkend="copy-everything-else" />
+        is used.
+      </para>
+      <figure xml:id="copy-everything-else">
+        <title>Copy everything else without modification</title>
+        <programlisting language="xml">
+          <![CDATA[
+<xsl:template match="@*|node()">
+  <xsl:copy>
+    <xsl:apply-templates select="@*|node()" />
+  </xsl:copy>
+</xsl:template>
+        ]]>
+        </programlisting>
+      </figure>
+    </section>
+    <section>
+      <title>Putting it all together</title>
+      <para>
+        The collection of all these templates gives a full stylesheet,
+        in <xref linkend="whole-unmped-stylesheet" />.
+      </para>
+      <figure xml:id="whole-unmped-stylesheet">
+        <title>The full stylesheet to apply mped markup</title>
+        <programlisting language="xml"
+                        mped:tangle-to="apply-mped.xsl"
+            ><![CDATA[<?xml version="1.0"?>
+
+<xsl:stylesheet version="1.0"
+                xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
+                xmlns:mped="https://labo.planete-kraus.eu/mped.git"
+                xmlns:docbook="http://docbook.org/ns/docbook">
+        ]]>
+        <mped:copy linkend="insert-xml-co-comment" />
+        <mped:copy linkend="insert-default-co-comment" />
+        <mped:copy linkend="copy-everything-else" />
+        <![CDATA[
+</xsl:stylesheet>
+        ]]>
+        </programlisting>
+      </figure>
+      <para>
+        Starting from this file, <filename>mped.xml</filename>, and
+        the bootstrap tangling stylesheet,
+        <filename>tangle-bootstrap.xsl</filename>, you would obtain a
+        mped-less docbook file with:
+      </para>
+      <example>xsltproc tangle-bootstrap.xsl mped.xml | bash
+xsltproc apply-mped.xsl mped.xml | xmllint --format -</example>
+    </section>
+  </chapter>
 </book>
-- 
cgit v1.2.3