public inbox for [email protected]
help / color / mirror / Atom feedFrom: David G. Johnston <[email protected]>
To: PostgreSQL Hackers <[email protected]>
Subject: Re: Docs: Create table description for constraints markup fix and label tweaks
Date: Fri, 3 Apr 2026 10:57:27 -0700
Message-ID: <CAKFQuwYda2RwHdzwbz3FcMs_2kaKn7skpuPzAd15h5DH1LfzQg@mail.gmail.com> (raw)
In-Reply-To: <CAKFQuwbsGWx5msYbRsWrRs+ss1k0utDHEhVq5unAKODQ9YOf9w@mail.gmail.com>
References: <CAKFQuwbsGWx5msYbRsWrRs+ss1k0utDHEhVq5unAKODQ9YOf9w@mail.gmail.com>
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
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: <CAKFQuwYda2RwHdzwbz3FcMs_2kaKn7skpuPzAd15h5DH1LfzQg@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