Content-Type: multipart/mixed; boundary="------------F8JC7QyYNfct3qCjqttzYAuK"
Message-ID: <38aa8e65-32e2-4578-bfc8-0d9f59efe049@postgrespro.ru>
Date: Fri, 12 Apr 2024 23:20:27 +0300
MIME-Version: 1.0
User-Agent: Mozilla Thunderbird
To: pgsql-docs <pgsql-docs@lists.postgresql.org>
Content-Language: en-US
From: Anton Voloshin <a.voloshin@postgrespro.ru>
Subject: three small improvements for "Composite Types" page
Archived-At: 
 <https://www.postgresql.org/message-id/38aa8e65-32e2-4578-bfc8-0d9f59efe049%40postgrespro.ru>
Precedence: bulk

This is a multi-part message in MIME format.
--------------F8JC7QyYNfct3qCjqttzYAuK
Content-Type: text/plain; charset=UTF-8; format=flowed
Content-Transfer-Encoding: 7bit

Hello,

While reading "Composite Types" manual page I've noticed that it is
somewhat hard to follow by trying out given examples. I suggest three
small changes which would make this page a little easier to follow for
me:

1. Clarify "different kind" by adding a link to a section of "create
type" page

 > Note that the AS keyword is essential; without it, the system will 
think a different kind of CREATE TYPE command is meant, and you will get 
odd syntax errors.

Here there is no link to CREATE TYPE, so it's not so easy to go there to
see what is that "different kind" of CREATE TYPE. I suggest to add an
anchor for the "Base Types" section there and link the words "different
kind" there.

2. make first mention of CREATE TABLE a link

 > The syntax is comparable to CREATE TABLE, except ...

It would be useful if this CREATE TABLE (first on this page) would
become a link.

3. Simplify CREATE TABLE example to make it self-sufficient

One of the examples on the same "Composite Types" page is an example of
CREATE TABLE:

CREATE TABLE inventory_item (
     name            text,
     supplier_id     integer REFERENCES suppliers,
     price           numeric CHECK (price > 0)
);

This example is not self-sufficient: it requires one to have "suppliers"
table with specific column to work as given. This table is actively used
in examples below, like
SELECT * FROM inventory_item c ORDER BY c;
and many others, so I think it's important to make this example easy to
reproduce. It seems to me that loosing "REFERENCES suppliers", while
loses something a bit interesting, adds something more important:
simplicity for the newcomers. So I suggest removing this part.

Please see attached patches as an example of these three changes.

Any comments? Do you think this is an improvement?

-- 
Anton Voloshin
Postgres Professional, The Russian Postgres Company
https://postgrespro.ru
--------------F8JC7QyYNfct3qCjqttzYAuK
Content-Type: text/x-patch; charset=UTF-8;
 name="0001-clarify-different-kind-by-adding-a-link-to-a-section.patch"
Content-Disposition: attachment;
 filename*0="0001-clarify-different-kind-by-adding-a-link-to-a-section.pa";
 filename*1="tch"
Content-Transfer-Encoding: base64

