On Wed, Mar 31, 2021 at 01:43:47PM +0200, Christoph Berg wrote:
> Re: Kyotaro Horiguchi
> > Returing to the description of pg_types, it should be changed like
> > this following the discussion here.
> >
> > - pg_catalog | box | geometric box '(lower left,upper right)'
> > + pg_catalog | box | geometric box 'lower left,upper right'
> >
> > But I find it hard to read. I fixed it instead as the following in the
> > attached. However, it might rather be better not changing it..
> >
> > + pg_catalog | box | geometric box 'pt-lower-left,pt-upper-right'
>
> I like that because it points to the "point" syntax so users can
> figure out how to spell a box.
I liked Horiguchi-san's patch from 2021, but once I started looking
further, I found a number of improvements that can be made in the \dTS
output beyond Horiguchi-san's changes:
* boolean outputs 't'/'f', not 'true'/'false'
* Added "format" ... for output
* tid output format was at the start, not the end
* I didn't add space between point x,y because the output has no space
* I spelled out "point" instead of "pt"
* "line" has two very different input formats so I listed both
(more different than others like boolean)
* I didn't see the need to say "datatype" for LSN and UUID
* I improved the txid_snapshot description
* There was no description for table_am_handler
Patch attached.
--
Bruce Momjian <[email protected]> https://momjian.us
EDB https://enterprisedb.com
Only you can decide what is important to you.
diff --git a/doc/src/sgml/datatype.sgml b/doc/src/sgml/datatype.sgml
index 5a6cfbd94d..55340b00ad 100644
--- a/doc/src/sgml/datatype.sgml
+++ b/doc/src/sgml/datatype.sgml
@@ -3366,13 +3366,13 @@ SELECT person.name, holidays.num_weeks FROM person, holidays
<entry><type>lseg</type></entry>
<entry>32 bytes</entry>
<entry>Finite line segment</entry>
- <entry>((x1,y1),(x2,y2))</entry>
+ <entry>[(x1,y1),(x2,y2)]</entry>
</row>
<row>
<entry><type>box</type></entry>
<entry>32 bytes</entry>
<entry>Rectangular box</entry>
- <entry>((x1,y1),(x2,y2))</entry>
+ <entry>(x1,y1),(x2,y2)</entry>
</row>
<row>
<entry><type>path</type></entry>
diff --git a/src/include/catalog/pg_type.dat b/src/include/catalog/pg_type.dat
index 92bcaf2c73..6fd3c64e40 100644
--- a/src/include/catalog/pg_type.dat
+++ b/src/include/catalog/pg_type.dat
@@ -32,7 +32,7 @@
# OIDS 1 - 99
{ oid => '16', array_type_oid => '1000',
- descr => 'boolean, \'true\'/\'false\'',
+ descr => 'boolean, format \'t\'/\'f\'',
typname => 'bool', typlen => '1', typbyval => 't', typcategory => 'B',
typispreferred => 't', typinput => 'boolin', typoutput => 'boolout',
typreceive => 'boolrecv', typsend => 'boolsend', typalign => 'c' },
@@ -90,7 +90,7 @@
typispreferred => 't', typinput => 'oidin', typoutput => 'oidout',
typreceive => 'oidrecv', typsend => 'oidsend', typalign => 'i' },
{ oid => '27', array_type_oid => '1010',
- descr => '(block, offset), physical location of tuple',
+ descr => 'tuple physical location, format \'(block,offset)\'',
typname => 'tid', typlen => '6', typbyval => 'f', typcategory => 'U',
typinput => 'tidin', typoutput => 'tidout', typreceive => 'tidrecv',
typsend => 'tidsend', typalign => 's' },
@@ -179,34 +179,34 @@
# OIDS 600 - 699
{ oid => '600', array_type_oid => '1017',
- descr => 'geometric point \'(x, y)\'',
+ descr => 'geometric point, format \'(x,y)\'',
typname => 'point', typlen => '16', typbyval => 'f', typcategory => 'G',
typsubscript => 'raw_array_subscript_handler', typelem => 'float8',
typinput => 'point_in', typoutput => 'point_out', typreceive => 'point_recv',
typsend => 'point_send', typalign => 'd' },
{ oid => '601', array_type_oid => '1018',
- descr => 'geometric line segment \'(pt1,pt2)\'',
+ descr => 'geometric line segment, format \'[point1,point2]\'',
typname => 'lseg', typlen => '32', typbyval => 'f', typcategory => 'G',
typsubscript => 'raw_array_subscript_handler', typelem => 'point',
typinput => 'lseg_in', typoutput => 'lseg_out', typreceive => 'lseg_recv',
typsend => 'lseg_send', typalign => 'd' },
{ oid => '602', array_type_oid => '1019',
- descr => 'geometric path \'(pt1,...)\'',
+ descr => 'geometric path, format \'(point1,...)\'',
typname => 'path', typlen => '-1', typbyval => 'f', typcategory => 'G',
typinput => 'path_in', typoutput => 'path_out', typreceive => 'path_recv',
typsend => 'path_send', typalign => 'd', typstorage => 'x' },
{ oid => '603', array_type_oid => '1020',
- descr => 'geometric box \'(lower left,upper right)\'',
+ descr => 'geometric box, format \'lower left point,upper right point\'',
typname => 'box', typlen => '32', typbyval => 'f', typcategory => 'G',
typdelim => ';', typsubscript => 'raw_array_subscript_handler',
typelem => 'point', typinput => 'box_in', typoutput => 'box_out',
typreceive => 'box_recv', typsend => 'box_send', typalign => 'd' },
{ oid => '604', array_type_oid => '1027',
- descr => 'geometric polygon \'(pt1,...)\'',
+ descr => 'geometric polygon, format \'(point1,...)\'',
typname => 'polygon', typlen => '-1', typbyval => 'f', typcategory => 'G',
typinput => 'poly_in', typoutput => 'poly_out', typreceive => 'poly_recv',
typsend => 'poly_send', typalign => 'd', typstorage => 'x' },
-{ oid => '628', array_type_oid => '629', descr => 'geometric line',
+{ oid => '628', array_type_oid => '629', descr => 'geometric line, formats \'{A,B,C}\'/\'[point1,point2]\'',
typname => 'line', typlen => '24', typbyval => 'f', typcategory => 'G',
typsubscript => 'raw_array_subscript_handler', typelem => 'float8',
typinput => 'line_in', typoutput => 'line_out', typreceive => 'line_recv',
@@ -230,7 +230,7 @@
typcategory => 'X', typinput => 'unknownin', typoutput => 'unknownout',
typreceive => 'unknownrecv', typsend => 'unknownsend', typalign => 'c' },
{ oid => '718', array_type_oid => '719',
- descr => 'geometric circle \'(center,radius)\'',
+ descr => 'geometric circle, format \'<center point,radius>\'',
typname => 'circle', typlen => '24', typbyval => 'f', typcategory => 'G',
typinput => 'circle_in', typoutput => 'circle_out',
typreceive => 'circle_recv', typsend => 'circle_send', typalign => 'd' },
@@ -271,14 +271,14 @@
typinput => 'aclitemin', typoutput => 'aclitemout', typreceive => '-',
typsend => '-', typalign => 'd' },
{ oid => '1042', array_type_oid => '1014',
- descr => 'char(length), blank-padded string, fixed storage length',
+ descr => '\'char(length)\' blank-padded string, fixed storage length',
typname => 'bpchar', typlen => '-1', typbyval => 'f', typcategory => 'S',
typinput => 'bpcharin', typoutput => 'bpcharout', typreceive => 'bpcharrecv',
typsend => 'bpcharsend', typmodin => 'bpchartypmodin',
typmodout => 'bpchartypmodout', typalign => 'i', typstorage => 'x',
typcollation => 'default' },
{ oid => '1043', array_type_oid => '1015',
- descr => 'varchar(length), non-blank-padded string, variable storage length',
+ descr => '\'varchar(length)\' non-blank-padded string, variable storage length',
typname => 'varchar', typlen => '-1', typbyval => 'f', typcategory => 'S',
typinput => 'varcharin', typoutput => 'varcharout',
typreceive => 'varcharrecv', typsend => 'varcharsend',
@@ -345,7 +345,7 @@
# OIDS 1700 - 1799
{ oid => '1700', array_type_oid => '1231',
- descr => 'numeric(precision, decimal), arbitrary precision number',
+ descr => '\'numeric(precision, decimal)\' arbitrary precision number',
typname => 'numeric', typlen => '-1', typbyval => 'f', typcategory => 'N',
typinput => 'numeric_in', typoutput => 'numeric_out',
typreceive => 'numeric_recv', typsend => 'numeric_send',
@@ -400,13 +400,13 @@
typalign => 'i' },
# uuid
-{ oid => '2950', array_type_oid => '2951', descr => 'UUID datatype',
+{ oid => '2950', array_type_oid => '2951', descr => 'UUID',
typname => 'uuid', typlen => '16', typbyval => 'f', typcategory => 'U',
typinput => 'uuid_in', typoutput => 'uuid_out', typreceive => 'uuid_recv',
typsend => 'uuid_send', typalign => 'c' },
# pg_lsn
-{ oid => '3220', array_type_oid => '3221', descr => 'PostgreSQL LSN datatype',
+{ oid => '3220', array_type_oid => '3221', descr => 'PostgreSQL LSN',
typname => 'pg_lsn', typlen => '8', typbyval => 'FLOAT8PASSBYVAL',
typcategory => 'U', typinput => 'pg_lsn_in', typoutput => 'pg_lsn_out',
typreceive => 'pg_lsn_recv', typsend => 'pg_lsn_send', typalign => 'd' },
@@ -452,7 +452,7 @@
typreceive => 'jsonpath_recv', typsend => 'jsonpath_send', typalign => 'i',
typstorage => 'x' },
-{ oid => '2970', array_type_oid => '2949', descr => 'txid snapshot',
+{ oid => '2970', array_type_oid => '2949', descr => 'transaction snapshot',
typname => 'txid_snapshot', typlen => '-1', typbyval => 'f',
typcategory => 'U', typinput => 'txid_snapshot_in',
typoutput => 'txid_snapshot_out', typreceive => 'txid_snapshot_recv',
@@ -633,7 +633,9 @@
typoutput => 'tsm_handler_out', typreceive => '-', typsend => '-',
typalign => 'i' },
{ oid => '269',
- typname => 'table_am_handler', typlen => '4', typbyval => 't', typtype => 'p',
+ typname => 'table_am_handler',
+ descr => 'pseudo-type for the result of a table AM handler function',
+ typlen => '4', typbyval => 't', typtype => 'p',
typcategory => 'P', typinput => 'table_am_handler_in',
typoutput => 'table_am_handler_out', typreceive => '-', typsend => '-',
typalign => 'i' },
