public inbox for [email protected]
help / color / mirror / Atom feedFrom: David G. Johnston <[email protected]>
To: PostgreSQL Hackers <[email protected]>
Subject: Docs: Create table description for constraints markup fix and label tweaks
Date: Fri, 3 Apr 2026 10:18:41 -0700
Message-ID: <CAKFQuwbsGWx5msYbRsWrRs+ss1k0utDHEhVq5unAKODQ9YOf9w@mail.gmail.com> (raw)
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
view thread (3+ messages) latest in thread
reply
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Reply to all the recipients using the --to and --cc options:
reply via email
To: [email protected]
Cc: [email protected], [email protected]
Subject: Re: Docs: Create table description for constraints markup fix and label tweaks
In-Reply-To: <CAKFQuwbsGWx5msYbRsWrRs+ss1k0utDHEhVq5unAKODQ9YOf9w@mail.gmail.com>
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
This inbox is served by agora; see mirroring instructions
for how to clone and mirror all data and code used for this inbox