diff options
author | Vivien Kraus <vivien@planete-kraus.eu> | 2022-10-06 23:16:54 +0200 |
---|---|---|
committer | Vivien Kraus <vivien@planete-kraus.eu> | 2022-10-07 00:07:32 +0200 |
commit | 91b5abcaed850639cde8808076cf76719b9cc669 (patch) | |
tree | 04f0204c22ce56cff32b9901dc138594b0e2d40e | |
parent | 3a15eb52334be6ddee374e044e70d3a0a8e6426a (diff) |
Add a new chapter to beautify listing inclusion in book.
-rw-r--r-- | mped.xml | 107 |
1 files changed, 104 insertions, 3 deletions
@@ -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 <mped:copy> 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 <mped:copy> 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><!-- </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> |