Put IDs to figures containing the listing, not the listing itself.

If both the figure and the program listing had an ID, this would make
cross-referencing a nightmare. Since it seems like it’s usually better
to put an ID on figures, I will consider the listings directly within
a figure with a given ID to have this ID.

2 files changed, 89 insertions, 47 deletions

diff --git a/mped.xml b/mped.xml
index 04dd33d..8739fcf 100644
--- a/mped.xml
+++ b/mped.xml
@@ -128,13 +128,16 @@
         attribute.
       </para>
       <para>
-        To tangle a document, an XSLT stylesheet is defined. It reads a
-        Docbook document, and outputs a shell script that writes the
+        To tangle a document, an XSLT stylesheet is defined. It reads
+        a Docbook document, and outputs a shell script that writes the
         correct pieces of code to the correct file names. The key
-        template to do the task is:
+        template to do the task is <xref
+        linkend="tangle-programlisting" />.
       </para>
-      <programlisting language="xml" xml:id="tangle-programlisting">
-        <![CDATA[
+      <figure xml:id="tangle-programlisting">
+        <title>Copy a specific programlisting to disk</title>
+        <programlisting language="xml">
+          <![CDATA[
 <xsl:template match="docbook:programlisting[@mped:tangle-to]">
   <xsl:text>mkdir -p $(dirname "</xsl:text>
   <xsl:value-of select="@mped:tangle-to" />
@@ -149,8 +152,9 @@
 
   <xsl:text>&#xA;_MPED_EOF&#xA;</xsl:text>
 </xsl:template>
-        ]]>
-      </programlisting>
+          ]]>
+        </programlisting>
+      </figure>
       <para>
         This template starts by creating the directory where the file
         should go, then fills the file with the source code. XML has a
@@ -160,50 +164,73 @@
         correctly, and has too many empty lines. To counter this
         effect, we use a code source <emphasis>formatter</emphasis>, a
         program that reads source code and indents it correctly. For
-        XSLT, we can use <command>xmllint</command> from
+        XSLT, in <xref linkend="formatter-for-xml" />, we can use
+        <command>xmllint</command> from
         <application>libxml2</application>. The important thing about
         the formatter is that it should take its input from standard
         input and write the formatted code to standard output.
       </para>
-      <programlisting language="xml" xml:id="formatter-for-xml">
-        <![CDATA[
+      <figure xml:id="formatter-for-xml">
+        <title>Use xmllint as a formatter for XML languages</title>
+        <programlisting language="xml">
+          <![CDATA[
 <xsl:template match="docbook:programlisting[@language = 'xml']" 
               mode="source-code-formatter">
   <xsl:text>xmllint --format -</xsl:text>
 </xsl:template>
-        ]]>
-      </programlisting>
+          ]]>
+        </programlisting>
+      </figure>
+      <note>
+        Unfortunately, xmllint does not accept an XML processing
+        instruction after the first line, so you will still need to
+        put no whitespace between the start tag of programlisting and
+        the text for XML listings.
+      </note>
       <para>
         If no formatter applies, then we can resort to
-        <command>cat</command>.
+        <command>cat</command>, see <xref linkend="default-formatter"
+        />.
       </para>
-      <programlisting language="xml" xml:id="default-formatter">
-        <![CDATA[
+      <figure xml:id="default-formatter">
+        <title>Use cat as the default formatter for any language</title>
+        <programlisting language="xml">
+          <![CDATA[
 <xsl:template match="docbook:programlisting"
               mode="source-code-formatter">
   <xsl:text>cat</xsl:text>
 </xsl:template>
-        ]]>
-      </programlisting>
+          ]]>
+        </programlisting>
+      </figure>
       <para>
-        We also need to specify how the source code is copied.
+        We also need to specify how the source code is copied. It is
+        very simple: <xref linkend="copy-source-code-text" /> copies
+        the text verbatim.
       </para>
-      <programlisting language="xml" xml:id="copy-source-code-text">
-        <![CDATA[
+      <figure xml:id="copy-source-code-text">
+        <title>Copy the source code as text</title>
+        <programlisting language="xml">
+          <![CDATA[
 <xsl:template match="text()" mode="copy-source-code">
   <xsl:value-of select="." />
 </xsl:template>
-        ]]>
-      </programlisting>
+          ]]>
+        </programlisting>
+      </figure>
       <para>
         Tangling should never touch anything else. So, text should not
-        be copied to output.
+        be copied to output. This is why we disable text matching by
+        default with <xref linkend="ignore-text-other-than-source" />.
       </para>
-      <programlisting language="xml" xml:id="ignore-text-other-than-source">
-        <![CDATA[
+      <figure xml:id="ignore-text-other-than-source">
+        <title>Ignore text by default when tangling</title>
+        <programlisting language="xml">
+          <![CDATA[
                  <xsl:template match="text()" />
-        ]]>
-      </programlisting>
+          ]]>
+        </programlisting>
+      </figure>
     </section>
     <section>
       <title>Paste other listings in place</title>
@@ -214,44 +241,58 @@
         “mped:copy”. It has a “linkend” attribute that resolves to a
         program listing anywhere in the document. When copying source
         code, matching this element will insert the linked listing
-        directly here.
+        directly here. This is done in <xref
+        linkend="tangle-mped-copy" />.
       </para>
-      <programlisting language="xml" xml:id="tangle-mped-copy">
-        <![CDATA[
+      <para>
+        More precisely, it looks if there is a single program listing
+        that is directly under a figure with the given ID. This way,
+        we can refer to listings as the figure they appear in, which
+        makes cross-referencing easier.
+      </para>
+      <figure xml:id="tangle-mped-copy">
+        <title>
+          Insert literally a listing in another when tangling
+        </title>
+        <programlisting language="xml">
+          <![CDATA[
 <xsl:template match="mped:copy" mode="copy-source-code">
   <xsl:variable name="ref" select="@linkend" />
   <xsl:variable name="candidates"
-                select="count(//docbook:programlisting[@xml:id = $ref])" />
+                select="count(//docbook:figure[@xml:id = $ref]/docbook:programlisting)" />
   <xsl:if test="$candidates = 0">
     <xsl:message terminate="yes">
-      <xsl:text>There are no listing with ID '</xsl:text>
+      <xsl:text>There are no listing directly within a figure with ID '</xsl:text>
       <xsl:value-of select="$ref" />
       <xsl:text>'.&#xA;</xsl:text>
     </xsl:message>
   </xsl:if>
   <xsl:if test="$candidates > 1">
     <xsl:message terminate="yes">
-      <xsl:text>There are multiple listings with ID '</xsl:text>
+      <xsl:text>There are multiple listings directly within a figure with ID '</xsl:text>
       <xsl:value-of select="$ref" />
       <xsl:text>'.&#xA;</xsl:text>
     </xsl:message>
   </xsl:if>
-  <xsl:apply-templates select="//docbook:programlisting[@xml:id = $ref]"
+  <xsl:apply-templates select="//docbook:figure[@xml:id = $ref]/docbook:programlisting"
                        mode="copy-source" />
 </xsl:template>
-        ]]>
-      </programlisting>
+          ]]>
+        </programlisting>
+      </figure>
     </section>
     <section>
       <title>Putting it all together</title>
       <para>
-        The collection of all these templates gives the following:
+        The collection of all these templates gives a full stylesheet,
+        in <xref linkend="whole-tangling-stylesheet" />.
       </para>
-      <programlisting
-          language="xml"
-          xml:id="whole-tangling-stylesheet"
-          mped:tangle-to="tangle.xsl"
-          ><![CDATA[<?xml version="1.0"?>
+      <figure xml:id="whole-tangling-stylesheet">
+        <title>The full stylesheet for tangling</title>
+        <programlisting
+            language="xml"
+            mped:tangle-to="tangle.xsl"
+            ><![CDATA[<?xml version="1.0"?>
 
 <xsl:stylesheet version="1.0"
                 xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
@@ -270,7 +311,8 @@
         <![CDATA[
 </xsl:stylesheet>
         ]]>
-      </programlisting>
+        </programlisting>
+      </figure>
     </section>
   </chapter>
 </book>
diff --git a/tangle-bootstrap.xsl b/tangle-bootstrap.xsl
index baa9669..a646bca 100644
--- a/tangle-bootstrap.xsl
+++ b/tangle-bootstrap.xsl
@@ -29,10 +29,10 @@ _MPED_EOF
   <xsl:template match="text()"/>
   <xsl:template match="mped:copy" mode="copy-source-code">
     <xsl:variable name="ref" select="@linkend"/>
-    <xsl:variable name="candidates" select="count(//docbook:programlisting[@xml:id = $ref])"/>
+    <xsl:variable name="candidates" select="count(//docbook:figure[@xml:id = $ref]/docbook:programlisting)"/>
     <xsl:if test="$candidates = 0">
       <xsl:message terminate="yes">
-        <xsl:text>There are no listing with ID '</xsl:text>
+        <xsl:text>There are no listing directly within a figure with ID '</xsl:text>
         <xsl:value-of select="$ref"/>
         <xsl:text>'.
 </xsl:text>
@@ -40,12 +40,12 @@ _MPED_EOF
     </xsl:if>
     <xsl:if test="$candidates &gt; 1">
       <xsl:message terminate="yes">
-        <xsl:text>There are multiple listings with ID '</xsl:text>
+        <xsl:text>There are multiple listings directly within a figure with ID '</xsl:text>
         <xsl:value-of select="$ref"/>
         <xsl:text>'.
 </xsl:text>
       </xsl:message>
     </xsl:if>
-    <xsl:apply-templates select="//docbook:programlisting[@xml:id = $ref]" mode="copy-source"/>
+    <xsl:apply-templates select="//docbook:figure[@xml:id = $ref]/docbook:programlisting" mode="copy-source"/>
   </xsl:template>
 </xsl:stylesheet>