RnJvbSBkZjJhMWI1Y2IzMjNkNjM5YmNmNzVmYWM2Nzk5Yjg5YjQwZGVjOTcyIE1vbiBTZXAg
MTcgMDA6MDA6MDAgMjAwMQpGcm9tOiBBbnRvbiBWb2xvc2hpbiA8YS52b2xvc2hpbkBwb3N0
Z3Jlc3Byby5ydT4KRGF0ZTogRnJpLCAxMiBBcHIgMjAyNCAyMjo0OToxNyArMDMwMApTdWJq
ZWN0OiBbUEFUQ0ggMS8zXSBjbGFyaWZ5ICJkaWZmZXJlbnQga2luZCIgYnkgYWRkaW5nIGEg
bGluayB0byBhIHNlY3Rpb24gb2YKICJjcmVhdGUgdHlwZSIgcGFnZQoKLS0tCiBkb2Mvc3Jj
L3NnbWwvcmVmL2NyZWF0ZV90eXBlLnNnbWwgfCAyICstCiBkb2Mvc3JjL3NnbWwvcm93dHlw
ZXMuc2dtbCAgICAgICAgfCAzICsrLQogMiBmaWxlcyBjaGFuZ2VkLCAzIGluc2VydGlvbnMo
KyksIDIgZGVsZXRpb25zKC0pCgpkaWZmIC0tZ2l0IGEvZG9jL3NyYy9zZ21sL3JlZi9jcmVh
dGVfdHlwZS5zZ21sIGIvZG9jL3NyYy9zZ21sL3JlZi9jcmVhdGVfdHlwZS5zZ21sCmluZGV4
IDk5NGRmYzY1MjY4Li5iOTc1NTMxODY0YiAxMDA2NDQKLS0tIGEvZG9jL3NyYy9zZ21sL3Jl
Zi9jcmVhdGVfdHlwZS5zZ21sCisrKyBiL2RvYy9zcmMvc2dtbC9yZWYvY3JlYXRlX3R5cGUu
c2dtbApAQCAtMTg4LDcgKzE4OCw3IEBAIENSRUFURSBUWVBFIDxyZXBsYWNlYWJsZSBjbGFz
cz0icGFyYW1ldGVyIj5uYW1lPC9yZXBsYWNlYWJsZT4KICAgIDwvcGFyYT4KICAgPC9yZWZz
ZWN0Mj4KIAotICA8cmVmc2VjdDI+CisgIDxyZWZzZWN0MiBpZD0ic3FsLWNyZWF0ZXR5cGUt
YmFzZSI+CiAgICA8dGl0bGU+QmFzZSBUeXBlczwvdGl0bGU+CiAKICAgPHBhcmE+CmRpZmYg
LS1naXQgYS9kb2Mvc3JjL3NnbWwvcm93dHlwZXMuc2dtbCBiL2RvYy9zcmMvc2dtbC9yb3d0
eXBlcy5zZ21sCmluZGV4IGJiZWFjODRkNDZhLi45ZDY1OGE3MGM0MSAxMDA2NDQKLS0tIGEv
ZG9jL3NyYy9zZ21sL3Jvd3R5cGVzLnNnbWwKKysrIGIvZG9jL3NyYy9zZ21sL3Jvd3R5cGVz
LnNnbWwKQEAgLTM5LDcgKzM5LDggQEAgQ1JFQVRFIFRZUEUgaW52ZW50b3J5X2l0ZW0gQVMg
KAogICBUaGUgc3ludGF4IGlzIGNvbXBhcmFibGUgdG8gPGNvbW1hbmQ+Q1JFQVRFIFRBQkxF
PC9jb21tYW5kPiwgZXhjZXB0IHRoYXQgb25seQogICBmaWVsZCBuYW1lcyBhbmQgdHlwZXMg
Y2FuIGJlIHNwZWNpZmllZDsgbm8gY29uc3RyYWludHMgKHN1Y2ggYXMgPGxpdGVyYWw+Tk9U
CiAgIE5VTEw8L2xpdGVyYWw+KSBjYW4gcHJlc2VudGx5IGJlIGluY2x1ZGVkLiAgTm90ZSB0
aGF0IHRoZSA8bGl0ZXJhbD5BUzwvbGl0ZXJhbD4ga2V5d29yZAotICBpcyBlc3NlbnRpYWw7
IHdpdGhvdXQgaXQsIHRoZSBzeXN0ZW0gd2lsbCB0aGluayBhIGRpZmZlcmVudCBraW5kCisg
IGlzIGVzc2VudGlhbDsgd2l0aG91dCBpdCwgdGhlIHN5c3RlbSB3aWxsIHRoaW5rIGEgPGxp
bmsKKyAgbGlua2VuZD0ic3FsLWNyZWF0ZXR5cGUtYmFzZSI+ZGlmZmVyZW50IGtpbmQ8L2xp
bms+CiAgIG9mIDxjb21tYW5kPkNSRUFURSBUWVBFPC9jb21tYW5kPiBjb21tYW5kIGlzIG1l
YW50LCBhbmQgeW91IHdpbGwgZ2V0IG9kZCBzeW50YXgKICAgZXJyb3JzLgogIDwvcGFyYT4K
LS0gCjIuNDMuMgoK
--------------F8JC7QyYNfct3qCjqttzYAuK
Content-Type: text/x-patch; charset=UTF-8;
 name="0002-composite-types-make-first-mention-of-CREATE-TABLE-a.patch"
Content-Disposition: attachment;
 filename*0="0002-composite-types-make-first-mention-of-CREATE-TABLE-a.pa";
 filename*1="tch"
Content-Transfer-Encoding: base64

