Fix assorted misstatements and poor wording in the descriptions of the I/O

formats for geometric types.  Per bug #5536 from Jon Strait, and my own
testing.

Back-patch to all supported branches, since this doco has been wrong right
along -- we certainly haven't changed the I/O behavior of these types in
many years.

diff --git a/doc/src/sgml/datatype.sgml b/doc/src/sgml/datatype.sgml
index 14efb14553e1e7f095ad59e065b737d6c8be3a54..b8dd8a5edced1f40ba2fe3d34bfd5443abc27c39 100644 (file)
--- a/doc/src/sgml/datatype.sgml
+++ b/doc/src/sgml/datatype.sgml
@@ -1,4 +1,4 @@
-<!-- $PostgreSQL: pgsql/doc/src/sgml/datatype.sgml,v 1.239.2.1 2009/07/08 17:22:01 tgl Exp $ -->
+<!-- $PostgreSQL: pgsql/doc/src/sgml/datatype.sgml,v 1.239.2.2 2010/07/03 04:03:14 tgl Exp $ -->
 
  <chapter id="datatype">
   <title id="datatype-title">Data Types</title>
@@ -2997,7 +2997,7 @@ SELECT person.name, holidays.num_weeks FROM person, holidays
 
    <para>
     A rich set of functions and operators is available to perform various geometric
-    operations such as scaling, translation, rotation, and determining 
+    operations such as scaling, translation, rotation, and determining
     intersections.  They are explained in <xref linkend="functions-geometry">.
    </para>
 
@@ -3009,8 +3009,9 @@ SELECT person.name, holidays.num_weeks FROM person, holidays
     </indexterm>
 
     <para>
-     Points are the fundamental two-dimensional building block for geometric types.
-     Values of type <type>point</type> are specified using the following syntax:
+     Points are the fundamental two-dimensional building block for geometric
+     types.  Values of type <type>point</type> are specified using either of
+     the following syntaxes:
 
 <synopsis>
 ( <replaceable>x</replaceable> , <replaceable>y</replaceable> )
@@ -3020,6 +3021,10 @@ SELECT person.name, holidays.num_weeks FROM person, holidays
      where <replaceable>x</> and <replaceable>y</> are the respective
      coordinates, as floating-point numbers.
     </para>
+
+    <para>
+     Points are output using the first syntax.
+    </para>
    </sect2>
 
    <sect2>
@@ -3035,11 +3040,13 @@ SELECT person.name, holidays.num_weeks FROM person, holidays
 
     <para>
      Line segments (<type>lseg</type>) are represented by pairs of points.
-     Values of type <type>lseg</type> are specified using the following syntax:
+     Values of type <type>lseg</type> are specified using any of the following
+     syntaxes:
 
 <synopsis>
+[ ( <replaceable>x1</replaceable> , <replaceable>y1</replaceable> ) , ( <replaceable>x2</replaceable> , <replaceable>y2</replaceable> ) ]
 ( ( <replaceable>x1</replaceable> , <replaceable>y1</replaceable> ) , ( <replaceable>x2</replaceable> , <replaceable>y2</replaceable> ) )
-  ( <replaceable>x1</replaceable> , <replaceable>y1</replaceable> ) , ( <replaceable>x2</replaceable> , <replaceable>y2</replaceable> )  
+  ( <replaceable>x1</replaceable> , <replaceable>y1</replaceable> ) , ( <replaceable>x2</replaceable> , <replaceable>y2</replaceable> )
     <replaceable>x1</replaceable> , <replaceable>y1</replaceable>   ,   <replaceable>x2</replaceable> , <replaceable>y2</replaceable>
 </synopsis>
 
@@ -3049,6 +3056,10 @@ SELECT person.name, holidays.num_weeks FROM person, holidays
      <literal>(<replaceable>x2</replaceable>,<replaceable>y2</replaceable>)</literal>
      are the end points of the line segment.
     </para>
+
+    <para>
+     Line segments are output using the first syntax.
+    </para>
    </sect2>
 
    <sect2>
@@ -3065,11 +3076,12 @@ SELECT person.name, holidays.num_weeks FROM person, holidays
     <para>
      Boxes are represented by pairs of points that are opposite
      corners of the box.
-     Values of type <type>box</type> are specified using the following syntax:
+     Values of type <type>box</type> are specified using any of the following
+     syntaxes:
 
 <synopsis>
 ( ( <replaceable>x1</replaceable> , <replaceable>y1</replaceable> ) , ( <replaceable>x2</replaceable> , <replaceable>y2</replaceable> ) )
-  ( <replaceable>x1</replaceable> , <replaceable>y1</replaceable> ) , ( <replaceable>x2</replaceable> , <replaceable>y2</replaceable> )  
+  ( <replaceable>x1</replaceable> , <replaceable>y1</replaceable> ) , ( <replaceable>x2</replaceable> , <replaceable>y2</replaceable> )
     <replaceable>x1</replaceable> , <replaceable>y1</replaceable>   ,   <replaceable>x2</replaceable> , <replaceable>y2</replaceable>
 </synopsis>
 
@@ -3081,10 +3093,13 @@ SELECT person.name, holidays.num_weeks FROM person, holidays
     </para>
 
     <para>
-     Boxes are output using the first syntax.
+     Boxes are output using the second syntax.
+    </para>
+
+    <para>
      Any two opposite corners can be supplied on input, but the values
      will be reordered as needed to store the
-     upper right and lower left corners.
+     upper right and lower left corners, in that order.
     </para>
    </sect2>
 
