fill out casting behavior, also list box type functions and links to it and from it

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

diff --git a/doc/reference_type.xml b/doc/reference_type.xml
index 920d4ceb3b805b5f5db6349544acb41e3eeb903d..5c19dded8354670c403a5e96674800f75ce2d365 100644 (file)
--- a/doc/reference_type.xml
+++ b/doc/reference_type.xml
@@ -1,7 +1,18 @@
 <?xml version="1.0" encoding="UTF-8"?>
   <sect1 id="PostGIS_Types">
     <title>PostgreSQL PostGIS Types</title>
-
+    <para>This section lists the PostgreSQL data types installed by PostGIS.  Note we describe the casting behavior of these which is very 
+       important especially when designing your own functions.  
+    </para>
+    <para>A Cast is when one type is coerced into another type.  PostgreSQL
+       is unique from most databases in that it allows you to define casting behavior for custom types and the functions used for casting.
+       A cast can be specified as automatic in which case, you do not have to do a CAST(myfoo As otherfootype) or myfoo::otherfootype
+       if you are feeding it to a function that only works with otherfootype and there is an automatic cast in place for it. 
+    </para>
+    <para>The danger of relying on automatic cast behavior is when you have an overloaded function say one that takes a box2d and one that takes a box3d
+       but no geometry.  What happens is that both functions are equally good to use with geometry since geometry has an autocast for both 
+       -- so you end up with an ambiguous function error. To force PostgreSQL to choose, you do a CAST(mygeom As box3d)  or mygeom::box3d.</para>
+    
        <refentry id="box2d">
       <refnamediv>
         <refname>box2d</refname>
@@ -23,6 +34,33 @@
         <title>Description</title>
         <para>box3d is a postgis spatial data type used to represent the enclosing box of a geometry or set of geometries. ST_Extent3D returns a box3d object.</para>
       </refsection>
+      
+      <refsection>
+               <title>Casting Behavor</title>
+               <para>This section lists the automatic as well as explicit casts allowed for this data type</para>
+               <informaltable rowsep="1" frame="all">
+               <tgroup cols="2">
+                       <tbody>
+                         <row>
+                               <entry>Cast To</entry>
+                               <entry>Behavior</entry>
+                         </row>
+                         <row>
+                               <entry>box</entry>
+                               <entry>automatic</entry>
+                         </row>
+                         <row>
+                               <entry>box2d</entry>
+                               <entry>automatic</entry>
+                         </row>
+                         <row>
+                               <entry>geometry</entry>
+                               <entry>automatic</entry>
+                         </row>
+                       </tbody>
+               </tgroup>
+               </informaltable>
+               </refsection>
     </refentry>
        
        <refentry id="box3d_extent">
@@ -35,32 +73,38 @@
         <title>Description</title>
         <para>box3d_extent is a data type returned by ST_Extent. In versions prior to PostGIS 1.4, ST_Extent would return a box2d.</para>
       </refsection>
+      
          <refsection>
-               <title>Casting Behavor</title>
+               <title>Casting Behavor</title>
                <para>This section lists the automatic as well as explicit casts allowed for this data type</para>
                <informaltable rowsep="1" frame="all">
-                       <tgroup cols="2">
-                               <tbody>
-                                 <row>
-                                       <entry>Cast To</entry>
-                                       <entry>Behavior</entry>
-                                 </row>
-                                 <row>
-                                       <entry>box2d</entry>
-                                       <entry>automatic</entry>
-                                 </row>
-                                 <row>
-                                       <entry>box3d</entry>
-                                       <entry>automatic</entry>
-                                 </row>
-                                 <row>
-                                       <entry>geometry</entry>
-                                       <entry>automatic</entry>
-                                 </row>
-                               </tbody>
-                       </tgroup>
+               <tgroup cols="2">
+                       <tbody>
+                         <row>
+                               <entry>Cast To</entry>
+                               <entry>Behavior</entry>
+                         </row>
+                         <row>
+                               <entry>box2d</entry>
+                               <entry>automatic</entry>
+                         </row>
+                         <row>
+                               <entry>box3d</entry>
+                               <entry>automatic</entry>
+                         </row>
+                         <row>
+                               <entry>geometry</entry>
+                               <entry>automatic</entry>
+                         </row>
+                       </tbody>
+               </tgroup>
                </informaltable>
-         </refsection>
+               </refsection>
+               
+               <refsection>
+                       <title>See Also</title>
+                       <para><xref linkend="PostGIS_BoxFunctions" /> </para>
+               </refsection>
     </refentry>
        
        <refentry id="geometry">
@@ -74,6 +118,45 @@
                        <para>geometry is a fundamental postgis spatial data type used to represent a feature in the Euclidean coordinate system.</para>
                </refsection>
                
