Received: from malur.postgresql.org ([217.196.149.56])
	by arkaria.postgresql.org with esmtps  (TLS1.3) tls
 TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384
	(Exim 4.94.2)
	(envelope-from <pgsql-docs-owner+archive@lists.postgresql.org>)
	id 1sP5uv-002r3P-R6
	for pgsql-docs@arkaria.postgresql.org; Wed, 03 Jul 2024 19:45:25 +0000
Received: from localhost ([127.0.0.1] helo=malur.postgresql.org)
	by malur.postgresql.org with esmtp (Exim 4.94.2)
	(envelope-from <pgsql-docs-owner+archive@lists.postgresql.org>)
	id 1sP5ut-00BkKp-61
	for pgsql-docs@arkaria.postgresql.org; Wed, 03 Jul 2024 19:45:23 +0000
Received: from magus.postgresql.org ([2a02:c0:301:0:ffff::29])
	by malur.postgresql.org with esmtps  (TLS1.3) tls
 TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384
	(Exim 4.94.2)
	(envelope-from <tgl@sss.pgh.pa.us>)
	id 1sP5us-00BkKg-Uo
	for pgsql-docs@lists.postgresql.org; Wed, 03 Jul 2024 19:45:23 +0000
Received: from sss.pgh.pa.us ([68.162.161.243])
	by magus.postgresql.org with esmtps  (TLS1.3) tls
 TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384
	(Exim 4.94.2)
	(envelope-from <tgl@sss.pgh.pa.us>)
	id 1sP5ur-000GjV-C6
	for pgsql-docs@lists.postgresql.org; Wed, 03 Jul 2024 19:45:23 +0000
Received: from sss1.sss.pgh.pa.us (localhost [127.0.0.1])
	by sss.pgh.pa.us (8.15.2/8.15.2) with ESMTP id 463JjI2F3282372;
	Wed, 3 Jul 2024 15:45:18 -0400
From: Tom Lane <tgl@sss.pgh.pa.us>
To: skalee@gmail.com
cc: pgsql-docs@lists.postgresql.org
Subject: Re: Chapter "8.8 Geometric Types" of documentation could contain more
 details
In-reply-to: <172000045661.706.1822177575291548794@wrigleys.postgresql.org>
References: <172000045661.706.1822177575291548794@wrigleys.postgresql.org>
Comments: In-reply-to PG Doc comments form <noreply@postgresql.org>
	message dated "Wed, 03 Jul 2024 09:54:16 -0000"
MIME-Version: 1.0
Content-Type: multipart/mixed; boundary="----- =_aaaaaaaaaa0"
Content-ID: <3282350.1720035901.0@sss.pgh.pa.us>
Date: Wed, 03 Jul 2024 15:45:18 -0400
Message-ID: <3282371.1720035918@sss.pgh.pa.us>
List-Id: <pgsql-docs.lists.postgresql.org>
List-Help: <https://lists.postgresql.org/manage/>
List-Subscribe: <https://lists.postgresql.org/manage/>
List-Post: <mailto:pgsql-docs@lists.postgresql.org>
List-Owner: <mailto:pgsql-docs-owner@lists.postgresql.org>
List-Archive: <https://www.postgresql.org/list/pgsql-docs>
Archived-At: 
 <https://www.postgresql.org/message-id/3282371.1720035918%40sss.pgh.pa.us>
Precedence: bulk

------- =_aaaaaaaaaa0
Content-Type: text/plain; charset="us-ascii"
Content-ID: <3282350.1720035901.1@sss.pgh.pa.us>

PG Doc comments form <noreply@postgresql.org> writes:
> Hi, I am writing to suggest a couple of clarifications to "8.8. Geometric
> Types" documentation chapter.

Fair points.  I am not really eager to say explicitly here that the
set of available functions varies for the different types: that seems
pretty self-evident.  But your other ideas are good.

I also noted while looking at this that table 8.20 is flat out wrong
about the storage size of "line" values: they are 24 bytes each not
32.  (This can be confirmed from pg_type.typlen or by looking at
struct LINE in the source code.)

How about the attached?

			regards, tom lane


------- =_aaaaaaaaaa0
Content-Type: text/x-diff; name="geometric-types-doc-improvement.patch";
	charset="us-ascii"
Content-ID: <3282350.1720035901.2@sss.pgh.pa.us>
Content-Description: geometric-types-doc-improvement.patch
Content-Transfer-Encoding: quoted-printable

diff --git a/doc/src/sgml/datatype.sgml b/doc/src/sgml/datatype.sgml
index 6646820d6a..a693424a69 100644
--- a/doc/src/sgml/datatype.sgml
+++ b/doc/src/sgml/datatype.sgml
@@ -3369,7 +3369,7 @@ SELECT person.name, holidays.num_weeks FROM person, =
holidays
        </row>
        <row>
         <entry><type>line</type></entry>
-        <entry>32 bytes</entry>
+        <entry>24 bytes</entry>
         <entry>Infinite line</entry>
         <entry>{A,B,C}</entry>
        </row>
@@ -3413,6 +3413,11 @@ SELECT person.name, holidays.num_weeks FROM person,=
 holidays
      </tgroup>
     </table>
 =

+   <para>
+    In all these types, the individual coordinates are stored as
+    <type>double precision</type> (<type>float8</type>) numbers.
+   </para>
+
    <para>
     A rich set of functions and operators is available to perform various=
 geometric
     operations such as scaling, translation, rotation, and determining
@@ -3607,6 +3612,14 @@ SELECT person.name, holidays.num_weeks FROM person,=
 holidays
      within it, while a path is not.
     </para>
 =

+    <para>
+     An important implementation difference between polygons and closed
+     paths is that the stored representation of a polygon includes its
+     smallest bounding box.  This speeds up certain search operations,
+     although computing the bounding box adds overhead while constructing
+     new polygons.
+    </para>
+
     <para>
      Values of type <type>polygon</type> are specified using any of the
      following syntaxes:

------- =_aaaaaaaaaa0--