diff options
| -rw-r--r-- | mped.xml | 128 | ||||
| -rw-r--r-- | tangle-bootstrap.xsl | 8 |
2 files changed, 89 insertions, 47 deletions
@@ -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>
_MPED_EOF
</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>'.
</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>'.
</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 > 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> |