+               <refsection>
+               <title>Casting Behavor</title>
+               <para>This section lists the automatic as well as explicit casts allowed for this data type</para>
+               <informaltable rowsep="1" frame="all">
+               <tgroup cols="2">
+                       <tbody>
+                         <row>
+                               <entry>Cast To</entry>
+                               <entry>Behavior</entry>
+                         </row>
+                         <row>
+                               <entry>box</entry>
+                               <entry>automatic</entry>
+                         </row>
+                         <row>
+                               <entry>box2d</entry>
+                               <entry>automatic</entry>
+                         </row>
+                         <row>
+                               <entry>box3d</entry>
+                               <entry>automatic</entry>
+                         </row>
+                         <row>
+                               <entry>bytea</entry>
+                               <entry>automatic</entry>
+                         </row>
+                         <row>
+                               <entry>geography</entry>
+                               <entry>automatic</entry>
+                         </row>
+                         <row>
+                               <entry>text</entry>
+                               <entry>automatic</entry>
+                         </row>
+                       </tbody>
+               </tgroup>
+               </informaltable>
+               </refsection>
+               
                <refsection>
                        <title>See Also</title>
                        <para><xref linkend="RefObject" /></para>
@@ -108,7 +191,26 @@
                
                <refsection>
                <title>Description</title>
-               <para>GEOGRAPHY is a spatial data type used to represent a feature in the round-earth coordinate system.</para>
+               <para>geography is a spatial data type used to represent a feature in the round-earth coordinate system.</para>
+               </refsection>
+               
+               <refsection>
+               <title>Casting Behavor</title>
+               <para>This section lists the automatic as well as explicit casts allowed for this data type</para>
+               <informaltable rowsep="1" frame="all">
+               <tgroup cols="2">
+                       <tbody>
+                         <row>
+                               <entry>Cast To</entry>
+                               <entry>Behavior</entry>
+                         </row>
+                         <row>
+                               <entry>geometry</entry>
+                               <entry>explicit</entry>
+                         </row>
+                       </tbody>
+               </tgroup>
+               </informaltable>
                </refsection>
                
                <refsection>

diff --git a/doc/xsl/postgis_aggs_mm.xml.xsl b/doc/xsl/postgis_aggs_mm.xml.xsl
index 8a9e8de02e65e9b8fe9729c1c8afcc299e263bc2..902d8b54b56366251f415d8cab0625c1304c0a5e 100644 (file)
--- a/doc/xsl/postgis_aggs_mm.xml.xsl
+++ b/doc/xsl/postgis_aggs_mm.xml.xsl
@@ -131,6 +131,34 @@
                                </xsl:for-each>\r
                                </itemizedlist>\r
                </sect1>\r
+               \r
+               <sect1 id="PostGIS_BoxFunctions">\r
+                       <title>PostGIS Box Functions</title>\r
+                       <para>The functions given below are PostGIS functions that take as input or return as output the box* family of PostGIS spatial types.\r
+                               The box family of types consists of <link linkend="box2d">box2d</link>, <link linkend="box3d">box3d</link>, <link linkend="box3d_extent">box3d_extent</link> </para>\r
+                               <itemizedlist>\r
+                       <!-- Pull out the purpose section for each ref entry and strip whitespace and put in a variable to be tagged unto each function comment  -->\r
+                               <xsl:for-each select='sect1/refentry'>\r
+                                       <xsl:sort select="@id"/>\r
+                                       <xsl:variable name='comment'>\r
+                                               <xsl:value-of select="normalize-space(translate(translate(refnamediv/refpurpose,'&#x0d;&#x0a;', ' '), '&#09;', ' '))"/>\r
+                                       </xsl:variable>\r
+                                       <xsl:variable name="refid">\r
+                                               <xsl:value-of select="@id" />\r
+                                       </xsl:variable>\r
+                                       <xsl:variable name="refname">\r
+                                               <xsl:value-of select="refnamediv/refname" />\r
+                                       </xsl:variable>\r
+\r
+                       <!-- If at least one proto function accepts or returns a geography -->\r
+                                       <xsl:choose>\r
+                                               <xsl:when test="contains(refsynopsisdiv/funcsynopsis,'box') or contains(refsynopsisdiv/funcsynopsis/funcprototype/funcdef,'box')">\r
+                                                       <listitem><link linkend="{$refid}"><xsl:value-of select="$refname" /></link> - <xsl:value-of select="$comment" /></listitem>\r
+                                               </xsl:when>\r
+                                       </xsl:choose>\r
+                               </xsl:for-each>\r
+                               </itemizedlist>\r
+               </sect1>\r
 \r
                <sect1 id="PostGIS_3D_Functions">\r
                        <title>PostGIS Functions that support 3D</title>\r