RnJvbSAxOGJhN2UzYjcyMmQ3MDc0NDJiY2EyMjg4ZjEzMzhmNTgwM2YzOTZhIE1vbiBTZXAg
MTcgMDA6MDA6MDAgMjAwMQpGcm9tOiBBbnRvbiBWb2xvc2hpbiA8YS52b2xvc2hpbkBwb3N0
Z3Jlc3Byby5ydT4KRGF0ZTogRnJpLCAxMiBBcHIgMjAyNCAyMjo1NjoxOCArMDMwMApTdWJq
ZWN0OiBbUEFUQ0ggMi8zXSBjb21wb3NpdGUgdHlwZXM6IG1ha2UgZmlyc3QgbWVudGlvbiBv
ZiBDUkVBVEUgVEFCTEUgYQogbGluawoKLS0tCiBkb2Mvc3JjL3NnbWwvcm93dHlwZXMuc2dt
bCB8IDIgKy0KIDEgZmlsZSBjaGFuZ2VkLCAxIGluc2VydGlvbigrKSwgMSBkZWxldGlvbigt
KQoKZGlmZiAtLWdpdCBhL2RvYy9zcmMvc2dtbC9yb3d0eXBlcy5zZ21sIGIvZG9jL3NyYy9z
Z21sL3Jvd3R5cGVzLnNnbWwKaW5kZXggOWQ2NThhNzBjNDEuLmU2YWUyNmEwNDQ2IDEwMDY0
NAotLS0gYS9kb2Mvc3JjL3NnbWwvcm93dHlwZXMuc2dtbAorKysgYi9kb2Mvc3JjL3NnbWwv
cm93dHlwZXMuc2dtbApAQCAtMzYsNyArMzYsNyBAQCBDUkVBVEUgVFlQRSBpbnZlbnRvcnlf
aXRlbSBBUyAoCiAgICAgcHJpY2UgICAgICAgICAgIG51bWVyaWMKICk7CiA8L3Byb2dyYW1s
aXN0aW5nPgotICBUaGUgc3ludGF4IGlzIGNvbXBhcmFibGUgdG8gPGNvbW1hbmQ+Q1JFQVRF
IFRBQkxFPC9jb21tYW5kPiwgZXhjZXB0IHRoYXQgb25seQorICBUaGUgc3ludGF4IGlzIGNv
bXBhcmFibGUgdG8gPHhyZWYgbGlua2VuZD0ic3FsLWNyZWF0ZXRhYmxlIi8+LCBleGNlcHQg
dGhhdCBvbmx5CiAgIGZpZWxkIG5hbWVzIGFuZCB0eXBlcyBjYW4gYmUgc3BlY2lmaWVkOyBu
byBjb25zdHJhaW50cyAoc3VjaCBhcyA8bGl0ZXJhbD5OT1QKICAgTlVMTDwvbGl0ZXJhbD4p
IGNhbiBwcmVzZW50bHkgYmUgaW5jbHVkZWQuICBOb3RlIHRoYXQgdGhlIDxsaXRlcmFsPkFT
PC9saXRlcmFsPiBrZXl3b3JkCiAgIGlzIGVzc2VudGlhbDsgd2l0aG91dCBpdCwgdGhlIHN5
c3RlbSB3aWxsIHRoaW5rIGEgPGxpbmsKLS0gCjIuNDMuMgoK
--------------F8JC7QyYNfct3qCjqttzYAuK
Content-Type: text/x-patch; charset=UTF-8;
 name="0003-Composite-Types-simplify-CREATE-TABLE-example-to-mak.patch"
Content-Disposition: attachment;
 filename*0="0003-Composite-Types-simplify-CREATE-TABLE-example-to-mak.pa";
 filename*1="tch"
Content-Transfer-Encoding: base64

RnJvbSAzOGQ4ZGZjYTIyY2RiMThmYzVjOWM1MzhmYzA0MzMxNDFlOGQ4OWFiIE1vbiBTZXAg
MTcgMDA6MDA6MDAgMjAwMQpGcm9tOiBBbnRvbiBWb2xvc2hpbiA8YS52b2xvc2hpbkBwb3N0
Z3Jlc3Byby5ydT4KRGF0ZTogRnJpLCAxMiBBcHIgMjAyNCAyMjo1ODo0NSArMDMwMApTdWJq
ZWN0OiBbUEFUQ0ggMy8zXSBDb21wb3NpdGUgVHlwZXM6IHNpbXBsaWZ5IENSRUFURSBUQUJM
RSBleGFtcGxlIHRvIG1ha2UgaXQKIHNlbGYtc3VmZmljaWVudAoKLS0tCiBkb2Mvc3JjL3Nn
bWwvcm93dHlwZXMuc2dtbCB8IDIgKy0KIDEgZmlsZSBjaGFuZ2VkLCAxIGluc2VydGlvbigr
KSwgMSBkZWxldGlvbigtKQoKZGlmZiAtLWdpdCBhL2RvYy9zcmMvc2dtbC9yb3d0eXBlcy5z
Z21sIGIvZG9jL3NyYy9zZ21sL3Jvd3R5cGVzLnNnbWwKaW5kZXggZTZhZTI2YTA0NDYuLjcz
MmNjMmQ3YTZlIDEwMDY0NAotLS0gYS9kb2Mvc3JjL3NnbWwvcm93dHlwZXMuc2dtbAorKysg
Yi9kb2Mvc3JjL3NnbWwvcm93dHlwZXMuc2dtbApAQCAtNzUsNyArNzUsNyBAQCBTRUxFQ1Qg
cHJpY2VfZXh0ZW5zaW9uKGl0ZW0sIDEwKSBGUk9NIG9uX2hhbmQ7CiA8cHJvZ3JhbWxpc3Rp
bmc+CiBDUkVBVEUgVEFCTEUgaW52ZW50b3J5X2l0ZW0gKAogICAgIG5hbWUgICAgICAgICAg
ICB0ZXh0LAotICAgIHN1cHBsaWVyX2lkICAgICBpbnRlZ2VyIFJFRkVSRU5DRVMgc3VwcGxp
ZXJzLAorICAgIHN1cHBsaWVyX2lkICAgICBpbnRlZ2VyLAogICAgIHByaWNlICAgICAgICAg
ICBudW1lcmljIENIRUNLIChwcmljZSAmZ3Q7IDApCiApOwogPC9wcm9ncmFtbGlzdGluZz4K
LS0gCjIuNDMuMgoK

--------------F8JC7QyYNfct3qCjqttzYAuK--