[SR-Dev] git:master: docbook: Fixed docbook dependency generator

[Jan Janak]

Module: sip-router
Branch: master
Commit: d5ceae609414dbbc81052abdc1f4b74066d84b98
URL:    http://git.sip-router.org/cgi-bin/gitweb.cgi/sip-router/?a=commit;h=d5ceae609414dbbc81052abdc1f4b74066d84b98

Author: Jan Janak <jan at iptel.org>
Committer: Jan Janak <jan at iptel.org>
Date:   Wed May 13 22:11:18 2009 +0200

docbook: Fixed docbook dependency generator

Previous version of the XSL stylesheet that is used to generate dependencies
for docbook documents did not work properly with docbook files included from
other directories, it did not make dependencies relative to the top-level
file being processed, resulting in dependency files that cannot be satisfied.

This change fixes the stylesheet and makes all the depedendencies generated
by the stylesheet relative to the directory of the top-level docbook document
being processed.

In addition to that it fixes a small typo in the main docbook Makefile.

---

 docbook/Makefile |    2 +-
 docbook/dep.xsl  |   92 +++++++++++++++++++++++++++++++++++++++++++++---------
 2 files changed, 78 insertions(+), 16 deletions(-)

diff --git a/docbook/Makefile b/docbook/Makefile
index b60ccf2..16691da 100644
--- a/docbook/Makefile
+++ b/docbook/Makefile
@@ -146,7 +146,7 @@ $(output_dir)/%.html: %.xml %.d $(single_html_xsl) $(all_deps)
         $(single_html_xsl) $<
 
 
-$(output_dir)/%.txt: %.xml %.d $(txt_xsl) $(all_dep)
+$(output_dir)/%.txt: %.xml %.d $(txt_xsl) $(all_deps)
 	XML_CATALOG_FILES=$(catalog) $(xsltproc) $(xsltproc_flags) \
 		--xinclude \
         $(txt_xsl) $< | $(lynx) $(lynx_flags) -stdin -dump > $@
diff --git a/docbook/dep.xsl b/docbook/dep.xsl
index e3c6133..0415f96 100644
--- a/docbook/dep.xsl
+++ b/docbook/dep.xsl
@@ -1,10 +1,10 @@
 <?xml version='1.0'?>
 <xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
 				version='1.0' xmlns:xi="http://www.w3.org/2001/XInclude">
-	
-	<xsl:param name="prefix"/>
 	<xsl:param name="output"/>
-	
+
+	<!-- Write the output into a plaintext file which will be later included
+		 into the Makefile -->
 	<xsl:template match="/">
 		<xsl:document href="{$output}" method="text" indent="no" 
 					  omit-xml-declaration="yes">
@@ -13,36 +13,98 @@
 		</xsl:document>
 	</xsl:template>
 	
-	<xsl:template name="get-prefix">
-		<xsl:if test="contains($prefix, '/')">
-			<xsl:value-of select="concat(substring-before($prefix, '/'), '/')"/>
-			<xsl:call-template name="get-prefix">
-				<xsl:with-param name="prefix" 
-								select="substring-after($prefix, '/')"/>
+	<!-- This template extract the name of the directory from a full pathname,
+	     in other words it returns everything but the name of the file -->
+	<xsl:template name="dirname">
+		<xsl:param name="filename"/>
+		<xsl:if test="contains($filename, '/')">
+			<xsl:value-of 
+				select="concat(substring-before($filename, '/'), '/')"/>
+			<xsl:call-template name="dirname">
+				<xsl:with-param name="filename" 
+								select="substring-after($filename, '/')"/>
 			</xsl:call-template>
 		</xsl:if>
 	</xsl:template>
+
+	<!-- This template is used to add a directory preefix to a filename. The
+	     prefix is only added if the filename is not absolute (i.e. it does
+	     not start with a / and if the prefix is not an empty string -->
+	<xsl:template name="addprefix">
+		<xsl:param name="prefix"/>
+		<xsl:param name="filename"/>
+		<xsl:if test="(string-length($prefix) > 0) and not(starts-with($filename, '/'))">
+			<xsl:value-of select="$prefix"/>
+		</xsl:if>
+		<xsl:value-of select="$filename"/>
+	</xsl:template>
 	
+	<!-- This template processes xi:include directives that include other XML
+	     documents. First the template outputs the name of the file being
+	     included and then the template traverses the included file
+	     recursively, searching fro other dependencies in that file.  The
+	     template passes the parameter prefix to other templates with its
+	     value set to the directory name of the file being included. This
+	     ensures that paths to all dependencies are relative to the main
+	     file. -->
 	<xsl:template match='xi:include' mode="subroot">
-		<xsl:value-of select="concat($prefix, concat(@href, ' '))"/>
+		<xsl:param name="prefix"/>
+
+		<!-- Add the prefix to the name of the file being included and store
+		     the result in variable fullpath -->
+		<xsl:variable name="fullpath">
+			<xsl:call-template name="addprefix">
+				<xsl:with-param name="prefix" select="$prefix"/>
+				<xsl:with-param name="filename" select="@href"/>
+			</xsl:call-template>
+		</xsl:variable>
+
+		<!-- First of all, output the name of the file being included, with
+		     proper prefix so that the resulting dependency is relative to the
+		     top-most file being processed, not the file we are are processing
+		     in this step. -->
+		<xsl:value-of select="concat($fullpath, ' ')"/>
+
+		<!-- Traverse the file being included and search for more depencencies
+		     in that file and other files included from there. -->
 		<xsl:apply-templates select="document(@href)" mode="subroot">
+			<!-- Extract the directory name from $fullpath and set it as a new
+			     value of the prefix parameter before calling other templates.
+			-->
 			<xsl:with-param name="prefix">
-				<xsl:call-template name="get-prefix">
-					<xsl:with-param name="prefix" 
-									select="concat($prefix, @href)"/>
+				<xsl:call-template name="dirname">
+					<xsl:with-param name="filename" select="$fullpath"/>
 				</xsl:call-template>
 			</xsl:with-param>
+
+			<!-- Process the included file recursively -->
 		</xsl:apply-templates>
 	</xsl:template>
 	
+	<!-- This template processes files included with xi:include that are not
+	     XML files, such files will only be output as dependencies and will be
+	     not traversed recursively. -->
 	<xsl:template match='xi:include[@parse="text"]' mode="subroot">
-		<xsl:value-of select="concat($prefix, concat(@href, ' '))"/>
+		<xsl:param name="prefix"/>
+		<xsl:call-template name="addprefix">
+			<xsl:with-param name="prefix" select="$prefix"/>
+			<xsl:with-param name="filename" select="@href"/>
+		</xsl:call-template>
+		<xsl:text> </xsl:text>
 	</xsl:template>
 	
+	<!-- This template processes mediaobjects (such as images) included in
+	     docbook. -->
 	<xsl:template match="graphic|imagedata|inlinemediaobject|textdata" 
 				  mode="subroot">
-		<xsl:value-of select="concat($prefix, concat(@fileref, ' '))"/>
+		<xsl:param name="prefix"/>
+		<xsl:call-template name="addprefix">
+			<xsl:with-param name="prefix" select="$prefix"/>
+			<xsl:with-param name="filename" select="@fileref"/>
+		</xsl:call-template>
+		<xsl:text> </xsl:text>
 	</xsl:template>
 	
+	<!-- Supress all other output -->
 	<xsl:template match="text()|@*" mode="subroot"/>
 </xsl:stylesheet>