Subject: doc: Add anchors in create_table.sgml

From: PG Doc comments form <[email-masked]>
Date: Thu, 02 Jan 2020 08:18:59 +0000

The following documentation comment has been logged on the website:

Page: https://www.postgresql.org/docs/12/sql-createtable.html
Description:

From 73ad66d721a3f87500857cdc6b1f4d810f2875df Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Ivan=20Mas=C3=A1r?= <[email-masked]>
Date: Thu, 2 Jan 2020 09:15:34 +0100
Subject: [PATCH] doc: Add anchors in create_table.sgml

---
 doc/src/sgml/ref/create_table.sgml | 84
+++++++++++++++++++-------------------
 1 file changed, 42 insertions(+), 42 deletions(-)

diff --git a/doc/src/sgml/ref/create_table.sgml
b/doc/src/sgml/ref/create_table.sgml
index 4a2b6f0dae..4b3b1ebceb 100644
--- a/doc/src/sgml/ref/create_table.sgml
+++ b/doc/src/sgml/ref/create_table.sgml
@@ -214,7 +214,7 @@ WITH ( MODULUS <replaceable
class="parameter">numeric_literal</replaceable>, REM
     </listitem>
    </varlistentry>
 
-   <varlistentry>
+   <varlistentry id="sql-createtable-if-not-exists">
     <term><literal>IF NOT EXISTS</literal></term>
     <listitem>
      <para>
@@ -226,7 +226,7 @@ WITH ( MODULUS <replaceable
class="parameter">numeric_literal</replaceable>, REM
     </listitem>
    </varlistentry>
 
-   <varlistentry>
+   <varlistentry id="sql-createtable-table-name">
     <term><replaceable class="parameter">table_name</replaceable></term>
     <listitem>
      <para>
@@ -235,7 +235,7 @@ WITH ( MODULUS <replaceable
class="parameter">numeric_literal</replaceable>, REM
     </listitem>
    </varlistentry>
 
-   <varlistentry>
+   <varlistentry id="sql-createtable-of-type-name">
     <term><literal>OF <replaceable
class="parameter">type_name</replaceable></literal></term>
     <listitem>
      <para>
@@ -256,7 +256,7 @@ WITH ( MODULUS <replaceable
class="parameter">numeric_literal</replaceable>, REM
     </listitem>
    </varlistentry>
 
-   <varlistentry>
+   <varlistentry id="sql-createtable-column-name">
     <term><replaceable class="parameter">column_name</replaceable></term>
     <listitem>
      <para>
@@ -265,7 +265,7 @@ WITH ( MODULUS <replaceable
class="parameter">numeric_literal</replaceable>, REM
     </listitem>
    </varlistentry>
 
-   <varlistentry>
+   <varlistentry id="sql-createtable-data-type">
     <term><replaceable class="parameter">data_type</replaceable></term>
     <listitem>
      <para>
@@ -277,7 +277,7 @@ WITH ( MODULUS <replaceable
class="parameter">numeric_literal</replaceable>, REM
     </listitem>
    </varlistentry>
 
-   <varlistentry>
+   <varlistentry id="sql-createtable-collate">
     <term><literal>COLLATE
<replaceable>collation</replaceable></literal></term>
     <listitem>
      <para>
@@ -288,7 +288,7 @@ WITH ( MODULUS <replaceable
class="parameter">numeric_literal</replaceable>, REM
     </listitem>
    </varlistentry>
 
-   <varlistentry>
+   <varlistentry id="sql-createtable-inherits">
     <term><literal>INHERITS ( <replaceable>parent_table</replaceable> [,
... ] )</literal></term>
     <listitem>
      <para>
@@ -345,7 +345,7 @@ WITH ( MODULUS <replaceable
class="parameter">numeric_literal</replaceable>, REM
     </listitem>
    </varlistentry>
 
-   <varlistentry>
+   <varlistentry id="sql-createtable-partition-by">
     <term><literal>PARTITION BY { RANGE | LIST | HASH } ( { <replaceable
class="parameter">column_name</replaceable> | ( <replaceable
class="parameter">expression</replaceable> ) } [ <replaceable
class="parameter">opclass</replaceable> ] [, ...] ) </literal></term>
     <listitem>
      <para>
@@ -559,7 +559,7 @@ WITH ( MODULUS <replaceable
class="parameter">numeric_literal</replaceable>, REM
     </listitem>
    </varlistentry>
 
-   <varlistentry>
+   <varlistentry id="sql-createtable-like">
     <term><literal>LIKE <replaceable>source_table</replaceable> [
<replaceable>like_option</replaceable> ... ]</literal></term>
     <listitem>
      <para>
@@ -591,7 +591,7 @@ WITH ( MODULUS <replaceable
class="parameter">numeric_literal</replaceable>, REM
       available options are:
 
       <variablelist>
-       <varlistentry>
+       <varlistentry id="sql-createtable-like-including-comments">
         <term><literal>INCLUDING COMMENTS</literal></term>
         <listitem>
          <para>
@@ -603,7 +603,7 @@ WITH ( MODULUS <replaceable
class="parameter">numeric_literal</replaceable>, REM
         </listitem>
        </varlistentry>
 
-       <varlistentry>
+       <varlistentry id="sql-createtable-like-including-constraints">
         <term><literal>INCLUDING CONSTRAINTS</literal></term>
         <listitem>
          <para>
@@ -614,7 +614,7 @@ WITH ( MODULUS <replaceable
class="parameter">numeric_literal</replaceable>, REM
         </listitem>
        </varlistentry>
 
-       <varlistentry>
+       <varlistentry id="sql-createtable-like-including-defaults">
         <term><literal>INCLUDING DEFAULTS</literal></term>
         <listitem>
          <para>
@@ -628,7 +628,7 @@ WITH ( MODULUS <replaceable
class="parameter">numeric_literal</replaceable>, REM
         </listitem>
        </varlistentry>
 
-       <varlistentry>
+       <varlistentry id="sql-createtable-like-including-generated">
         <term><literal>INCLUDING GENERATED</literal></term>
         <listitem>
          <para>
@@ -638,7 +638,7 @@ WITH ( MODULUS <replaceable
class="parameter">numeric_literal</replaceable>, REM
         </listitem>
        </varlistentry>
 
-       <varlistentry>
+       <varlistentry id="sql-createtable-like-including-identity">
         <term><literal>INCLUDING IDENTITY</literal></term>
         <listitem>
          <para>
@@ -650,7 +650,7 @@ WITH ( MODULUS <replaceable
class="parameter">numeric_literal</replaceable>, REM
         </listitem>
        </varlistentry>
 
-       <varlistentry>
+       <varlistentry id="sql-createtable-like-including-indexes">
         <term><literal>INCLUDING INDEXES</literal></term>
         <listitem>
          <para>
@@ -664,7 +664,7 @@ WITH ( MODULUS <replaceable
class="parameter">numeric_literal</replaceable>, REM
         </listitem>
        </varlistentry>
 
-       <varlistentry>
+       <varlistentry id="sql-createtable-like-including-statistics">
         <term><literal>INCLUDING STATISTICS</literal></term>
         <listitem>
          <para>
@@ -673,7 +673,7 @@ WITH ( MODULUS <replaceable
class="parameter">numeric_literal</replaceable>, REM
         </listitem>
        </varlistentry>
 
-       <varlistentry>
+       <varlistentry id="sql-createtable-like-including-storage">
         <term><literal>INCLUDING STORAGE</literal></term>
         <listitem>
          <para>
@@ -687,7 +687,7 @@ WITH ( MODULUS <replaceable
class="parameter">numeric_literal</replaceable>, REM
         </listitem>
        </varlistentry>
 
-       <varlistentry>
+       <varlistentry id="sql-createtable-like-including-all">
         <term><literal>INCLUDING ALL</literal></term>
         <listitem>
          <para>
@@ -711,7 +711,7 @@ WITH ( MODULUS <replaceable
class="parameter">numeric_literal</replaceable>, REM
     </listitem>
    </varlistentry>
 
-   <varlistentry>
+   <varlistentry id="sql-createtable-constraint">
     <term><literal>CONSTRAINT <replaceable
class="parameter">constraint_name</replaceable></literal></term>
     <listitem>
      <para>
@@ -725,7 +725,7 @@ WITH ( MODULUS <replaceable
class="parameter">numeric_literal</replaceable>, REM
     </listitem>
    </varlistentry>
 
-   <varlistentry>
+   <varlistentry id="sql-createtable-not-null">
     <term><literal>NOT NULL</literal></term>
     <listitem>
      <para>
@@ -734,7 +734,7 @@ WITH ( MODULUS <replaceable
class="parameter">numeric_literal</replaceable>, REM
     </listitem>
    </varlistentry>
 
-   <varlistentry>
+   <varlistentry id="sql-createtable-null">
     <term><literal>NULL</literal></term>
     <listitem>
      <para>
@@ -749,7 +749,7 @@ WITH ( MODULUS <replaceable
class="parameter">numeric_literal</replaceable>, REM
     </listitem>
    </varlistentry>
 
-   <varlistentry>
+   <varlistentry id="sql-createtable-check">
     <term><literal>CHECK ( <replaceable
class="parameter">expression</replaceable> ) [ NO INHERIT ]
</literal></term>
     <listitem>
      <para>
@@ -787,7 +787,7 @@ WITH ( MODULUS <replaceable
class="parameter">numeric_literal</replaceable>, REM
     </listitem>
    </varlistentry>
 
-   <varlistentry>
+   <varlistentry id="sql-createtable-default">
     <term><literal>DEFAULT
     <replaceable>default_expr</replaceable></literal></term>
     <listitem>
@@ -808,7 +808,7 @@ WITH ( MODULUS <replaceable
class="parameter">numeric_literal</replaceable>, REM
     </listitem>
    </varlistentry>
 
-   <varlistentry>
+   <varlistentry id="sql-createtable-generated-always-as">
     <term><literal>GENERATED ALWAYS AS (
<replaceable>generation_expr</replaceable> )
STORED</literal><indexterm><primary>generated
column</primary></indexterm></term>
     <listitem>
      <para>
@@ -830,7 +830,7 @@ WITH ( MODULUS <replaceable
class="parameter">numeric_literal</replaceable>, REM
     </listitem>
    </varlistentry>
 
-   <varlistentry>
+   <varlistentry id="sql-createtable-generated-as-identity">
     <term><literal>GENERATED { ALWAYS | BY DEFAULT } AS IDENTITY [ (
<replaceable>sequence_options</replaceable> ) ]</literal></term>
     <listitem>
      <para>
@@ -861,7 +861,7 @@ WITH ( MODULUS <replaceable
class="parameter">numeric_literal</replaceable>, REM
     </listitem>
    </varlistentry>
 
-   <varlistentry>
+   <varlistentry id="sql-createtable-uniqye">
     <term><literal>UNIQUE</literal> (column constraint)</term>
     <term><literal>UNIQUE ( <replaceable
class="parameter">column_name</replaceable> [, ... ] )</literal>
     <optional> INCLUDE ( <replaceable
class="parameter">column_name</replaceable> [, ...]) </optional> (table
constraint)</term>
@@ -907,7 +907,7 @@ WITH ( MODULUS <replaceable
class="parameter">numeric_literal</replaceable>, REM
     </listitem>
    </varlistentry>
 
-   <varlistentry>
+   <varlistentry id="sql-createtable-primary-key">
     <term><literal>PRIMARY KEY</literal> (column constraint)</term>
     <term><literal>PRIMARY KEY ( <replaceable
class="parameter">column_name</replaceable> [, ... ] )</literal>
     <optional> INCLUDE ( <replaceable
class="parameter">column_name</replaceable> [, ...]) </optional> (table
constraint)</term>
@@ -1003,7 +1003,7 @@ WITH ( MODULUS <replaceable
class="parameter">numeric_literal</replaceable>, REM
     </listitem>
    </varlistentry>
 
-   <varlistentry>
+   <varlistentry id="sql-createtable-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>FOREIGN KEY ( <replaceable
class="parameter">column_name</replaceable> [, ... ] )
@@ -1063,7 +1063,7 @@ WITH ( MODULUS <replaceable
class="parameter">numeric_literal</replaceable>, REM
       actions for each clause:
 
       <variablelist>
-       <varlistentry>
+       <varlistentry id="sql-createtable-action-no-action">
         <term><literal>NO ACTION</literal></term>
         <listitem>
          <para>
@@ -1076,7 +1076,7 @@ WITH ( MODULUS <replaceable
class="parameter">numeric_literal</replaceable>, REM
         </listitem>
        </varlistentry>
 
-       <varlistentry>
+       <varlistentry id="sql-createtable-action-restrict">
         <term><literal>RESTRICT</literal></term>
         <listitem>
          <para>
@@ -1088,7 +1088,7 @@ WITH ( MODULUS <replaceable
class="parameter">numeric_literal</replaceable>, REM
         </listitem>
        </varlistentry>
 
-       <varlistentry>
+       <varlistentry id="sql-createtable-action-cascade">
         <term><literal>CASCADE</literal></term>
         <listitem>
          <para>
@@ -1099,7 +1099,7 @@ WITH ( MODULUS <replaceable
class="parameter">numeric_literal</replaceable>, REM
         </listitem>
        </varlistentry>
 
-       <varlistentry>
+       <varlistentry id="sql-createtable-action-set-null">
         <term><literal>SET NULL</literal></term>
         <listitem>
          <para>
@@ -1108,7 +1108,7 @@ WITH ( MODULUS <replaceable
class="parameter">numeric_literal</replaceable>, REM
         </listitem>
        </varlistentry>
 
-       <varlistentry>
+       <varlistentry id="sql-createtable-action-set-default">
         <term><literal>SET DEFAULT</literal></term>
         <listitem>
          <para>
@@ -1130,7 +1130,7 @@ WITH ( MODULUS <replaceable
class="parameter">numeric_literal</replaceable>, REM
     </listitem>
    </varlistentry>
 
-   <varlistentry>
+   <varlistentry id="sql-createtable-deferrable">
     <term><literal>DEFERRABLE</literal></term>
     <term><literal>NOT DEFERRABLE</literal></term>
     <listitem>
@@ -1152,7 +1152,7 @@ WITH ( MODULUS <replaceable
class="parameter">numeric_literal</replaceable>, REM
     </listitem>
    </varlistentry>
 
-   <varlistentry>
+   <varlistentry id="sql-createtable-initially">
     <term><literal>INITIALLY IMMEDIATE</literal></term>
     <term><literal>INITIALLY DEFERRED</literal></term>
     <listitem>
@@ -1182,7 +1182,7 @@ WITH ( MODULUS <replaceable
class="parameter">numeric_literal</replaceable>, REM
     </listitem>
    </varlistentry>
 
-   <varlistentry>
+   <varlistentry id="sql-createtable-with">
     <term><literal>WITH ( <replaceable
class="parameter">storage_parameter</replaceable> [= <replaceable
class="parameter">value</replaceable>] [, ... ] )</literal></term>
     <listitem>
      <para>
@@ -1197,7 +1197,7 @@ WITH ( MODULUS <replaceable
class="parameter">numeric_literal</replaceable>, REM
     </listitem>
    </varlistentry>
 
-   <varlistentry>
+   <varlistentry id="sql-createtable-without-oids">
     <term><literal>WITHOUT OIDS</literal></term>
     <listitem>
      <para>
@@ -1208,7 +1208,7 @@ WITH ( MODULUS <replaceable
class="parameter">numeric_literal</replaceable>, REM
     </listitem>
    </varlistentry>
 
-   <varlistentry>
+   <varlistentr id="sql-createtable-on-commit">
     <term><literal>ON COMMIT</literal></term>
     <listitem>
      <para>
@@ -1217,7 +1217,7 @@ WITH ( MODULUS <replaceable
class="parameter">numeric_literal</replaceable>, REM
       The three options are:
 
       <variablelist>
-       <varlistentry>
+       <varlistentry id="sql-createtable-on-commit-preserve-rows">
         <term><literal>PRESERVE ROWS</literal></term>
         <listitem>
          <para>
@@ -1227,7 +1227,7 @@ WITH ( MODULUS <replaceable
class="parameter">numeric_literal</replaceable>, REM
         </listitem>
        </varlistentry>
 
-       <varlistentry>
+       <varlistentry id="sql-createtable-on-commit-delete-rows">
         <term><literal>DELETE ROWS</literal></term>
         <listitem>
          <para>
@@ -1240,7 +1240,7 @@ WITH ( MODULUS <replaceable
class="parameter">numeric_literal</replaceable>, REM
         </listitem>
        </varlistentry>
 
-       <varlistentry>
+       <varlistentry id="sql-createtable-on-commit-drop">
         <term><literal>DROP</literal></term>
         <listitem>
          <para>
@@ -1272,7 +1272,7 @@ WITH ( MODULUS <replaceable
class="parameter">numeric_literal</replaceable>, REM
     </listitem>
    </varlistentry>
 
-   <varlistentry>
+   <varlistentry id="sql-createtable-using-index-tablespace">
     <term><literal>USING INDEX TABLESPACE <replaceable
class="parameter">tablespace_name</replaceable></literal></term>
     <listitem>
      <para>
-- 
2.11.0

---

From: Alvaro Herrera <[email-masked]>
Date: Thu, 2 Jan 2020 12:56:32 -0300

> Subject: [PATCH] doc: Add anchors in create_table.sgml

Can you comment a little on the reason for adding these?  I'm not
opposed to doing so, but we don't have them in every possible place (we
have in 607 of ~4300 varlistentries by my count), so it needs some
rationale.

-- 
Álvaro Herrera                https://www.2ndQuadrant.com/
PostgreSQL Development, 24x7 Support, Remote DBA, Training & Services

---

From: helix84 <[email-masked]>
Date: Thu, 2 Jan 2020 21:56:00 +0100

Hi, I prefer to bookmark docs pointing to the exact term I need and
with pg docs it's often been the case that the exact term doesn't have
an anchor or only has unstable, generated anchors. So I would very
much like to add stable anchors in many more places. I haven't
contributed to pg before, so this patch is me testing the waters. If
there is interest, I'd like to add stable anchors to wherever we'll
agree it makes sense - preferably in an automated or semi-automated
way.

I read an older thread on this topic [1] which links to a custom SGML
parser in Python for this specific task [2]. I have experience with
XSLT, but not so much with SGML processing, so I would appreciate if
you could point me whether a custom parser is the way to go for this
task or I should look into a more generic SGML processing tool.

Thanks in advance and let me take this opportunity to thank you all
for this wonderful piece of software.

[1] https://www.postgresql-archive.org/Please-provide-stable-target-anchors-td2167039.html
[2] https://bitbucket.org/dvarrazzo/pg-doc-anchors/src/default/

Regards,
~~helix84

---

From: Alvaro Herrera <[email-masked]>
Date: Fri, 3 Jan 2020 10:35:20 -0300

Hi,

> task or I should look into a more generic SGML processing tool.

Ah,
https://www.postgresql.org/message-id/[email-masked]
(We prefer our own archive to GMane's.)  That thread is so old that
Peter feels the need to point out that the Git mirror was out of date
with CVS ... I can no longer even remember the commit process for CVS
anymore.  We also converted from SGML to XML in the meantime, so you can
probably make do with a standard XML parser without having to write a
custom SGML one.  (Daniele Varrazzo's patch ended up as 477319829c2e.)

TBH I've felt the need for anchors for <varlistentry> tags in the
past also (IIRC the runtime-config page would be improved by them),
but I'm not sure about adding them to every single keyword of every
single reference page.  Is that really useful?

> for this wonderful piece of software.

You're welcome.

---

From: Jürgen Purtz <[email-masked]>
Date: Fri, 3 Jan 2020 15:10:49 +0100

> We also converted from SGML to XML in the meantime, so you can
> custom SGML one.

Use XML tools with care! Some of our XML files are not well formed 
because they contain more than one root element.

Kind regards, Jürgen Purtz.

---

From: Bruce Momjian <[email-masked]>
Date: Fri, 17 Jan 2020 18:22:46 -0500

> single reference page.  Is that really useful?

It would be helpful if the release notes could point to specific
tables in the docs, rather than just sections.

-- 
  Bruce Momjian  <[email-masked]>        http://momjian.us
  EnterpriseDB                             http://enterprisedb.com

+ As you are, so once was I.  As I am, so you will be. +
+                      Ancient Roman grave inscription +