summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorTom Lane2010-07-03 04:03:46 +0000
committerTom Lane2010-07-03 04:03:46 +0000
commit5e7776941370491b17755de7472a81631fcfaeae (patch)
treee8c90dc731c11690d95dba647d8bfc8fe3c3ae79
parentfa8ccf59faaec5c026e3721642487cab6fa3b34f (diff)
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.
-rw-r--r--doc/src/sgml/datatype.sgml63
1 files changed, 41 insertions, 22 deletions
diff --git a/doc/src/sgml/datatype.sgml b/doc/src/sgml/datatype.sgml
index 94da75fcf2b..f40eb0d605b 100644
--- a/doc/src/sgml/datatype.sgml
+++ b/doc/src/sgml/datatype.sgml
@@ -1,5 +1,5 @@
<!--
-$Header: /cvsroot/pgsql/doc/src/sgml/datatype.sgml,v 1.128.2.7 2008/01/02 19:53:15 mha Exp $
+$Header: /cvsroot/pgsql/doc/src/sgml/datatype.sgml,v 1.128.2.8 2010/07/03 04:03:46 tgl Exp $
-->
<chapter id="datatype">
@@ -2325,7 +2325,7 @@ SELECT * FROM test1 WHERE a;
<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>
@@ -2337,8 +2337,9 @@ SELECT * FROM test1 WHERE a;
</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> )
@@ -2348,6 +2349,10 @@ SELECT * FROM test1 WHERE a;
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>
@@ -2363,11 +2368,13 @@ SELECT * FROM test1 WHERE a;
<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>
@@ -2377,6 +2384,10 @@ SELECT * FROM test1 WHERE a;
<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>
@@ -2393,7 +2404,8 @@ SELECT * FROM test1 WHERE a;
<para>
Boxes are represented by pairs of points that are opposite
corners of the box.
- Values of type <type>box</type> is 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> ) )
@@ -2409,11 +2421,13 @@ SELECT * FROM test1 WHERE a;
</para>
<para>
- Boxes are output using the first syntax.
- The corners are reordered on input to store
- the upper right corner, then the lower left corner.
- Other corners of the box can be entered, but the lower
- left and upper right corners are determined from the input and stored corners.
+ 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, in that order.
</para>
</sect2>
@@ -2440,20 +2454,22 @@ SELECT * FROM test1 WHERE a;
</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>
@@ -2475,7 +2491,8 @@ SELECT * FROM test1 WHERE a;
</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> ) )
@@ -2502,7 +2519,8 @@ SELECT * FROM test1 WHERE a;
<para>
Circles are represented by a center point and a 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;
@@ -2512,8 +2530,9 @@ SELECT * FROM test1 WHERE a;
</synopsis>
where
- <literal>(<replaceable>x</replaceable>,<replaceable>y</replaceable>)</literal>
- is the center and <replaceable>r</replaceable> is the radius of the circle.
+ <literal>(<replaceable>x</replaceable>,<replaceable>y</replaceable>)</>
+ is the center and <replaceable>r</replaceable> is the radius of the
+ circle.
</para>
<para>