Received: from malur.postgresql.org ([217.196.149.56]) by arkaria.postgresql.org with esmtps (TLS1.3) tls TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384 (Exim 4.96) (envelope-from ) id 1vwsiw-001ZKZ-1R for pgsql-general@arkaria.postgresql.org; Mon, 02 Mar 2026 02:09:30 +0000 Received: from localhost ([127.0.0.1] helo=malur.postgresql.org) by malur.postgresql.org with esmtp (Exim 4.96) (envelope-from ) id 1vwsiv-00Eiy6-1I for pgsql-general@arkaria.postgresql.org; Mon, 02 Mar 2026 02:09:29 +0000 Received: from magus.postgresql.org ([2a02:c0:301:0:ffff::29]) by malur.postgresql.org with esmtps (TLS1.3) tls TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384 (Exim 4.96) (envelope-from ) id 1vwsiv-00Eixy-09 for pgsql-general@lists.postgresql.org; Mon, 02 Mar 2026 02:09:29 +0000 Received: from mail-oi1-x22e.google.com ([2607:f8b0:4864:20::22e]) by magus.postgresql.org with esmtps (TLS1.3) tls TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256 (Exim 4.98.2) (envelope-from ) id 1vwsir-00000001xAa-3EBn for pgsql-general@lists.postgresql.org; Mon, 02 Mar 2026 02:09:28 +0000 Received: by mail-oi1-x22e.google.com with SMTP id 5614622812f47-46391e91e16so2811387b6e.3 for ; Sun, 01 Mar 2026 18:09:26 -0800 (PST) ARC-Seal: i=1; a=rsa-sha256; t=1772417364; cv=none; d=google.com; s=arc-20240605; b=bTF90kzUjbF6NCA1SqhCkwRN2lAZfcRxUAwqBYh9lEyFXN5IUeykF4WFy1SxCxybHU B5FxOB+QRNP9BWTG7gsdySdywNLREfWaXgJN2YkqRK1dP6JO2kSBfDtRbQ0MDf7sIB0y ELVVstU+JY8ViqoLn03YaTGdcM/bCWfu1rT6sa4dOgST0Bu4d9dFGwGEyBbJowCPs1ch 93INK/5LC0rmUVnEXoYkJV2WIsJjmprldPB9Sfz+gY+RhLbJfKp5GDyptZNyHobLbmGT VFZ9bxf2qrEZuLqLV6ug1UamGycaoSyTcEIVsGv7aoboUdKvE5kaXEvemIYJGgI/cGk4 ta8Q== ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=google.com; s=arc-20240605; h=cc:to:subject:message-id:date:from:in-reply-to:references :mime-version:dkim-signature; bh=+zYbLMmrJjDc3ZKHtVFXHuYUEA3TTdKm7HKIcFMS3vw=; fh=MqX3/PjeIRWyveucHIwmT3MEzIvphFWgoM5FEnVDTkI=; b=d4gJPmBmebq7qvF9anWTuQGBO8pdVJR60mvMYYV36kIljzDC9gaXUQu4CTIUBWOc06 TyrY9H0reCQkEK47k6aSPdKyAmYR4J7/6H4Ed/0JodBwr6d/hefZb0YATRa+U+0otzi4 1L9UNBveGf7fI9gxUXzOnyHg7QXaQx5xrnFiR6lRwRuqqppMVqoaZM0EaLCOGkNot5BN Q2yk4h4x4LDvdp2vTL4bhm0bhbGtW/7Q9Q/FSUAV7AxlteClEk8fsloPlVzCvNdUiu5M pqxoYs7b9/a6q+IgMq/oCcocYyj2TKuPejeGE20Mg+K4/yHmGfjDc6Y0dGjlfpXJHLQN VVgg==; darn=lists.postgresql.org ARC-Authentication-Results: i=1; mx.google.com; arc=none DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20230601; t=1772417364; x=1773022164; darn=lists.postgresql.org; h=cc:to:subject:message-id:date:from:in-reply-to:references :mime-version:from:to:cc:subject:date:message-id:reply-to; bh=+zYbLMmrJjDc3ZKHtVFXHuYUEA3TTdKm7HKIcFMS3vw=; b=gEmVk1TvGssPjczsVGsWHbG2hr/oWHLShZaGq4CWG6RWKWNa7PXW7+CbGoLJbHOai/ 2e4kyUPLHStwZ3PsBvLexrbprNNFPE/NSdrceREa1RsFgRZP67jNNK46uLM411MhHgw+ fCsb8KKnbUbzL7lrp0LscfQCa7P34gPcZPLE3UdVjIUeS39hRMxeVnS0S07CVr8q+S/p t9dR7D2FqAjhHvkktKCcLcFp2NEDZXDU9GJoGwTXCHbaYALroCFyGFMm/Cu0GYzQQo/P pi3MbVAU4OFSzgAOdZNqAt5fwGkV/cVB5gB+IUyIwVKvqPycHXKtvlHMOs7GM97wv7vG 7ssw== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20230601; t=1772417364; x=1773022164; h=cc:to:subject:message-id:date:from:in-reply-to:references :mime-version:x-gm-gg:x-gm-message-state:from:to:cc:subject:date :message-id:reply-to; bh=+zYbLMmrJjDc3ZKHtVFXHuYUEA3TTdKm7HKIcFMS3vw=; b=jl3mzuGk8SO3i3TWK3dWTWNVaGUHLck/UlzpnLAvR1SMV3eXcy/Lf/9NuwpkgPRZ7F QbEd2ijjahfiA86EmDdXL3hfqoikIeVdrM5toP7Bv8WbJYzq5a+8JJ+nV61FraWG1MRu XDelVvVAE/Eb/R7m0xMdWKMGIcIwwB9L6LQdWDyUE5tQVbjGy0sthMenJ5BN/AJyCp60 UR8hrw0QJ5n+7aWpOa74YSLRSH87aikSZjqaL9BP4AzSe7ePgLHlvTIBqpXzLCza8/kf fo8f+aIy/iCLVDqzguT/16BlFHVcmfbaFUFfU3t4vsQGYB2+vUUkOYzQju0M8p2bn0u6 8ACA== X-Gm-Message-State: AOJu0Yy6IyXRg+I/fs4c6BI7dqxYMnGeQw6L+vbW+myM2BGwUhMrSsem 3gtKKd9vP0G3KeS6EvpapPy3AnkenOYFDrSfsi8yqlK6J2whN7Bt4AQbMMQ/kTIt4VHW0iM7xlh VjsVNPTR4WfrgUsUgOMxIOnw02Tpv/SP3cTfRblQ= X-Gm-Gg: ATEYQzwOPA/ogOhv+ReTdwFArkX/gFzGcE5KJbNgaBsIb9lss1qcWs+rbWtb7OhCxBC 3KQSrtS8TvqOddXTgOYXaMCnEuXOYmCEB5ByQ7Ysz7+sJJO4qlIxmnqA30Z4+vLhyhPD1HRk06x 28dWTDe3eLkSlX3oIbcL5eYrH1XCsGi4WN8CIyHbX/Jjo7g96U69OMgCpdxRF0P05wxuTBPzLP6 hUesTf6qkgRlRBXygx4pm2v55FZAIwCaLazl3rj4eDN8RJ3A1QPBsoi39Ojo5wj0aAPaoI3wc2Q mirGF3X/6PKHt77+5A== X-Received: by 2002:a05:6808:2814:b0:463:94f6:681b with SMTP id 5614622812f47-464beeffbc2mr4500232b6e.34.1772417364368; Sun, 01 Mar 2026 18:09:24 -0800 (PST) MIME-Version: 1.0 References: In-Reply-To: From: "David G. Johnston" Date: Sun, 1 Mar 2026 19:08:48 -0700 X-Gm-Features: AaiRm50_YyvD7Y0znZpfmSUZ4Gc5F7lshnl_8kVkmzD48P_srIOJb4P_5n18hG4 Message-ID: Subject: Re: Documentation weirdness To: Igor Korot Cc: "pgsql-generallists.postgresql.org" Content-Type: multipart/alternative; boundary="00000000000065a1fc064c01131a" List-Id: List-Help: List-Subscribe: List-Post: List-Owner: List-Archive: Archived-At: Precedence: bulk --00000000000065a1fc064c01131a Content-Type: text/plain; charset="UTF-8" Content-Transfer-Encoding: quoted-printable On Sun, Mar 1, 2026 at 6:38=E2=80=AFPM Igor Korot wrot= e: > 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 close/open pair and placing the closing element inside the closing 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 numeric_literal, REM - PRIMARY KEY (column constraint) - PRIMARY KEY ( column_name [, ... ] [, column_name WITHOUT OVERLAPS ] ) - INCLUDE ( column_name [, ...]) (table constraint) + PRIMARY KEY (column constraint variant) + PRIMARY KEY ( column_name [, ... ] [, column_name WITHOUT OVERLAPS ] ) + INCLUDE ( column_name [, ...]) (table constraint variant) The PRIMARY KEY constraint specifies that a column or I'll forward this onto -hackers if no one decides to quickly handle it from here. David J. --00000000000065a1fc064c01131a Content-Type: text/html; charset="UTF-8" Content-Transfer-Encoding: quoted-printable
On Sun, Mar 1, 2026 at 6:38=E2=80=AFPM Igor Korot <ikorot01@gmail.com> wrote:<= /div>
Hi, ALL,
I'm looking at https://www.postgresq= l.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&#= 39;t there.=C2=A0 That said, I concur that using a label here that so close= ly matches something that exists within the page, to mean something else, i= s just asking for this kind of confusion.

