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. > >
