pg.ddx.io pgsql-docs@postgresql.org mailing list archive
help / color / mirror / Atom feedthree small improvements for "Composite Types" page
3+ messages / 2 participants
[nested] [flat]
* three small improvements for "Composite Types" page
@ 2024-04-12 20:20 Anton Voloshin <a.voloshin@postgrespro.ru>
0 siblings, 1 reply; 3+ messages in thread
From: Anton Voloshin @ 2024-04-12 20:20 UTC (permalink / raw)
To: pgsql-docs <pgsql-docs@lists.postgresql.org>
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
Attachments:
[text/x-patch] 0001-clarify-different-kind-by-adding-a-link-to-a-section.patch (1.5K, ../../38aa8e65-32e2-4578-bfc8-0d9f59efe049@postgrespro.ru/2-0001-clarify-different-kind-by-adding-a-link-to-a-section.patch)
download | inline diff:
From df2a1b5cb323d639bcf75fac6799b89b40dec972 Mon Sep 17 00:00:00 2001
From: Anton Voloshin <a.voloshin@postgrespro.ru>
Date: Fri, 12 Apr 2024 22:49:17 +0300
Subject: [PATCH 1/3] clarify "different kind" by adding a link to a section of
"create type" page
---
doc/src/sgml/ref/create_type.sgml | 2 +-
doc/src/sgml/rowtypes.sgml | 3 ++-
2 files changed, 3 insertions(+), 2 deletions(-)
diff --git a/doc/src/sgml/ref/create_type.sgml b/doc/src/sgml/ref/create_type.sgml
index 994dfc65268..b975531864b 100644
--- a/doc/src/sgml/ref/create_type.sgml
+++ b/doc/src/sgml/ref/create_type.sgml
@@ -188,7 +188,7 @@ CREATE TYPE <replaceable class="parameter">name</replaceable>
</para>
</refsect2>
- <refsect2>
+ <refsect2 id="sql-createtype-base">
<title>Base Types</title>
<para>
diff --git a/doc/src/sgml/rowtypes.sgml b/doc/src/sgml/rowtypes.sgml
index bbeac84d46a..9d658a70c41 100644
--- a/doc/src/sgml/rowtypes.sgml
+++ b/doc/src/sgml/rowtypes.sgml
@@ -39,7 +39,8 @@ CREATE TYPE inventory_item AS (
The syntax is comparable to <command>CREATE TABLE</command>, except that only
field names and types can be specified; no constraints (such as <literal>NOT
NULL</literal>) can presently be included. Note that the <literal>AS</literal> keyword
- is essential; without it, the system will think a different kind
+ is essential; without it, the system will think a <link
+ linkend="sql-createtype-base">different kind</link>
of <command>CREATE TYPE</command> command is meant, and you will get odd syntax
errors.
</para>
--
2.43.2
[text/x-patch] 0002-composite-types-make-first-mention-of-CREATE-TABLE-a.patch (1008B, ../../38aa8e65-32e2-4578-bfc8-0d9f59efe049@postgrespro.ru/3-0002-composite-types-make-first-mention-of-CREATE-TABLE-a.patch)
download | inline diff:
From 18ba7e3b722d707442bca2288f1338f5803f396a Mon Sep 17 00:00:00 2001
From: Anton Voloshin <a.voloshin@postgrespro.ru>
Date: Fri, 12 Apr 2024 22:56:18 +0300
Subject: [PATCH 2/3] composite types: make first mention of CREATE TABLE a
link
---
doc/src/sgml/rowtypes.sgml | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
diff --git a/doc/src/sgml/rowtypes.sgml b/doc/src/sgml/rowtypes.sgml
index 9d658a70c41..e6ae26a0446 100644
--- a/doc/src/sgml/rowtypes.sgml
+++ b/doc/src/sgml/rowtypes.sgml
@@ -36,7 +36,7 @@ CREATE TYPE inventory_item AS (
price numeric
);
</programlisting>
- The syntax is comparable to <command>CREATE TABLE</command>, except that only
+ The syntax is comparable to <xref linkend="sql-createtable"/>, except that only
field names and types can be specified; no constraints (such as <literal>NOT
NULL</literal>) can presently be included. Note that the <literal>AS</literal> keyword
is essential; without it, the system will think a <link
--
2.43.2
[text/x-patch] 0003-Composite-Types-simplify-CREATE-TABLE-example-to-mak.patch (822B, ../../38aa8e65-32e2-4578-bfc8-0d9f59efe049@postgrespro.ru/4-0003-Composite-Types-simplify-CREATE-TABLE-example-to-mak.patch)
download | inline diff:
From 38d8dfca22cdb18fc5c9c538fc0433141e8d89ab Mon Sep 17 00:00:00 2001
From: Anton Voloshin <a.voloshin@postgrespro.ru>
Date: Fri, 12 Apr 2024 22:58:45 +0300
Subject: [PATCH 3/3] Composite Types: simplify CREATE TABLE example to make it
self-sufficient
---
doc/src/sgml/rowtypes.sgml | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
diff --git a/doc/src/sgml/rowtypes.sgml b/doc/src/sgml/rowtypes.sgml
index e6ae26a0446..732cc2d7a6e 100644
--- a/doc/src/sgml/rowtypes.sgml
+++ b/doc/src/sgml/rowtypes.sgml
@@ -75,7 +75,7 @@ SELECT price_extension(item, 10) FROM on_hand;
<programlisting>
CREATE TABLE inventory_item (
name text,
- supplier_id integer REFERENCES suppliers,
+ supplier_id integer,
price numeric CHECK (price > 0)
);
</programlisting>
--
2.43.2
^ permalink raw reply [nested|flat] 3+ messages in thread
* Re: three small improvements for "Composite Types" page
@ 2024-04-12 20:44 David G. Johnston <david.g.johnston@gmail.com>
parent: Anton Voloshin <a.voloshin@postgrespro.ru>
0 siblings, 1 reply; 3+ messages in thread
From: David G. Johnston @ 2024-04-12 20:44 UTC (permalink / raw)
To: Anton Voloshin <a.voloshin@postgrespro.ru>; +Cc: pgsql-docs <pgsql-docs@lists.postgresql.org>
On Fri, Apr 12, 2024 at 1:20 PM Anton Voloshin <a.voloshin@postgrespro.ru>
wrote:
> 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.
>
I'd much prefer to leave "different kind" alone and turn the immediately
following, first-on-the-page, instance of CREATE TYPE into a link.
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.
>
I'm not all that convinced of that particular usefulness but also don't see
it hurting either.
> 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.
Agreed.
David J.
^ permalink raw reply [nested|flat] 3+ messages in thread
* Re: three small improvements for "Composite Types" page
@ 2024-04-16 08:48 Anton Voloshin <a.voloshin@postgrespro.ru>
parent: David G. Johnston <david.g.johnston@gmail.com>
0 siblings, 0 replies; 3+ messages in thread
From: Anton Voloshin @ 2024-04-16 08:48 UTC (permalink / raw)
To: David G. Johnston <david.g.johnston@gmail.com>; +Cc: pgsql-docs <pgsql-docs@lists.postgresql.org>
On 12/04/2024 23:44, David G. Johnston wrote:
> I'd much prefer to leave "different kind" alone and turn the immediately
> following, first-on-the-page, instance of CREATE TYPE into a link.
Good, I'm fine with that too.
> 2. make first mention of CREATE TABLE a link
> [...] > I'm not all that convinced of that particular usefulness but also don't
> see it hurting either.
Thanks. I do think it's useful when one reads this page separately (not
as a part of sequential read-through).
> 3. Simplify CREATE TABLE example to make it self-sufficient
> [...]
> Agreed.
Thanks. I've updated the patches correspondingly.
--
Anton Voloshin
Postgres Professional, The Russian Postgres Company
https://postgrespro.ru
Attachments:
[text/x-patch] 0001-Composite-Types-clarify-different-kind-by-linking-to.patch (1010B, ../../5fcda2fa-fb49-41f2-a5e5-c3100937b0a4@postgrespro.ru/2-0001-Composite-Types-clarify-different-kind-by-linking-to.patch)
download | inline diff:
From dddf7ee4a9a22515c327434b7db2c0293301b257 Mon Sep 17 00:00:00 2001
From: Anton Voloshin <a.voloshin@postgrespro.ru>
Date: Fri, 12 Apr 2024 22:49:17 +0300
Subject: [PATCH 1/3] Composite Types: clarify "different kind" by linking to a
"create type" page
---
doc/src/sgml/rowtypes.sgml | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
diff --git a/doc/src/sgml/rowtypes.sgml b/doc/src/sgml/rowtypes.sgml
index bbeac84d46a..049e90e9c68 100644
--- a/doc/src/sgml/rowtypes.sgml
+++ b/doc/src/sgml/rowtypes.sgml
@@ -40,7 +40,7 @@ CREATE TYPE inventory_item AS (
field names and types can be specified; no constraints (such as <literal>NOT
NULL</literal>) can presently be included. Note that the <literal>AS</literal> keyword
is essential; without it, the system will think a different kind
- of <command>CREATE TYPE</command> command is meant, and you will get odd syntax
+ of <xref linkend="sql-createtype"/> command is meant, and you will get odd syntax
errors.
</para>
--
2.43.2
[text/x-patch] 0002-Composite-Types-make-first-mention-of-CREATE-TABLE-a.patch (1017B, ../../5fcda2fa-fb49-41f2-a5e5-c3100937b0a4@postgrespro.ru/3-0002-Composite-Types-make-first-mention-of-CREATE-TABLE-a.patch)
download | inline diff:
From def3f7ccb55b44e63b2a9fffa88ba4d3c545e553 Mon Sep 17 00:00:00 2001
From: Anton Voloshin <a.voloshin@postgrespro.ru>
Date: Fri, 12 Apr 2024 22:56:18 +0300
Subject: [PATCH 2/3] Composite Types: make first mention of CREATE TABLE a
link
---
doc/src/sgml/rowtypes.sgml | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
diff --git a/doc/src/sgml/rowtypes.sgml b/doc/src/sgml/rowtypes.sgml
index 049e90e9c68..a409b292795 100644
--- a/doc/src/sgml/rowtypes.sgml
+++ b/doc/src/sgml/rowtypes.sgml
@@ -36,7 +36,7 @@ CREATE TYPE inventory_item AS (
price numeric
);
</programlisting>
- The syntax is comparable to <command>CREATE TABLE</command>, except that only
+ The syntax is comparable to <xref linkend="sql-createtable"/>, except that only
field names and types can be specified; no constraints (such as <literal>NOT
NULL</literal>) can presently be included. Note that the <literal>AS</literal> keyword
is essential; without it, the system will think a different kind
--
2.43.2
[text/x-patch] 0003-Composite-Types-simplify-CREATE-TABLE-example-to-mak.patch (822B, ../../5fcda2fa-fb49-41f2-a5e5-c3100937b0a4@postgrespro.ru/4-0003-Composite-Types-simplify-CREATE-TABLE-example-to-mak.patch)
download | inline diff:
From bbda6a20a387cd6b1379b760de0e215851e638a9 Mon Sep 17 00:00:00 2001
From: Anton Voloshin <a.voloshin@postgrespro.ru>
Date: Fri, 12 Apr 2024 22:58:45 +0300
Subject: [PATCH 3/3] Composite Types: simplify CREATE TABLE example to make it
self-sufficient
---
doc/src/sgml/rowtypes.sgml | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
diff --git a/doc/src/sgml/rowtypes.sgml b/doc/src/sgml/rowtypes.sgml
index a409b292795..b6063b30c31 100644
--- a/doc/src/sgml/rowtypes.sgml
+++ b/doc/src/sgml/rowtypes.sgml
@@ -74,7 +74,7 @@ SELECT price_extension(item, 10) FROM on_hand;
<programlisting>
CREATE TABLE inventory_item (
name text,
- supplier_id integer REFERENCES suppliers,
+ supplier_id integer,
price numeric CHECK (price > 0)
);
</programlisting>
--
2.43.2
^ permalink raw reply [nested|flat] 3+ messages in thread
end of thread, other threads:[~2024-04-16 08:48 UTC | newest]
Thread overview: 3+ messages (download: mbox mbox.gz follow: Atom feed)
-- links below jump to the message on this page --
2024-04-12 20:20 three small improvements for "Composite Types" page Anton Voloshin <a.voloshin@postgrespro.ru>
2024-04-12 20:44 ` David G. Johnston <david.g.johnston@gmail.com>
2024-04-16 08:48 ` Anton Voloshin <a.voloshin@postgrespro.ru>
This inbox is served by DDX for PostgreSQL; see mirroring instructions
for how to clone and mirror all data and code used for this inbox