Обсуждение: doc: Add anchors in create_table.sgml

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?= <helix84@centrum.sk>
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

On 2020-Jan-02, PG Doc comments form wrote:

> 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?= <helix84@centrum.sk>
> Date: Thu, 2 Jan 2020 09:15:34 +0100
> 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

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

On Thu, Jan 2, 2020 at 4:56 PM Alvaro Herrera <alvherre@2ndquadrant.com> wrote:
>
> On 2020-Jan-02, PG Doc comments form wrote:
>
> > 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?= <helix84@centrum.sk>
> > Date: Thu, 2 Jan 2020 09:15:34 +0100
> > 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

Hi,

On 2020-Jan-02, helix84 wrote:

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

Ah,
https://www.postgresql.org/message-id/AANLkTikAgIyYfwy_2Zj8GafoC7ZFlGv5iCdab1l7VuDp@mail.gmail.com
(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?

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

You're welcome.

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

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

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.

On Fri, Jan  3, 2020 at 10:35:20AM -0300, Alvaro Herrera wrote:
> Hi,
> 
> On 2020-Jan-02, helix84 wrote:
> 
> > 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.
> 
> Ah,
> https://www.postgresql.org/message-id/AANLkTikAgIyYfwy_2Zj8GafoC7ZFlGv5iCdab1l7VuDp@mail.gmail.com
> (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?

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

-- 
  Bruce Momjian  <bruce@momjian.us>        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 +