Looking at t= his, I did find a real sgml markup mistake.=C2=A0 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 be= low fixes the sgml problem by removing the inner <literal> close/open= pair and placing the <optional> closing element inside the closing &= lt;literal> element.

I have also added the word &qu= ot;variant" to the two labels to make it clear they are indeed two var= iants of the same thing (as described below) as opposed to some kind of syn= tax element.


diff --git a/doc/src/sgm= l/ref/create_table.sgml b/doc/src/sgml/ref/create_table.sgml
index 98253= 2fe725..befadf1d696 100644
--- a/doc/src/sgml/ref/create_table.sgml
+= ++ b/doc/src/sgml/ref/create_table.sgml
@@ -1067,9 +1067,9 @@ WITH ( MOD= ULUS <replaceable class=3D"parameter">numeric_literal</r= eplaceable>, REM
=C2=A0 =C2=A0 </varlistentry>
=C2=A0
=C2= =A0 =C2=A0 <varlistentry id=3D"sql-createtable-parms-primary-key&qu= ot;>
- =C2=A0 =C2=A0<term><literal>PRIMARY KEY</litera= l> (column constraint)</term>
- =C2=A0 =C2=A0<term><li= teral>PRIMARY KEY ( <replaceable class=3D"parameter">col= umn_name</replaceable> [, ... ] [, <replaceable class=3D"para= meter">column_name</replaceable> WITHOUT OVERLAPS ] )</lit= eral>
- =C2=A0 =C2=A0<optional> <literal>INCLUDE ( <re= placeable class=3D"parameter">column_name</replaceable> = [, ...])</literal> </optional> (table constraint)</term><= br>+ =C2=A0 =C2=A0<term><literal>PRIMARY KEY</literal> (c= olumn constraint variant)</term>
+ =C2=A0 = =C2=A0<term><literal>PRIMARY KEY ( <replaceable class=3D&quo= t;parameter">column_name</replaceable> [, ... ] [, <replac= eable class=3D"parameter">column_name</replaceable> WITH= OUT OVERLAPS ] )
+ =C2=A0 =C2=A0<optional> INCLUDE ( <replaceab= le class=3D"parameter">column_name</replaceable> [, ...]= )</optional></literal> (table constraint variant= )</term>
=C2=A0 =C2=A0 =C2=A0<listitem>
=C2=A0 =C2= =A0 =C2=A0 <para>
=C2=A0 =C2=A0 =C2=A0 =C2=A0The <literal>PR= IMARY KEY</literal> constraint specifies that a column or
= =C2=A0
I'll forward this onto -hackers if no one decides t= o quickly handle it from here.

David J.


--00000000000065a1fc064c01131a--