MIME-Version: 1.0
References: <CA+FnnTzeE30E4kfK4=+MLe4DBORu4CdYvPQgWUYakRxfwsbEtg@mail.gmail.com>
 <CAKFQuwbefYYr-e=jS6gLJbdo9nG47_tS-inbsCCFEFYpxV+U2w@mail.gmail.com>
In-Reply-To: <CAKFQuwbefYYr-e=jS6gLJbdo9nG47_tS-inbsCCFEFYpxV+U2w@mail.gmail.com>
From: Igor Korot <ikorot01@gmail.com>
Date: Sun, 1 Mar 2026 20:49:09 -0600
Message-ID: <CA+FnnTxY=bMEUDtW=LVXS1TO+O-5KA5EfSSfC+=kC3UEDWTVyw@mail.gmail.com>
Subject: Re: Documentation weirdness
To: "David G. Johnston" <david.g.johnston@gmail.com>, 
	"pgsql-generallists.postgresql.org" <pgsql-general@lists.postgresql.org>
Content-Type: text/plain; charset="UTF-8"
Content-Transfer-Encoding: quoted-printable
Archived-At: <https://www.postgresql.org/message-id/CA%2BFnnTxY%3DbMEUDtW%3DLVXS1TO%2BO-5KA5EfSSfC%2B%3DkC3UEDWTVyw%40mail.gmail.com>
Precedence: bulk

Thx for the quick reply.

Agreed.

On Sun, Mar 1, 2026 at 8:09=E2=80=AFPM David G. Johnston
<david.g.johnston@gmail.com> wrote:
>
> On Sun, Mar 1, 2026 at 6:38=E2=80=AFPM Igor Korot <ikorot01@gmail.com> wr=
ote:
>>
>> Hi, ALL,
>> I'm looking at https://www.postgresql.org/docs/current/sql-createtable.h=
tml
>> 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 sa=
id, 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 ki=
nd 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 d=
ifferently but a couple of parts are not.
>
> The diff below fixes the sgml problem by removing the inner <literal> clo=
se/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 t=
hey are indeed two variants of the same thing (as described below) as oppos=
ed 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=3D"parameter">num=
eric_literal</replaceable>, REM
>     </varlistentry>
>
>     <varlistentry id=3D"sql-createtable-parms-primary-key">
> -    <term><literal>PRIMARY KEY</literal> (column constraint)</term>
> -    <term><literal>PRIMARY KEY ( <replaceable class=3D"parameter">column=
_name</replaceable> [, ... ] [, <replaceable class=3D"parameter">column_nam=
e</replaceable> WITHOUT OVERLAPS ] )</literal>
> -    <optional> <literal>INCLUDE ( <replaceable class=3D"parameter">colum=
n_name</replaceable> [, ...])</literal> </optional> (table constraint)</ter=
m>
> +    <term><literal>PRIMARY KEY</literal> (column constraint variant)</te=
rm>
> +    <term><literal>PRIMARY KEY ( <replaceable class=3D"parameter">column=
_name</replaceable> [, ... ] [, <replaceable class=3D"parameter">column_nam=
e</replaceable> WITHOUT OVERLAPS ] )
> +    <optional> INCLUDE ( <replaceable class=3D"parameter">column_name</r=
eplaceable> [, ...])</optional></literal> (table constraint variant)</term>
>      <listitem>
>       <para>
>        The <literal>PRIMARY KEY</literal> constraint specifies that a col=
umn or
>
> I'll forward this onto -hackers if no one decides to quickly handle it fr=
om here.
>
> David J.
>
>