From 4b200a27693ebdfb2cc281682adb627069c7d6e1 Mon Sep 17 00:00:00 2001
From: Tom Lane <tgl@sss.pgh.pa.us>
Date: Sat, 3 Jul 2010 04:03:06 +0000
Subject: [PATCH] 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.
---
doc/src/sgml/datatype.sgml | 73 ++++++++++++++++++++++++--------------
1 file changed, 46 insertions(+), 27 deletions(-)
diff --git a/doc/src/sgml/datatype.sgml b/doc/src/sgml/datatype.sgml
index 42907791ca9..20bf2ea9fa2 100644
--- 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.249 2010/06/29 00:03:39 petere Exp $ -->
+<!-- $PostgreSQL: pgsql/doc/src/sgml/datatype.sgml,v 1.250 2010/07/03 04:03:06 tgl Exp $ -->
<chapter id="datatype">
<title>Data Types</title>
@@ -3061,7 +3061,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>
@@ -3073,8 +3073,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> )
@@ -3084,6 +3085,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>
@@ -3099,11 +3104,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>
@@ -3113,6 +3120,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>
@@ -3129,11 +3140,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>
@@ -3145,10 +3157,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>
@@ -3168,20 +3183,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>
@@ -3199,18 +3216,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
@@ -3231,18 +3248,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>
< ( <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>
+ <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>
--
GitLab