public inbox for [email protected]
help / color / mirror / Atom feedRe: Documentation weirdness
3+ messages / 3 participants
[nested] [flat]
* Re: Documentation weirdness
@ 2026-03-02 02:08 David G. Johnston <[email protected]>
2026-03-02 02:49 ` Re: Documentation weirdness Igor Korot <[email protected]>
2026-03-02 18:29 ` Re: Documentation weirdness Peter J. Holzer <[email protected]>
0 siblings, 2 replies; 3+ messages in thread
From: David G. Johnston @ 2026-03-02 02:08 UTC (permalink / raw)
To: Igor Korot <[email protected]>; +Cc: pgsql-generallists.postgresql.org <[email protected]>
On Sun, Mar 1, 2026 at 6:38 PM Igor Korot <[email protected]> wrote:
> Hi, ALL,
> I'm looking at
> https://www.postgresql.org/docs/current/sql-createtable.html
> and see some weird stuff.
>
> When I try to search for "PRIMARY KEY" I eventually hit following:
>
> [quote]
> PRIMARY KEY (column constraint)
> PRIMARY KEY ( column_name [, ... ] [, column_name WITHOUT OVERLAPS ] )
> [ INCLUDE ( column_name [, ...]) ] (table constraint)
> [/quote]
>
> Now I want to check what "column_constraint" is.
>
You read in an underscore in the parenthetical that isn't there. That
said, I concur that using a label here that so closely matches something
that exists within the page, to mean something else, is just asking for
this kind of confusion.
Looking at this, I did find a real sgml markup mistake. The highlighting
in dark mode makes it obvious since the whole "literal" should be shaded
differently but a couple of parts are not.
The diff below fixes the sgml problem by removing the inner <literal>
close/open pair and placing the <optional> closing element inside the
closing <literal> element.
I have also added the word "variant" to the two labels to make it clear
they are indeed two variants of the same thing (as described below) as
opposed to some kind of syntax element.
diff --git a/doc/src/sgml/ref/create_table.sgml
b/doc/src/sgml/ref/create_table.sgml
index 982532fe725..befadf1d696 100644
--- a/doc/src/sgml/ref/create_table.sgml
+++ b/doc/src/sgml/ref/create_table.sgml
@@ -1067,9 +1067,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 ( <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</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 variant)</term>
<listitem>
<para>
The <literal>PRIMARY KEY</literal> constraint specifies that a
column or
I'll forward this onto -hackers if no one decides to quickly handle it from
here.
David J.
^ permalink raw reply [nested|flat] 3+ messages in thread
* Re: Documentation weirdness
2026-03-02 02:08 Re: Documentation weirdness David G. Johnston <[email protected]>
@ 2026-03-02 02:49 ` Igor Korot <[email protected]>
1 sibling, 0 replies; 3+ messages in thread
From: Igor Korot @ 2026-03-02 02:49 UTC (permalink / raw)
To: David G. Johnston <[email protected]>; pgsql-generallists.postgresql.org <[email protected]>
Thx for the quick reply.
Agreed.
On Sun, Mar 1, 2026 at 8:09 PM David G. Johnston
<[email protected]> wrote:
>
> On Sun, Mar 1, 2026 at 6:38 PM Igor Korot <[email protected]> wrote:
>>
>> Hi, ALL,
>> I'm looking at https://www.postgresql.org/docs/current/sql-createtable.html
>> and see some weird stuff.
>>
>> When I try to search for "PRIMARY KEY" I eventually hit following:
>>
>> [quote]
>> PRIMARY KEY (column constraint)
>> PRIMARY KEY ( column_name [, ... ] [, column_name WITHOUT OVERLAPS ] )
>> [ INCLUDE ( column_name [, ...]) ] (table constraint)
>> [/quote]
>>
>> Now I want to check what "column_constraint" is.
>
>
> You read in an underscore in the parenthetical that isn't there. That said, I concur that using a label here that so closely matches something that exists within the page, to mean something else, is just asking for this kind of confusion.
>
> Looking at this, I did find a real sgml markup mistake. The highlighting in dark mode makes it obvious since the whole "literal" should be shaded differently but a couple of parts are not.
>
> The diff below fixes the sgml problem by removing the inner <literal> close/open pair and placing the <optional> closing element inside the closing <literal> element.
>
> I have also added the word "variant" to the two labels to make it clear they are indeed two variants of the same thing (as described below) as opposed to some kind of syntax element.
>
>
> diff --git a/doc/src/sgml/ref/create_table.sgml b/doc/src/sgml/ref/create_table.sgml
> index 982532fe725..befadf1d696 100644
> --- a/doc/src/sgml/ref/create_table.sgml
> +++ b/doc/src/sgml/ref/create_table.sgml
> @@ -1067,9 +1067,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 ( <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</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 variant)</term>
> <listitem>
> <para>
> The <literal>PRIMARY KEY</literal> constraint specifies that a column or
>
> I'll forward this onto -hackers if no one decides to quickly handle it from here.
>
> David J.
>
>
^ permalink raw reply [nested|flat] 3+ messages in thread
* Re: Documentation weirdness
2026-03-02 02:08 Re: Documentation weirdness David G. Johnston <[email protected]>
@ 2026-03-02 18:29 ` Peter J. Holzer <[email protected]>
1 sibling, 0 replies; 3+ messages in thread
From: Peter J. Holzer @ 2026-03-02 18:29 UTC (permalink / raw)
To: [email protected]
On 2026-03-01 19:08:48 -0700, David G. Johnston wrote:
> On Sun, Mar 1, 2026 at 6:38 PM Igor Korot <[email protected]> wrote:
>
> Hi, ALL,
> I'm looking at https://www.postgresql.org/docs/current/sql-createtable.html
> and see some weird stuff.
>
> When I try to search for "PRIMARY KEY" I eventually hit following:
>
> [quote]
> PRIMARY KEY (column constraint)
> PRIMARY KEY ( column_name [, ... ] [, column_name WITHOUT OVERLAPS ] )
> [ INCLUDE ( column_name [, ...]) ] (table constraint)
> [/quote]
>
> Now I want to check what "column_constraint" is.
>
>
> You read in an underscore in the parenthetical that isn't there. That said, I
> concur that using a label here that so closely matches something that exists
> within the page, to mean something else, is just asking for this kind of
> confusion.
Would it be possible to set (column constraint) and (table constraint)
in the normal body font instead of monospace? That would make it clearer
that these phrases aren't part of the syntax but descriptive.
hjp
--
_ | Peter J. Holzer | Story must make more sense than reality.
|_|_) | |
| | | [email protected] | -- Charles Stross, "Creative writing
__/ | http://www.hjp.at/ | challenge!"
Attachments:
[application/pgp-signature] signature.asc (833B, 2-signature.asc)
download
^ permalink raw reply [nested|flat] 3+ messages in thread
end of thread, other threads:[~2026-03-02 18:29 UTC | newest]
Thread overview: 3+ messages (download: mbox.gz follow: Atom feed)
-- links below jump to the message on this page --
2026-03-02 02:08 Re: Documentation weirdness David G. Johnston <[email protected]>
2026-03-02 02:49 ` Igor Korot <[email protected]>
2026-03-02 18:29 ` Peter J. Holzer <[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