Same changes as in trunk

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

diff --git a/doc/postgis.xml b/doc/postgis.xml
index e628bcc5a350a0f2a343256aa0c24c1488e786de..e17360be966348990244a5dc6ee6d4109e79219c 100644 (file)
--- a/doc/postgis.xml
+++ b/doc/postgis.xml
@@ -3181,8 +3181,8 @@ VACUUM FULL ANALYZE mytable;</programlisting>
                          <para>It is usually used with MULTI and Geometry Collections.  Although it is not an aggregate - you can use it in conjunction with ST_Collect to get the convex hull of a set of points.  ST_ConvexHull(ST_Collect(somepointfield)).  It is often used to determine an affected area based on a set of point observations.
                          </para>
                          <programlisting>SELECT d.disease_type, ST_ConvexHull(ST_Collect(d.the_geom)) As the_geom 
-                                       FROM disease_obs As d 
-                                       GROUP BY d.disease_type</programlisting>
+       FROM disease_obs As d 
+       GROUP BY d.disease_type</programlisting>
                          
               <para>Performed by the GEOS module</para>
 
@@ -3218,8 +3218,8 @@ VACUUM FULL ANALYZE mytable;</programlisting>
             <term>ST_SymDifference(geometry A, geometry B)</term>
 
             <listitem>
-              <para>Returns a geometry that represents the point set symmetric
-              difference of Geometry A with Geometry B.</para>
+              <para>Returns a geometry that represents the portions of A and B that do not intersect.  It is 
+                         called a symmetric difference because ST_SymDifference(A,B) = ST_SymDifference(B,A).</para>
 
               <para>Performed by the GEOS module</para>
 
@@ -3233,8 +3233,8 @@ VACUUM FULL ANALYZE mytable;</programlisting>
             <term>ST_Difference(geometry A, geometry B)</term>
 
             <listitem>
-              <para>Returns a geometry that represents the point set
-              difference of Geometry A with Geometry B.</para>
+              <para>Returns a geometry that represents that part of geometry A that does not intersect
+                               with geometry B.</para>
 
               <para>Performed by the GEOS module</para>
 
@@ -4619,11 +4619,27 @@ dimension
               <para>This function returns a GEOMETRYCOLLECTION or a MULTI
               object from a set of geometries. The collect() function is an
               &quot;aggregate&quot; function in the terminology of PostgreSQL.
-              That means that it operators on lists of data, in the same way
+              That means that it operates on rows of data, in the same way
               the sum() and mean() functions do. For example, &quot;SELECT
               COLLECT(GEOM) FROM GEOMTABLE GROUP BY ATTRCOLUMN&quot; will
               return a separate GEOMETRYCOLLECTION for each distinct value of
               ATTRCOLUMN.</para>
+                         <para>ST_Collect and ST_Union are often interchangeable.  
+                         ST_Collect is in general orders of magnitude faster than ST_Union because it does not try to dissolve
+                         boundaries.  It merely rolls up single geometries into MULTI and MULTI or mixed geometry types into Geometry Collections.  
+                         Unfortunately geometry collections are not well-supported by 
+                         GIS tools.  To prevent ST_Collect from returning a Geometry Collection when collecting MULTI geometries, 
+                         one can use the below trick that utilizes ST_Dump to expand the MULTIs out to singles and then regroup them.
+                         </para>
+                         <programlisting>
+Thread ref: http://postgis.refractions.net/pipermail/postgis-users/2008-June/020331.html
+SELECT stusps, 
+          ST_Multi(ST_Collect(f.the_geom)) as singlegeom  
+        FROM (SELECT stusps, (ST_Dump(the_geom)).geom As the_geom 
+                               FROM
+                               somestatetable ) As f
+GROUP BY stusps
+                         </programlisting>
             </listitem>
           </varlistentry>
 
@@ -4649,6 +4665,15 @@ dimension
               input geometry is a collection or multi it will return a record
               for each of the collection components, and the path will express
               the position of the component inside the collection.</para>
+                         
+                         <para>ST_Dump is useful for expanding geometries.  It is the reverse of a GROUP BY in that
+                               it creates new rows. For example it can be use to expand MULTIPOLYGONS into POLYGONS.</para>
+                               
+                         <programlisting>
+SELECT sometable.*, (ST_Dump(the_geom)).geom As the_geom 
+        FROM somestatetable
+                         </programlisting>
+                               
 
               <para>Availability: PostGIS 1.0.0RC1. Requires PostgreSQL 7.3 or
               higher.</para>
@@ -6160,7 +6185,7 @@ z' = z </programlisting> This method is a subcase of
           </listitem>
           <listitem>
 
-            <para>Attach the patch to a new issue in bug tracker.</command></para>
+            <para>Attach the patch to a new issue in bug tracker.</para>
 
           </listitem>
         </orderedlist>