From 173901a900515dc1bbe75ffab6b348e74f897df7 Mon Sep 17 00:00:00 2001
From: Regina Obe <lr@pcorp.us>
Date: Sat, 26 Jan 2013 02:32:22 +0000
Subject: [PATCH] #657: correct the documentation on ST_Project to reflect it
 expects bearing measured in radians and how to handle for both degrees and
 radians

git-svn-id: http://svn.osgeo.org/postgis/trunk@11026 b70326c6-7e19-0410-871a-916f4a2858ee
---
 doc/reference_measure.xml | 33 ++++++++++++++++++++++-----------
 1 file changed, 22 insertions(+), 11 deletions(-)

diff --git a/doc/reference_measure.xml b/doc/reference_measure.xml
index 2bea45009..4458cff16 100644
--- a/doc/reference_measure.xml
+++ b/doc/reference_measure.xml
@@ -3607,11 +3607,11 @@ SELECT ST_AsEWKT(ST_PointOnSurface(ST_GeomFromEWKT('LINESTRING(0 5 1, 0 0 1, 0 1
 	  </refsection>
 	</refentry>
 
-		<refentry id="ST_Project">
+	<refentry id="ST_Project">
 		  <refnamediv>
 			<refname>ST_Project</refname>
 
-			<refpurpose>Returns a <varname>POINT</varname> projected from a start point using a bearing and distance.</refpurpose>
+			<refpurpose>Returns a <varname>POINT</varname> projected from a start point using a distance and bearing (azimuth) in radians.</refpurpose>
 		  </refnamediv>
 
 		  <refsynopsisdiv>
@@ -3632,21 +3632,32 @@ SELECT ST_AsEWKT(ST_PointOnSurface(ST_GeomFromEWKT('LINESTRING(0 5 1, 0 0 1, 0 1
 		  <refsection>
 			<title>Description</title>
 
-			<para>Returns a <varname>POINT</varname> projected from a start point using an azimuth (bearing) and distance.</para>
+			<para>Returns a <varname>POINT</varname> projected from a start point using an azimuth (bearing) measured in radians and distance measured in meters.</para>
 			<para>Distance, azimuth and projection are all aspects of the same operation, describing (or in the case of projection, constructing) the relationship between two points on the world.</para>
-			<para>The azimuth is sometimes called the heading or the bearing in navigation. It is measured relative to true north (azimuth zero). East is azimuth 90, south is azimuth 180, west is azimuth 270.</para>
+			<para>The azimuth is sometimes called the heading or the bearing in navigation. It is measured relative to true north (azimuth zero). East is azimuth 90 (<varname>pi/2</varname>), south is azimuth 180 (<varname>pi</varname>), west is azimuth 270 (<varname>pi*1.5</varname>).</para>
 			<para>The distance is given in meters.</para>
 
 		  </refsection>
 
 		  <refsection>
-			<title>Examples</title>
+			<title>Example: Using degrees - projected point 100,000 meters and bearing 45 degreees </title>
 
-			<programlisting>SELECT ST_AsText(ST_Project('POINT(0 0)'::geography, 100000, 45));
-                  st_astext
-	------------------------------------------
-	 POINT(0.63523102912532 0.63947233472882)
-	(1 row)
+			<programlisting>SELECT ST_AsText(ST_Project('POINT(0 0)'::geography, 100000, radians(45.0)));
+			  st_astext
+------------------------------------------
+ POINT(0.63523102912532 0.63947233472882)
+(1 row)
+	</programlisting>
+		  </refsection>
+		  
+		  <refsection>
+			<title>Example: Using radians - projected point 100,000 meters and bearing pi/4 (45 degreees) </title>
+
+			<programlisting>SELECT ST_AsText(ST_Project('POINT(0 0)'::geography, 100000, pi()/4));
+			  st_astext
+------------------------------------------
+ POINT(0.63523102912532 0.63947233472882)
+(1 row)
 	</programlisting>
 		  </refsection>
 
@@ -3655,7 +3666,7 @@ SELECT ST_AsEWKT(ST_PointOnSurface(ST_GeomFromEWKT('LINESTRING(0 5 1, 0 0 1, 0 1
 
 			<para><xref linkend="ST_Azimuth" />, <xref linkend="ST_Distance" /></para>
 		  </refsection>
-		</refentry>
+	</refentry>
 
 	<refentry id="ST_Relate">
 		<refnamediv>
-- 
2.50.1