public inbox for [email protected]help / color / mirror / Atom feed
Docs: Create table description for constraints markup fix and label tweaks 3+ messages / 2 participants [nested] [flat]
* Docs: Create table description for constraints markup fix and label tweaks @ 2026-04-03 17:18 David G. Johnston <[email protected]> 0 siblings, 1 reply; 3+ messages in thread From: David G. Johnston @ 2026-04-03 17:18 UTC (permalink / raw) To: PostgreSQL Hackers <[email protected]> Hi, Responding to a recent report on -general [1] I found a markup bug in the primary key description under create table. 0001 fixes this. The complaint itself was about using "column constraint" as a descriptive label in a syntax area when "column constraint" is an actual defined syntax label. 0002 adds the word "variant" to the six places "(table/column constraint)" is used in this manner. David J. [1] https://www.postgresql.org/message-id/[email protected]... Attachments: [application/octet-stream] v1-0002-pgsql-doc-Make-constraint-type-labels-not-match-s.patch (4.4K, 3-v1-0002-pgsql-doc-Make-constraint-type-labels-not-match-s.patch) download | inline diff: From 19bc06f6c8a21475f3ca01e9f7988ac0083caa21 Mon Sep 17 00:00:00 2001 From: "David G. Johnston" <[email protected]> Date: Fri, 3 Apr 2026 10:06:07 -0700 Subject: [PATCH v1 2/2] pgsql: doc: Make constraint type labels not match syntax verbiage In CREATE TABLE, unique, primary key, and foreign key indexes all have table and column variants. In the description the label used to identify the variant matched the label used in the syntax. Since the label appears in a syntax blub this could lead to confusion as reported. To fix, add the word 'variant' to the six labels. --- doc/src/sgml/ref/create_table.sgml | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/doc/src/sgml/ref/create_table.sgml b/doc/src/sgml/ref/create_table.sgml index 4c3808cdb45..83efc1f2b6c 100644 --- a/doc/src/sgml/ref/create_table.sgml +++ b/doc/src/sgml/ref/create_table.sgml @@ -1009,9 +1009,9 @@ WITH ( MODULUS <replaceable class="parameter">numeric_literal</replaceable>, REM </varlistentry> <varlistentry id="sql-createtable-parms-unique"> - <term><literal>UNIQUE [ NULLS [ NOT ] DISTINCT ]</literal> (column constraint)</term> + <term><literal>UNIQUE [ NULLS [ NOT ] DISTINCT ]</literal> (column constraint variant)</term> <term><literal>UNIQUE [ NULLS [ NOT ] DISTINCT ] ( <replaceable class="parameter">column_name</replaceable> [, ... ] [, <replaceable class="parameter">column_name</replaceable> WITHOUT OVERLAPS ] )</literal> - <optional> <literal>INCLUDE ( <replaceable class="parameter">column_name</replaceable> [, ...])</literal> </optional> (table constraint)</term> + <optional> <literal>INCLUDE ( <replaceable class="parameter">column_name</replaceable> [, ...])</literal> </optional> (table constraint variant)</term> <listitem> <para> @@ -1087,9 +1087,9 @@ WITH ( MODULUS <replaceable class="parameter">numeric_literal</replaceable>, REM </varlistentry> <varlistentry id="sql-createtable-parms-primary-key"> - <term><literal>PRIMARY KEY</literal> (column constraint)</term> + <term><literal>PRIMARY KEY</literal> (column constraint variant)</term> <term><literal>PRIMARY KEY ( <replaceable class="parameter">column_name</replaceable> [, ... ] [, <replaceable class="parameter">column_name</replaceable> WITHOUT OVERLAPS ] ) - <optional> INCLUDE ( <replaceable class="parameter">column_name</replaceable> [, ...])</optional></literal> (table constraint)</term> + <optional> INCLUDE ( <replaceable class="parameter">column_name</replaceable> [, ...])</optional></literal> (table constraint variant)</term> <listitem> <para> The <literal>PRIMARY KEY</literal> constraint specifies that a column or @@ -1203,14 +1203,14 @@ WITH ( MODULUS <replaceable class="parameter">numeric_literal</replaceable>, REM </varlistentry> <varlistentry id="sql-createtable-parms-references"> - <term><literal>REFERENCES <replaceable class="parameter">reftable</replaceable> [ ( <replaceable class="parameter">refcolumn</replaceable> ) ] [ MATCH <replaceable class="parameter">matchtype</replaceable> ] [ ON DELETE <replaceable class="parameter">referential_action</replaceable> ] [ ON UPDATE <replaceable class="parameter">referential_action</replaceable> ]</literal> (column constraint)</term> + <term><literal>REFERENCES <replaceable class="parameter">reftable</replaceable> [ ( <replaceable class="parameter">refcolumn</replaceable> ) ] [ MATCH <replaceable class="parameter">matchtype</replaceable> ] [ ON DELETE <replaceable class="parameter">referential_action</replaceable> ] [ ON UPDATE <replaceable class="parameter">referential_action</replaceable> ]</literal> (column constraint variant)</term> <term><literal>FOREIGN KEY ( <replaceable class="parameter">column_name</replaceable> [, ... ] [, PERIOD <replaceable class="parameter">column_name</replaceable> ] ) REFERENCES <replaceable class="parameter">reftable</replaceable> [ ( <replaceable class="parameter">refcolumn</replaceable> [, ... ] [, PERIOD <replaceable class="parameter">refcolumn</replaceable> ] ) ] [ MATCH <replaceable class="parameter">matchtype</replaceable> ] [ ON DELETE <replaceable class="parameter">referential_action</replaceable> ] [ ON UPDATE <replaceable class="parameter">referential_action</replaceable> ]</literal> - (table constraint)</term> + (table constraint variant)</term> <listitem> <para> -- 2.43.0 [application/octet-stream] v1-0001-pgsql-doc-Fix-malformed-sgml-element-nesting-for-.patch (1.7K, 4-v1-0001-pgsql-doc-Fix-malformed-sgml-element-nesting-for-.patch) download | inline diff: From 71309e81cd3a31bc953e178c80abc04ecaa035b2 Mon Sep 17 00:00:00 2001 From: "David G. Johnston" <[email protected]> Date: Fri, 3 Apr 2026 10:05:39 -0700 Subject: [PATCH v1 1/2] pgsql: doc: Fix malformed sgml element nesting for primary key In CREATE TABLE, the primary key description had malformed sgml element nesting. The INCLUDE clause was placed outside the enclosing literal element. Fix the two sgml markup issues. --- doc/src/sgml/ref/create_table.sgml | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/doc/src/sgml/ref/create_table.sgml b/doc/src/sgml/ref/create_table.sgml index 80829b23945..4c3808cdb45 100644 --- a/doc/src/sgml/ref/create_table.sgml +++ b/doc/src/sgml/ref/create_table.sgml @@ -1088,8 +1088,8 @@ WITH ( MODULUS <replaceable class="parameter">numeric_literal</replaceable>, REM <varlistentry id="sql-createtable-parms-primary-key"> <term><literal>PRIMARY KEY</literal> (column constraint)</term> - <term><literal>PRIMARY KEY ( <replaceable class="parameter">column_name</replaceable> [, ... ] [, <replaceable class="parameter">column_name</replaceable> WITHOUT OVERLAPS ] )</literal> - <optional> <literal>INCLUDE ( <replaceable class="parameter">column_name</replaceable> [, ...])</literal> </optional> (table constraint)</term> + <term><literal>PRIMARY KEY ( <replaceable class="parameter">column_name</replaceable> [, ... ] [, <replaceable class="parameter">column_name</replaceable> WITHOUT OVERLAPS ] ) + <optional> INCLUDE ( <replaceable class="parameter">column_name</replaceable> [, ...])</optional></literal> (table constraint)</term> <listitem> <para> The <literal>PRIMARY KEY</literal> constraint specifies that a column or -- 2.43.0 ^ permalink raw reply [nested|flat] 3+ messages in thread
* Re: Docs: Create table description for constraints markup fix and label tweaks @ 2026-04-03 17:57 David G. Johnston <[email protected]> parent: David G. Johnston <[email protected]> 0 siblings, 1 reply; 3+ messages in thread From: David G. Johnston @ 2026-04-03 17:57 UTC (permalink / raw) To: PostgreSQL Hackers <[email protected]> On Fri, Apr 3, 2026 at 10:18 AM David G. Johnston < [email protected]> wrote: > Responding to a recent report on -general [1] I found a markup bug in the > primary key description under create table. 0001 fixes this. > > The complaint itself was about using "column constraint" as a descriptive > label in a syntax area when "column constraint" is an actual defined syntax > label. 0002 adds the word "variant" to the six places "(table/column > constraint)" is used in this manner. > > [1] > https://www.postgresql.org/message-id/[email protected]... > > The more you look (not having production dark mode in the core build is a bit annoying)...v2 attached after re-reading the original thread and looking around a bit more. Unique had the same sgml markup error as primary key. Also, the CF entry: https://commitfest.postgresql.org/patch/6648/ David J. P.S. Reviewing this we are inconsistent as to where we use "optional" markup versus just literal [ ]. Even among these three locations there are variances - and simply literals used for optional meaning brackets. Attachments: [application/octet-stream] v2-0002-pgsql-doc-Make-constraint-type-labels-not-match-s.patch (4.4K, 3-v2-0002-pgsql-doc-Make-constraint-type-labels-not-match-s.patch) download | inline diff: From 376ff9c738d104bc20ddcbf94d4958873f3f8ea0 Mon Sep 17 00:00:00 2001 From: "David G. Johnston" <[email protected]> Date: Fri, 3 Apr 2026 10:28:41 -0700 Subject: [PATCH 2/2] pgsql: doc: Make constraint type labels not match syntax verbiage In CREATE TABLE, unique, primary key, and foreign key indexes all have table and column variants. In the description the label used to identify the variant matched the label used in the syntax. Since the label appears in a syntax blub this could lead to confusion as reported. To fix, add the word 'variant' to the six labels. --- doc/src/sgml/ref/create_table.sgml | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/doc/src/sgml/ref/create_table.sgml b/doc/src/sgml/ref/create_table.sgml index 943420663e2..907bd9b1acf 100644 --- a/doc/src/sgml/ref/create_table.sgml +++ b/doc/src/sgml/ref/create_table.sgml @@ -1009,9 +1009,9 @@ WITH ( MODULUS <replaceable class="parameter">numeric_literal</replaceable>, REM </varlistentry> <varlistentry id="sql-createtable-parms-unique"> - <term><literal>UNIQUE [ NULLS [ NOT ] DISTINCT ]</literal> (column constraint)</term> + <term><literal>UNIQUE [ NULLS [ NOT ] DISTINCT ]</literal> (column constraint variant)</term> <term><literal>UNIQUE [ NULLS [ NOT ] DISTINCT ] ( <replaceable class="parameter">column_name</replaceable> [, ... ] [, <replaceable class="parameter">column_name</replaceable> WITHOUT OVERLAPS ] ) - <optional> INCLUDE ( <replaceable class="parameter">column_name</replaceable> [, ...]) </optional></literal> (table constraint)</term> + <optional> INCLUDE ( <replaceable class="parameter">column_name</replaceable> [, ...]) </optional></literal> (table constraint variant)</term> <listitem> <para> @@ -1087,9 +1087,9 @@ WITH ( MODULUS <replaceable class="parameter">numeric_literal</replaceable>, REM </varlistentry> <varlistentry id="sql-createtable-parms-primary-key"> - <term><literal>PRIMARY KEY</literal> (column constraint)</term> + <term><literal>PRIMARY KEY</literal> (column constraint variant)</term> <term><literal>PRIMARY KEY ( <replaceable class="parameter">column_name</replaceable> [, ... ] [, <replaceable class="parameter">column_name</replaceable> WITHOUT OVERLAPS ] ) - <optional> INCLUDE ( <replaceable class="parameter">column_name</replaceable> [, ...]) </optional></literal> (table constraint)</term> + <optional> INCLUDE ( <replaceable class="parameter">column_name</replaceable> [, ...]) </optional></literal> (table constraint variant)</term> <listitem> <para> The <literal>PRIMARY KEY</literal> constraint specifies that a column or @@ -1203,14 +1203,14 @@ WITH ( MODULUS <replaceable class="parameter">numeric_literal</replaceable>, REM </varlistentry> <varlistentry id="sql-createtable-parms-references"> - <term><literal>REFERENCES <replaceable class="parameter">reftable</replaceable> [ ( <replaceable class="parameter">refcolumn</replaceable> ) ] [ MATCH <replaceable class="parameter">matchtype</replaceable> ] [ ON DELETE <replaceable class="parameter">referential_action</replaceable> ] [ ON UPDATE <replaceable class="parameter">referential_action</replaceable> ]</literal> (column constraint)</term> + <term><literal>REFERENCES <replaceable class="parameter">reftable</replaceable> [ ( <replaceable class="parameter">refcolumn</replaceable> ) ] [ MATCH <replaceable class="parameter">matchtype</replaceable> ] [ ON DELETE <replaceable class="parameter">referential_action</replaceable> ] [ ON UPDATE <replaceable class="parameter">referential_action</replaceable> ]</literal> (column constraint variant)</term> <term><literal>FOREIGN KEY ( <replaceable class="parameter">column_name</replaceable> [, ... ] [, PERIOD <replaceable class="parameter">column_name</replaceable> ] ) REFERENCES <replaceable class="parameter">reftable</replaceable> [ ( <replaceable class="parameter">refcolumn</replaceable> [, ... ] [, PERIOD <replaceable class="parameter">refcolumn</replaceable> ] ) ] [ MATCH <replaceable class="parameter">matchtype</replaceable> ] [ ON DELETE <replaceable class="parameter">referential_action</replaceable> ] [ ON UPDATE <replaceable class="parameter">referential_action</replaceable> ]</literal> - (table constraint)</term> + (table constraint variant)</term> <listitem> <para> -- 2.43.0 [application/octet-stream] v2-0001-pgsql-doc-Fix-malformed-sgml-element-nesting-for-.patch (2.7K, 4-v2-0001-pgsql-doc-Fix-malformed-sgml-element-nesting-for-.patch) download | inline diff: From 4613f027c27df4889c0a6973f0e45db2ae3a521f Mon Sep 17 00:00:00 2001 From: "David G. Johnston" <[email protected]> Date: Fri, 3 Apr 2026 10:28:31 -0700 Subject: [PATCH 1/2] pgsql: doc: Fix malformed sgml element nesting for unique and primary key In CREATE TABLE, the unique and primary key descriptions had malformed sgml element nesting. The INCLUDE clause was placed outside the enclosing literal element. Fix the four sgml markup issues. --- doc/src/sgml/ref/create_table.sgml | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/doc/src/sgml/ref/create_table.sgml b/doc/src/sgml/ref/create_table.sgml index 80829b23945..943420663e2 100644 --- a/doc/src/sgml/ref/create_table.sgml +++ b/doc/src/sgml/ref/create_table.sgml @@ -1010,8 +1010,8 @@ WITH ( MODULUS <replaceable class="parameter">numeric_literal</replaceable>, REM <varlistentry id="sql-createtable-parms-unique"> <term><literal>UNIQUE [ NULLS [ NOT ] DISTINCT ]</literal> (column constraint)</term> - <term><literal>UNIQUE [ NULLS [ NOT ] DISTINCT ] ( <replaceable class="parameter">column_name</replaceable> [, ... ] [, <replaceable class="parameter">column_name</replaceable> WITHOUT OVERLAPS ] )</literal> - <optional> <literal>INCLUDE ( <replaceable class="parameter">column_name</replaceable> [, ...])</literal> </optional> (table constraint)</term> + <term><literal>UNIQUE [ NULLS [ NOT ] DISTINCT ] ( <replaceable class="parameter">column_name</replaceable> [, ... ] [, <replaceable class="parameter">column_name</replaceable> WITHOUT OVERLAPS ] ) + <optional> INCLUDE ( <replaceable class="parameter">column_name</replaceable> [, ...]) </optional></literal> (table constraint)</term> <listitem> <para> @@ -1088,8 +1088,8 @@ WITH ( MODULUS <replaceable class="parameter">numeric_literal</replaceable>, REM <varlistentry id="sql-createtable-parms-primary-key"> <term><literal>PRIMARY KEY</literal> (column constraint)</term> - <term><literal>PRIMARY KEY ( <replaceable class="parameter">column_name</replaceable> [, ... ] [, <replaceable class="parameter">column_name</replaceable> WITHOUT OVERLAPS ] )</literal> - <optional> <literal>INCLUDE ( <replaceable class="parameter">column_name</replaceable> [, ...])</literal> </optional> (table constraint)</term> + <term><literal>PRIMARY KEY ( <replaceable class="parameter">column_name</replaceable> [, ... ] [, <replaceable class="parameter">column_name</replaceable> WITHOUT OVERLAPS ] ) + <optional> INCLUDE ( <replaceable class="parameter">column_name</replaceable> [, ...]) </optional></literal> (table constraint)</term> <listitem> <para> The <literal>PRIMARY KEY</literal> constraint specifies that a column or -- 2.43.0 ^ permalink raw reply [nested|flat] 3+ messages in thread
* Re: Docs: Create table description for constraints markup fix and label tweaks @ 2026-04-10 07:42 Dapeng Wang <[email protected]> parent: David G. Johnston <[email protected]> 0 siblings, 0 replies; 3+ messages in thread From: Dapeng Wang @ 2026-04-10 07:42 UTC (permalink / raw) To: David G. Johnston <[email protected]>; +Cc: PostgreSQL Hackers <[email protected]> Hi David, I reviewed both patches on the latest HEAD. 0001: SGML nesting fix applied and verified - make html builds successfully with the corrected element nesting for UNIQUE and PRIMARY KEY. 0002: The six "variant" label changes look good and should help avoid the confusion reported on -general. Looks good to me. Regards, Dapeng Wang David G. Johnston <[email protected]> 于2026年4月10日周五 15:04写道： > On Fri, Apr 3, 2026 at 10:18 AM David G. Johnston < > [email protected]> wrote: > >> Responding to a recent report on -general [1] I found a markup bug in the >> primary key description under create table. 0001 fixes this. >> >> The complaint itself was about using "column constraint" as a descriptive >> label in a syntax area when "column constraint" is an actual defined syntax >> label. 0002 adds the word "variant" to the six places "(table/column >> constraint)" is used in this manner. >> >> [1] >> https://www.postgresql.org/message-id/[email protected]... >> >> > The more you look (not having production dark mode in the core build is a > bit annoying)...v2 attached after re-reading the original thread and > looking around a bit more. > > Unique had the same sgml markup error as primary key. > > Also, the CF entry: https://commitfest.postgresql.org/patch/6648/ > > David J. > > P.S. Reviewing this we are inconsistent as to where we use "optional" > markup versus just literal [ ]. Even among these three locations there are > variances - and simply literals used for optional meaning brackets. > > ^ permalink raw reply [nested|flat] 3+ messages in thread
end of thread, other threads:[~2026-04-10 07:42 UTC | newest] Thread overview: 3+ messages (download: mbox mbox.gz follow: Atom feed) -- links below jump to the message on this page -- 2026-04-03 17:18 Docs: Create table description for constraints markup fix and label tweaks David G. Johnston <[email protected]> 2026-04-03 17:57 ` David G. Johnston <[email protected]> 2026-04-10 07:42 ` Dapeng Wang <[email protected]>
This inbox is served by agora; see mirroring instructions for how to clone and mirror all data and code used for this inbox