Revert "remove ~= from documentation -- we don't want people using this operator"

This reverts r8799

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

diff --git a/doc/reference_operator.xml b/doc/reference_operator.xml
index 3031d3e036bc3a63daf87d321437b0183ad38ce0..cc6da36a52d2ad07146cdf1c7cb7ca0f58979a01 100644 (file)
--- a/doc/reference_operator.xml
+++ b/doc/reference_operator.xml
@@ -991,6 +991,78 @@ FROM
                        <para><xref linkend="ST_Geometry_Contained" />, <xref linkend="geometry_overlaps" /></para>
                  </refsection>
                </refentry>
+
+               <refentry id="ST_Geometry_Same">
+                 <refnamediv>
+                       <refname>~=</refname>
+
+                       <refpurpose>Returns <varname>TRUE</varname> if A's bounding box is the same as B's.</refpurpose>
+                 </refnamediv>
+
+                 <refsynopsisdiv>
+                       <funcsynopsis>
+                         <funcprototype>
+                               <!-- TODO: Ideally, it would be nice if this could be reordered to
+                               "boolean (geometry A ~= geometry B)" instead of
+                               "boolean ~=( geometry A, geometry B)" -->
+                               <funcdef>boolean <function>~=</function></funcdef>
+
+                               <paramdef>
+                                 <type>geometry </type>
+
+                                 <parameter>A</parameter>
+                               </paramdef>
+
+                               <paramdef>
+                                 <type>geometry </type>
+
+                                 <parameter>B</parameter>
+                               </paramdef>
+                         </funcprototype>
+                       </funcsynopsis>
+                 </refsynopsisdiv>
+
+                 <refsection>
+                       <title>Description</title>
+
+                       <para>The <varname>~=</varname> operator returns <varname>TRUE</varname> if the bounding box of geometry/geography A
+                       is the same as the bounding box of geometry/geography B.</para>
+
+                       <note><para>This operand will make use of any indexes that may be available on the
+                         geometries.</para></note>
+
+                        <para>Availability: 1.5.0 changed behavior</para>
+                        <para>&P_support;</para>
+
+                       <warning>
+                         <para>This operator has changed behavior in PostGIS 1.5
+                         from testing for actual geometric equality to only 
+                         checking for bounding box equality. To complicate things 
+                         it also depends on if you have done a hard or soft upgrade 
+                         which behavior your database has. To find out which behavior
+                         your database has you can run the query below.
+                               To check for true equality use <xref linkend="ST_OrderingEquals" /> or <xref
+                         linkend="ST_Equals" /> and to check for bounding box equality <xref linkend="ST_Geometry_EQ" />; 
+                         operator is a safer option.</para>
+                         </warning>
+                 </refsection>
+
+                 <refsection>
+                       <title>Examples</title>
+<programlisting>
+
+select 'LINESTRING(0 0, 1 1)'::geometry ~= 'LINESTRING(0 1, 1 0)'::geometry as equality;
+ equality   |
+-----------------+
+          t    |
+                       </programlisting>
+                       <para>The above can be used to test if you have the new or old behavior of ~= operator.</para>
+                 </refsection>
+                 <refsection>
+                       <title>See Also</title>
+                       <para><xref linkend="ST_Equals" />, <xref linkend="ST_OrderingEquals" />, <xref linkend="ST_Geometry_EQ" /></para>
+                 </refsection>
+               </refentry>
                
                <refentry id="geometry_distance_centroid">
                  <refnamediv>