Remove ST_Area2D and replace with ST_Area - move to new section and provide example

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

diff --git a/doc/reference.xml b/doc/reference.xml
index 70350f400ff81a0840246aa1397b6e005a6aa835..0eaf061afa18393f4a40156abd8901aa09452d86 100644 (file)
--- a/doc/reference.xml
+++ b/doc/reference.xml
@@ -1254,17 +1254,7 @@ GROUP BY gid, field1,field2;
 
     <sect2>
       <title>Measurement Functions</title>
-
-      <variablelist>
-        <varlistentry>
-          <term>ST_area2d(geometry)</term>
-
-          <listitem>
-            <para>Returns the area of the geometry if it is a polygon or
-            multi-polygon.</para>
-          </listitem>
-        </varlistentry>
-
+         <variablelist>
         <varlistentry id="ST_Distance_Sphere">
           <term>ST_Distance_Sphere(point, point)</term>
 
@@ -2393,17 +2383,6 @@ WHERE n*100.00/length &lt; 1;
     </note>
 
     <variablelist>
-      <varlistentry>
-        <term>ST_Area</term>
-
-        <listitem>
-          <para>Return the area measurement of an ST_Surface or
-          ST_MultiSurface value.</para>
-
-          <para>SQL-MM 3: 8.1.2, 9.5.3</para>
-        </listitem>
-      </varlistentry>
-
       <varlistentry>
         <term>ST_AsBinary</term>
 

diff --git a/doc/reference_new.xml b/doc/reference_new.xml
index aeb8772b068baf3e09d34a26331e71afcd07fb1e..e2a2d9cffc72116416ce2773ff3e9892aaba3132 100644 (file)
--- a/doc/reference_new.xml
+++ b/doc/reference_new.xml
@@ -1106,7 +1106,71 @@ LINESTRING(1 2,1 10) | LINESTRING(1 10,1 2)
   
   
   <sect1>
-    <title>Spatial Relationships and Measurements</title>
+       <title>Spatial Relationships and Measurements</title>
+       <refentry id="ST_Area">
+               <refnamediv>
+                 <refname>ST_Area</refname>
+       
+                 <refpurpose>Returns the area of the geometry if it is a polygon or
+                               multi-polygon.</refpurpose>
+               </refnamediv>
+               <refsynopsisdiv>
+                 <funcsynopsis>
+                       <funcprototype>
+                         <funcdef>float <function>ST_Area</function></funcdef>
+                               <paramdef><type>geometry </type><parameter>g1</parameter></paramdef>
+                       </funcprototype>
+                 </funcsynopsis>
+               </refsynopsisdiv>
+               <refsection>
+                       <title>Description</title>
+                       
+                       <para>Returns the area of the geometry if it is a polygon or
+                               multi-polygon. Return the area measurement of an ST_Surface or
+          ST_MultiSurface value. Area is in the units of the spatial reference system.</para>
+               
+                       <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.</ulink></para>
+                       
+                       <para><inlinemediaobject>
+                               <imageobject>
+                                 <imagedata fileref="images/check.png" />
+                               </imageobject>
+                         </inlinemediaobject> This method implements the SQL/MM specification:
+                       SQL-MM 3: 8.1.2, 9.5.3</para>
+               </refsection>
+               
+                 <refsection>
+                       <title>Examples</title>
+                       <para>Return area in square feet for a plot of Massachusetts land. Note this is in square feet because 2249 is
+                               Mass State Plane Feet</para>
+                       <programlisting>
+SELECT ST_Area(ST_GeomFromText('POLYGON((743238 2967416,743238 2967450,
+       743265 2967450,743265.625 2967416,743238 2967416))',2249));
+st_area
+---------
+ 928.625
+(1 row)
+
+--this returns in square meters
+SELECT ST_Area(ST_Transform(ST_GeomFromText('POLYGON((743238 2967416,743238 2967450,
+       743265 2967450,743265.625 2967416,743238 2967416))',2249), 26986));
+st_area
+------------------
+ 86.2724306061864
+                       </programlisting>
+                 </refsection>
+               <refsection>
+                       <title>See Also</title>
+                       <para><xref linkend="ST_GeomFromText" />, <xref linkend="ST_SetSRID" />,<xref linkend="ST_Transform" /></para>
+               </refsection>
+
+       </refentry>
 
     
   <refentry id="ST_Crosses">