Moved over ST_Touches to new PostGIS reference. Examples forthcoming.

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

diff --git a/doc/reference.xml b/doc/reference.xml
index 5ff0127596169a49a5216b91126542f8d96b72ec..e8231c39861bb65f4a40d671fc4280ec425a495c 100644 (file)
--- a/doc/reference.xml
+++ b/doc/reference.xml
@@ -23,29 +23,6 @@
       <title>Geometry Relationship Functions</title>
 
       <variablelist>
-        <varlistentry>
-          <term>ST_Touches(A geometry, B geometry)</term>
-
-          <listitem>
-            <para>Returns TRUE if the Geometries "spatially touch".</para>
-
-            <para>Performed by the GEOS module</para>
-
-            <para>Do not call with a GeometryCollection as an argument</para>
-
-            <para>This function call will automatically include a bounding box
-            comparison that will make use of any indexes that are available on
-            the geometries. To avoid index use, use the function
-            _ST_Touches.</para>
-
-            <para>NOTE: this is the "allowable" version that returns a
-            boolean, not an integer.</para>
-
-            <para>OGC SPEC s2.1.1.2 // s2.1.13.3- a.Touches(b) -&gt; (I(a)
-            intersection I(b) = {empty set} ) and (a intersection b) not
-            empty</para>
-          </listitem>
-        </varlistentry>
 
         <varlistentry>
           <term>ST_Overlaps(A geometry, B geometry)</term>
@@ -2518,18 +2495,7 @@ WHERE n*100.00/length &lt; 1;
 
           <para>SQL-MM 3: 5.1.21</para>
         </listitem>
-      </varlistentry>
-
-      <varlistentry>
-        <term>ST_Touches</term>
-
-        <listitem>
-          <para>Test if an ST_Geometry value spatially touches another
-          ST_Geometry value.</para>
-
-          <para>SQL-MM 3: 5.1.28</para>
-        </listitem>
-      </varlistentry>   
+      </varlistentry> 
 
       <varlistentry>
         <term>ST_WKBToSQL</term>

diff --git a/doc/reference_new.xml b/doc/reference_new.xml
index d216d6ac60ab5aab891225b495ebd05830498082..e26a3664ab74db66048115c92c27d33ddf0d31c9 100644 (file)
--- a/doc/reference_new.xml
+++ b/doc/reference_new.xml
@@ -2594,7 +2594,7 @@ st_area
       geometries must not equal either of the source geometries. Otherwise, it
       returns <varname>FALSE</varname>.</para>
 
