From: Regina Obe <lr@pcorp.us>
Date: Fri, 26 Sep 2008 12:45:38 +0000 (+0000)
Subject: Put in author/license info (hmm this is a guess - couldn't find a good example in... 
X-Git-Tag: 1.4.0b1~698
X-Git-Url: https://granicus.if.org/sourcecode?a=commitdiff_plain;h=e4d04f472a5c7c8e0598ea4e622b022080187fc0;p=postgis

Put in author/license info (hmm this is a guess - couldn't find a good example in SVN to go by).  Also comment on what xsl is doing.

git-svn-id: http://svn.osgeo.org/postgis/trunk@3014 b70326c6-7e19-0410-871a-916f4a2858ee
---

diff --git a/doc/xsl/postgis_comments.sql.xsl b/doc/xsl/postgis_comments.sql.xsl
index b7a138a25..3f4b12006 100644
--- a/doc/xsl/postgis_comments.sql.xsl
+++ b/doc/xsl/postgis_comments.sql.xsl
@@ -1,21 +1,31 @@
 <?xml version="1.0" encoding="utf-8"?>
 <xsl:stylesheet version="1.0" xmlns:xsl="http://www.w3.org/1999/XSL/Transform">
+<!-- ********************************************************************
+     $Id: 0.2 postgis_comments.xsl 2008-09-26 $
+     ********************************************************************
+	 Copyright 2008, Regina Obe
+     License: BSD
+	 Purpose: This is an xsl transform that generates PostgreSQL COMMENT ON FUNCTION ddl
+	 statements from postgis xml doc reference
+     ******************************************************************** -->
 	<xsl:output method="text" />
 	<xsl:template match='/chapter'>
 		<xsl:variable name="ap"><xsl:text>'</xsl:text></xsl:variable>
+<!-- Pull out the purpose section for each ref entry and strip whitespace and put in a variable to be tagged unto each function comment  -->
 		<xsl:for-each select='sect1/refentry'>
 		  <xsl:variable name='plaincomment'>
-		  	<xsl:value-of select="refnamediv/refpurpose" />
+		  	<xsl:value-of select="normalize-space(translate(translate(refnamediv/refpurpose,'&#x0d;&#x0a;', ' '), '&#09;', ' '))"/>
 		  </xsl:variable>
-		  
-			<xsl:variable name='comment'>
-				<xsl:call-template name="globalReplace">
-					<xsl:with-param name="outputString" select="$plaincomment"/>
-					<xsl:with-param name="target" select="$ap"/>
-					<xsl:with-param name="replacement" select="''"/>
-				</xsl:call-template>
-			</xsl:variable>
-
+<!-- Replace apostrophes with 2 apostrophes needed for escaping in SQL -->
+		<xsl:variable name='comment'>
+			<xsl:call-template name="globalReplace">
+				<xsl:with-param name="outputString" select="$plaincomment"/>
+				<xsl:with-param name="target" select="$ap"/>
+				<xsl:with-param name="replacement" select="''"/>
+			</xsl:call-template>
+		</xsl:variable>
+<!-- For each function prototype generate the DDL comment statement
+	If its input is a geometry set - we know it is an aggregate function rather than a regular function -->
 		<xsl:for-each select="refsynopsisdiv/funcsynopsis/funcprototype">
 COMMENT ON <xsl:choose><xsl:when test="contains(paramdef/type,'geometry set')">AGGREGATE</xsl:when><xsl:otherwise>FUNCTION</xsl:otherwise></xsl:choose><xsl:text> </xsl:text> <xsl:value-of select="funcdef/function" />(<xsl:for-each select="paramdef"><xsl:choose><xsl:when test="count(parameter) &gt; 0"> 
 <xsl:choose><xsl:when test="contains(type,'geometry set')">geometry</xsl:when><xsl:otherwise><xsl:value-of select="type" /></xsl:otherwise></xsl:choose><xsl:if test="position()&lt;last()"><xsl:text>, </xsl:text></xsl:if></xsl:when>
@@ -24,6 +34,8 @@ COMMENT ON <xsl:choose><xsl:when test="contains(paramdef/type,'geometry set')">A
 		</xsl:for-each>
 	</xsl:template>
 	
+<!--General replace macro hack to make up for the fact xsl 1.0 does not have a built in one.  
+	Not needed for xsl 2.0 lifted from http://www.xml.com/pub/a/2002/06/05/transforming.html -->
 	<xsl:template name="globalReplace">
 	  <xsl:param name="outputString"/>
 	  <xsl:param name="target"/>
@@ -47,6 +59,7 @@ COMMENT ON <xsl:choose><xsl:when test="contains(paramdef/type,'geometry set')">A
 	  </xsl:choose>
 	</xsl:template>
 
+	<!--macro to pull out function parameter names so we can provide a pretty arg list prefix for each function -->
 	<xsl:template name="listparams">
 		<xsl:param name="func" />
 		<xsl:for-each select="$func">