@@ -3104,20 +3119,22 @@ SELECT person.name, holidays.num_weeks FROM person, holidays
     </para>
 
     <para>
-     Values of type <type>path</type> are specified using the following syntax:
+     Values of type <type>path</type> are specified using any of the following
+     syntaxes:
 
 <synopsis>
-( ( <replaceable>x1</replaceable> , <replaceable>y1</replaceable> ) , ... , ( <replaceable>xn</replaceable> , <replaceable>yn</replaceable> ) )
 [ ( <replaceable>x1</replaceable> , <replaceable>y1</replaceable> ) , ... , ( <replaceable>xn</replaceable> , <replaceable>yn</replaceable> ) ]
-  ( <replaceable>x1</replaceable> , <replaceable>y1</replaceable> ) , ... , ( <replaceable>xn</replaceable> , <replaceable>yn</replaceable> )  
-  ( <replaceable>x1</replaceable> , <replaceable>y1</replaceable>   , ... ,   <replaceable>xn</replaceable> , <replaceable>yn</replaceable> )  
-    <replaceable>x1</replaceable> , <replaceable>y1</replaceable>   , ... ,   <replaceable>xn</replaceable> , <replaceable>yn</replaceable>    
+( ( <replaceable>x1</replaceable> , <replaceable>y1</replaceable> ) , ... , ( <replaceable>xn</replaceable> , <replaceable>yn</replaceable> ) )
+  ( <replaceable>x1</replaceable> , <replaceable>y1</replaceable> ) , ... , ( <replaceable>xn</replaceable> , <replaceable>yn</replaceable> )
+  ( <replaceable>x1</replaceable> , <replaceable>y1</replaceable>   , ... ,   <replaceable>xn</replaceable> , <replaceable>yn</replaceable> )
+    <replaceable>x1</replaceable> , <replaceable>y1</replaceable>   , ... ,   <replaceable>xn</replaceable> , <replaceable>yn</replaceable>
 </synopsis>
 
      where the points are the end points of the line segments
      comprising the path.  Square brackets (<literal>[]</>) indicate
      an open path, while parentheses (<literal>()</>) indicate a
-     closed path.
+     closed path.  When the outermost parentheses are omitted, as
+     in the third through fifth syntaxes, a closed path is assumed.
     </para>
 
     <para>
@@ -3135,18 +3152,18 @@ SELECT person.name, holidays.num_weeks FROM person, holidays
     <para>
      Polygons are represented by lists of points (the vertexes of the
      polygon). Polygons are very similar to closed paths, but are
-     stored differently
-     and have their own set of support routines.
+     stored differently and have their own set of support routines.
     </para>
 
     <para>
-     Values of type <type>polygon</type> are specified using the following syntax:
+     Values of type <type>polygon</type> are specified using any of the
+     following syntaxes:
 
 <synopsis>
 ( ( <replaceable>x1</replaceable> , <replaceable>y1</replaceable> ) , ... , ( <replaceable>xn</replaceable> , <replaceable>yn</replaceable> ) )
-  ( <replaceable>x1</replaceable> , <replaceable>y1</replaceable> ) , ... , ( <replaceable>xn</replaceable> , <replaceable>yn</replaceable> )  
-  ( <replaceable>x1</replaceable> , <replaceable>y1</replaceable>   , ... ,   <replaceable>xn</replaceable> , <replaceable>yn</replaceable> )  
-    <replaceable>x1</replaceable> , <replaceable>y1</replaceable>   , ... ,   <replaceable>xn</replaceable> , <replaceable>yn</replaceable>    
+  ( <replaceable>x1</replaceable> , <replaceable>y1</replaceable> ) , ... , ( <replaceable>xn</replaceable> , <replaceable>yn</replaceable> )
+  ( <replaceable>x1</replaceable> , <replaceable>y1</replaceable>   , ... ,   <replaceable>xn</replaceable> , <replaceable>yn</replaceable> )
+    <replaceable>x1</replaceable> , <replaceable>y1</replaceable>   , ... ,   <replaceable>xn</replaceable> , <replaceable>yn</replaceable>
 </synopsis>
 
      where the points are the end points of the line segments
@@ -3167,18 +3184,20 @@ SELECT person.name, holidays.num_weeks FROM person, holidays
 
     <para>
      Circles are represented by a center point and radius.
-     Values of type <type>circle</type> are specified using the following syntax:
+     Values of type <type>circle</type> are specified using any of the
+     following syntaxes:
 
 <synopsis>
 &lt; ( <replaceable>x</replaceable> , <replaceable>y</replaceable> ) , <replaceable>r</replaceable> &gt;
 ( ( <replaceable>x</replaceable> , <replaceable>y</replaceable> ) , <replaceable>r</replaceable> )
-  ( <replaceable>x</replaceable> , <replaceable>y</replaceable> ) , <replaceable>r</replaceable>  
-    <replaceable>x</replaceable> , <replaceable>y</replaceable>   , <replaceable>r</replaceable>  
+  ( <replaceable>x</replaceable> , <replaceable>y</replaceable> ) , <replaceable>r</replaceable>
+    <replaceable>x</replaceable> , <replaceable>y</replaceable>   , <replaceable>r</replaceable>
 </synopsis>
 
      where
-     <literal>(<replaceable>x</replaceable>,<replaceable>y</replaceable>)</literal>
-     is the center point and <replaceable>r</replaceable> is the radius of the circle.
+     <literal>(<replaceable>x</replaceable>,<replaceable>y</replaceable>)</>
+     is the center point and <replaceable>r</replaceable> is the radius of the
+     circle.
     </para>
 
     <para>