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 42907791ca9b172ff428ced87d689828ddd30978..20bf2ea9fa22613114634493f40f65fa53c45d06 100644 (file)
--- a/doc/src/sgml/datatype.sgml
+++ b/doc/src/sgml/datatype.sgml
@@ -1,4 +1,4 @@
-
+
 
  
   Data Types
@@ -3061,7 +3061,7 @@ SELECT person.name, holidays.num_weeks FROM person, holidays
 
    
     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 .
    
 
@@ -3073,8 +3073,9 @@ SELECT person.name, holidays.num_weeks FROM person, holidays
     
 
     
-     Points are the fundamental two-dimensional building block for geometric types.
-     Values of type point are specified using the following syntax:
+     Points are the fundamental two-dimensional building block for geometric
+     types.  Values of type point are specified using either of
+     the following syntaxes:
 
 
 ( x , y )
@@ -3084,6 +3085,10 @@ SELECT person.name, holidays.num_weeks FROM person, holidays
      where x and y are the respective
      coordinates, as floating-point numbers.
     
+
+    
+     Points are output using the first syntax.
+    
    
 
    
@@ -3099,11 +3104,13 @@ SELECT person.name, holidays.num_weeks FROM person, holidays
 
     
      Line segments (lseg) are represented by pairs of points.
-     Values of type lseg are specified using the following syntax:
+     Values of type lseg are specified using any of the following
+     syntaxes:
 
 
+[ ( x1 , y1 ) , ( x2 , y2 ) ]
 ( ( x1 , y1 ) , ( x2 , y2 ) )
-  ( x1 , y1 ) , ( x2 , y2 )  
+  ( x1 , y1 ) , ( x2 , y2 )
     x1 , y1   ,   x2 , y2
 
 
@@ -3113,6 +3120,10 @@ SELECT person.name, holidays.num_weeks FROM person, holidays
      (x2,y2)
      are the end points of the line segment.
     
+
+    
+     Line segments are output using the first syntax.
+    
    
 
    
@@ -3129,11 +3140,12 @@ SELECT person.name, holidays.num_weeks FROM person, holidays
     
      Boxes are represented by pairs of points that are opposite
      corners of the box.
-     Values of type box are specified using the following syntax:
+     Values of type box are specified using any of the following
+     syntaxes:
 
 
 ( ( x1 , y1 ) , ( x2 , y2 ) )
-  ( x1 , y1 ) , ( x2 , y2 )  
+  ( x1 , y1 ) , ( x2 , y2 )
     x1 , y1   ,   x2 , y2
 
 
@@ -3145,10 +3157,13 @@ SELECT person.name, holidays.num_weeks FROM person, holidays
     
 
     
-     Boxes are output using the first syntax.
+     Boxes are output using the second syntax.
+    
+
+    
      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.
     
    
 
@@ -3168,20 +3183,22 @@ SELECT person.name, holidays.num_weeks FROM person, holidays
     
 
     
-     Values of type path are specified using the following syntax:
+     Values of type path are specified using any of the following
+     syntaxes:
 
 
-( ( x1 , y1 ) , ... , ( xn , yn ) )
 [ ( x1 , y1 ) , ... , ( xn , yn ) ]
-  ( x1 , y1 ) , ... , ( xn , yn )  
-  ( x1 , y1   , ... ,   xn , yn )  
-    x1 , y1   , ... ,   xn , yn    
+( ( x1 , y1 ) , ... , ( xn , yn ) )
+  ( x1 , y1 ) , ... , ( xn , yn )
+  ( x1 , y1   , ... ,   xn , yn )
+    x1 , y1   , ... ,   xn , yn
 
 
      where the points are the end points of the line segments
      comprising the path.  Square brackets ([]) indicate
      an open path, while parentheses (()) indicate a
-     closed path.
+     closed path.  When the outermost parentheses are omitted, as
+     in the third through fifth syntaxes, a closed path is assumed.
     
 
     
@@ -3199,18 +3216,18 @@ SELECT person.name, holidays.num_weeks FROM person, holidays
     
      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.
     
 
     
-     Values of type polygon are specified using the following syntax:
+     Values of type polygon are specified using any of the
+     following syntaxes:
 
 
 ( ( x1 , y1 ) , ... , ( xn , yn ) )
-  ( x1 , y1 ) , ... , ( xn , yn )  
-  ( x1 , y1   , ... ,   xn , yn )  
-    x1 , y1   , ... ,   xn , yn    
+  ( x1 , y1 ) , ... , ( xn , yn )
+  ( x1 , y1   , ... ,   xn , yn )
+    x1 , y1   , ... ,   xn , yn
 
 
      where the points are the end points of the line segments
@@ -3231,18 +3248,20 @@ SELECT person.name, holidays.num_weeks FROM person, holidays
 
     
      Circles are represented by a center point and radius.
-     Values of type circle are specified using the following syntax:
+     Values of type circle are specified using any of the
+     following syntaxes:
 
 
 < ( x , y ) , r >
 ( ( x , y ) , r )
-  ( x , y ) , r  
-    x , y   , r  
+  ( x , y ) , r
+    x , y   , r
 
 
      where
-     (x,y)
-     is the center point and r is the radius of the circle.
+     (x,y)
+     is the center point and r is the radius of the
+     circle.