-      <para>In mathematical terms, this is expressed as :</para>
+      <para>In mathematical terms, this is expressed as:</para>
 
       <para>
         <equation>a.Crosses(b) &hArr; (dim(I(a) &cap; I(b)) &lt; max(dim(I(a)),dim(I(b))) 
@@ -2628,7 +2628,7 @@ st_area
         Area/Line situations as well. This makes the relation
         symmetric.</para>
 
-    <important>
+      <important>
         <para>Do not call with a <varname>GEOMETRYCOLLECTION</varname> as an argument</para>
       </important>
     </refsection>
@@ -2772,9 +2772,11 @@ WHERE ST_Crosses(roads.the_geom, highways.the_geom);</programlisting>
                        <para>Overlaps, Touches, Within all imply geometries are not spatially disjoint.  If any of the aforementioned
                                returns true, then the geometries are not spatially disjoint.  
                                Disjoint implies false for spatial intersection.</para>
-                       <para><inlinegraphic class="sfs_compliant" fileref="images/warning.png" />
-                               Do not call with a GeometryCollection as an argument
-                       </para>
+                               
+      <important>
+        <para>Do not call with a <varname>GEOMETRYCOLLECTION</varname> as an argument</para>
+      </important>
+      
                        <para>Performed by the GEOS module</para>
                        <note>
                          <para>This function call does not use indexes</para>
@@ -3049,9 +3051,11 @@ SELECT ST_Equals(ST_Reverse(ST_GeomFromText('LINESTRING(0 0, 10 10)')),
                        <para>Overlaps, Touches, Within all imply spatial intersection.  If any of the aforementioned
                                returns true, then the geometries also spatially intersect.  
                                Disjoint implies false for spatial intersection.</para>
-                       <para><inlinegraphic class="sfs_compliant" fileref="images/warning.png" />
-                               Do not call with a GeometryCollection as an argument
-                       </para>
+
+      <important>
+        <para>Do not call with a <varname>GEOMETRYCOLLECTION</varname> as an argument</para>
+      </important>
+      
                        <para>Performed by the GEOS module</para>
                        <note>
                          <para>This function call will automatically include a bounding box
@@ -3366,6 +3370,93 @@ SELECT ST_AsText(ST_PointOnSurface('POLYGON((0 0, 0 5, 5 5, 5 0, 0 0))'::geometr
       </refsection>
     </refentry>
        
+    <refentry id="ST_Touches">
+      <refnamediv>
+        <refname>ST_Touches</refname>
+
+        <refpurpose>Returns <varname>TRUE</varname> if the geometries have at least one point in common, 
+        but their interiors do not intersect.</refpurpose>
+      </refnamediv>
+
+      <refsynopsisdiv>
+        <funcsynopsis>
+          <funcprototype>
+            <funcdef>boolean <function>ST_Touches</function></funcdef>
+
+            <paramdef><type>geometry </type>
+            <parameter>g1</parameter></paramdef>
+
+            <paramdef><type>geometry </type>
+            <parameter>g2</parameter></paramdef>
+          </funcprototype>
+        </funcsynopsis>
+      </refsynopsisdiv>
+
+      <refsection>
+        <title>Description</title>
+
+        <para>Returns <varname>TRUE</varname> if the only points in common between 
+        <parameter>g1</parameter> and <parameter>g2</parameter> lie in the union of the 
+        boundaries of <parameter>g1</parameter> and <parameter>g2</parameter>.
+        The <function>ST_Touches</function> relation applies 
+        to all Area/Area, Line/Line, Line/Area, Point/Area and Point/Line pairs of relationships, 
+        but <emphasis>not</emphasis> to the Point/Point pair.</para>
+
+        <para>In mathematical terms, this predicate is expressed as:</para>
+        
+        <para>
+          <equation>a.Touches(b) &hArr; (I(a) &cap; I(b) = &empty;) &and; (a &cup; b &ne; &empty;)</equation>
+        </para>
+        
+        <para>The allowable DE-9IM Intersection Matrices for the two geometries are:</para>
+        
+        <itemizedlist>
+          <listitem>
+            <para><markup>FT*******</markup></para>
+          </listitem>
+        
+          <listitem>
+            <para><markup>F**T*****</markup></para>
+          </listitem>
+        
+          <listitem>
+            <para><markup>F***T****</markup></para>
+          </listitem>
+        </itemizedlist>
+        
+        <important>
+          <para>Do not call with a <varname>GEOMETRYCOLLECTION</varname> as an argument</para>
+        </important>
+        
+        <note>
+          <para>This function call will automatically include a bounding box
+          comparison that will make use of any indexes that are available on
+          the geometries.  To avoid using an index, use <function>_ST_Touches</function> instead.</para>
+        </note>
+      
+        <para><inlinemediaobject>
+            <imageobject>
+              <imagedata fileref="images/check.png" />
+            </imageobject>
+          </inlinemediaobject> This method implements the <ulink
+        url="http://www.opengeospatial.org/standards/sfs">OpenGIS Simple
+        Features Implementation Specification for SQL: 2.1.1.2, 2.1.13.3</ulink></para>
+
+        <para><inlinemediaobject>
+            <imageobject>
+              <imagedata fileref="images/check.png" />
+            </imageobject>
+          </inlinemediaobject> This method implements the SQL/MM
+        specification: SQL-MM 3: 5.1.28</para>
+      </refsection>
+
+      <refsection>
+        <title>Examples</title>
+
+        <programlisting>Forthcoming...</programlisting>
+      </refsection>
+    </refentry>
+    
     <refentry id="ST_Within">
       <refnamediv>
         <refname>ST_Within</refname>
@@ -3397,7 +3488,9 @@ SELECT ST_AsText(ST_PointOnSurface('POLYGON((0 0, 0 5, 5 5, 5 0, 0 0))'::geometr
        
         <para>Performed by the GEOS module</para>
 
-        <note><para>Do not call with a GeometryCollection as an argument</para></note>
+        <important>
+          <para>Do not call with a <varname>GEOMETRYCOLLECTION</varname> as an argument</para>
+        </important>
 
         <para>This function call will automatically include a bounding box
             comparison that will make use of any indexes that are available on