Re: [PATCH] Missing links between system catalog documentation pages

Alvaro Herrera <alvherre@2ndquadrant.com> writes:

> On 2020-Jun-21, Tom Lane wrote:
>
>> That has not been our practice up to now, eg in comparable cases in
>> discussions of GUC variables, only the first reference is xref-ified.
>> I think it could be kind of annoying to make every reference a link,
>> both for regular readers (the link decoration is too bold in most
>> browsers) and for users of screen-reader software.
>
> In the glossary I also changed things so that only the first reference
> of a term in another term's definition is linked; my experience reading
> the originals as submitted (which did link them all at some point) is
> that the extra links are very distracting, bad for readability.  So +1
> for not adding links to every single mention.

There were only three cases of multiple mentions of the same table in a
single paragraph, I've removed them in the attached patch.

I've also added a second patch that makes the SQL commands links.  There
were some cases of the same commands being mentioned in the descriptions
of multiple columns in the same table, but I've left those in place,
since that feels less disruptive than in prose.

>> There is a fair question as to how far apart two references should
>> be before we <xref> both of them.  But I think that distance
>> does need to be more than zero, and probably more than one para.
>
> Nod.

I tend to agree.

- ilmari
-- 
"A disappointingly low fraction of the human race is,
 at any given time, on fire." - Stig Sandbeck Mathisen

From 165c4aa4613d572a0547a2f2d01dcf06dfa93a24 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Dagfinn=20Ilmari=20Manns=C3=A5ker?= <ilmari@ilmari.org>
Date: Sun, 24 May 2020 21:48:29 +0100
Subject: [PATCH v3 1/2] Add missing cross-links in system catalog
 documentation

This makes the first mention of a system catalog or view in each
paragraph in the system system catalog and view documentation pages
hyperlinks, for easier navigation.

Also linkify the first mention of pg_hba.conf in pg_hba_file_rules, as
that's more specific and easier to spot than the link to the client
authentication chapter at the bottom.
---
 doc/src/sgml/catalogs.sgml | 140 ++++++++++++++++++++-----------------
 1 file changed, 77 insertions(+), 63 deletions(-)

diff --git a/doc/src/sgml/catalogs.sgml b/doc/src/sgml/catalogs.sgml
index 700271fd40..47d78d2ff8 100644
--- a/doc/src/sgml/catalogs.sgml
+++ b/doc/src/sgml/catalogs.sgml
@@ -16,7 +16,8 @@
    Normally, one should not change the system catalogs by hand, there
    are normally SQL commands to do that.  (For example, <command>CREATE
    DATABASE</command> inserts a row into the
-   <structname>pg_database</structname> catalog — and actually
+   <link linkend="catalog-pg-database"><structname>pg_database</structname></link>
+   catalog — and actually
    creates the database on disk.)  There are some exceptions for
    particularly esoteric operations, but many of those have been made
    available as SQL commands over time, and so the need for direct manipulation
@@ -381,9 +382,10 @@
    <function>sum</function>, <function>count</function>, and
    <function>max</function>.  Each entry in
    <structname>pg_aggregate</structname> is an extension of an entry
-   in <structname>pg_proc</structname>.  The <structname>pg_proc</structname>
-   entry carries the aggregate's name, input and output data types, and
-   other information that is similar to ordinary functions.
+   in <link linkend="catalog-pg-proc"><structname>pg_proc</structname></link>.
+   The <structname>pg_proc</structname> entry carries the aggregate's name,
+   input and output data types, and other information that is similar to
+   ordinary functions.
   </para>
 
   <table>
@@ -407,7 +409,7 @@
        (references <link
linkend="catalog-pg-proc"><structname>pg_proc</structname></link>.<structfield>oid</structfield>)
       </para>
       <para>
-       <structname>pg_proc</structname> OID of the aggregate function
+       OID of the aggregate function
       </para></entry>
      </row>
 
@@ -902,7 +904,7 @@
    catalog structure for performance reasons).  Also,
    <structfield>amoplefttype</structfield> and <structfield>amoprighttype</structfield> must match
    the <structfield>oprleft</structfield> and <structfield>oprright</structfield> fields of the
-   referenced <structname>pg_operator</structname> entry.
+   referenced <link linkend="catalog-pg-operator"><structname>pg_operator</structname></link> entry.
   </para>
 
  </sect1>
@@ -1099,7 +1101,8 @@
    table columns.  There will be exactly one
    <structname>pg_attribute</structname> row for every column in every
    table in the database.  (There will also be attribute entries for
-   indexes, and indeed all objects that have <structname>pg_class</structname>
+   indexes, and indeed all objects that have
+   <link linkend="catalog-pg-class"><structname>pg_class</structname></link>
    entries.)
   </para>
 
@@ -1270,7 +1273,7 @@
       <para>
        This column has a default expression or generation expression, in which
        case there will be a corresponding entry in the
-       <structname>pg_attrdef</structname> catalog that actually defines the
+       <link linkend="catalog-pg-attrdef"><structname>pg_attrdef</structname></link> catalog that actually defines
the
        expression.  (Check <structfield>attgenerated</structfield> to
        determine whether this is a default or a generation expression.)
       </para></entry>
@@ -1402,7 +1405,7 @@
    In a dropped column's <structname>pg_attribute</structname> entry,
    <structfield>atttypid</structfield> is reset to zero, but
    <structfield>attlen</structfield> and the other fields copied from
-   <structname>pg_type</structname> are still valid.  This arrangement is needed
+   <link linkend="catalog-pg-type"><structname>pg_type</structname></link> are still valid.  This arrangement is
needed
    to cope with the situation where the dropped column's data type was
    later dropped, and so there is no <structname>pg_type</structname> row anymore.
    <structfield>attlen</structfield> and the other fields can be used
@@ -1835,14 +1838,16 @@
 
   <para>
    The catalog <structname>pg_class</structname> catalogs tables and most
-   everything else that has columns or is otherwise similar to a
-   table.  This includes indexes (but see also
-   <structname>pg_index</structname>), sequences (but see also
-   <structname>pg_sequence</structname>), views, materialized
-   views, composite types, and TOAST tables; see <structfield>relkind</structfield>.
-   Below, when we mean all of these
-   kinds of objects we speak of <quote>relations</quote>.  Not all
-   columns are meaningful for all relation types.
+   everything else that has columns or is otherwise similar to a table.
+   This includes indexes (but see also <link
+   linkend="catalog-pg-index"><structname>pg_index</structname></link>),
+   sequences (but see also <link
+   linkend="catalog-pg-sequence"><structname>pg_sequence</structname></link>),
+   views, materialized views, composite types, and TOAST tables;
+   see <structfield>relkind</structfield>.
+   Below, when we mean all of these kinds of objects we speak of
+   <quote>relations</quote>.  Not all columns are meaningful for all relation
+   types.
   </para>
 
   <table>
@@ -1895,7 +1900,7 @@
       </para>
       <para>
        The OID of the data type that corresponds to this table's row type,
-       if any (zero for indexes, which have no <structname>pg_type</structname> entry)
+       if any (zero for indexes, which have no <link linkend="catalog-pg-type"><structname>pg_type</structname></link>
entry)
       </para></entry>
      </row>
 
@@ -2019,7 +2024,7 @@
       </para>
       <para>
        True if this table is shared across all databases in the cluster.  Only
-       certain system catalogs (such as <structname>pg_database</structname>)
+       certain system catalogs (such as <link
linkend="catalog-pg-database"><structname>pg_database</structname></link>)
        are shared.
       </para></entry>
      </row>
@@ -2059,8 +2064,8 @@
       <para>
        Number of user columns in the relation (system columns not
        counted).  There must be this many corresponding entries in
-       <structname>pg_attribute</structname>.  See also
-       <literal>pg_attribute.attnum</literal>.
+       <link linkend="catalog-pg-attribute"><structname>pg_attribute</structname></link>.  See also
+       <structname>pg_attribute</structname>.<structfield>attnum</structfield>.
       </para></entry>
      </row>
 
@@ -2404,7 +2409,8 @@
    key, unique, foreign key, and exclusion constraints on tables.
    (Column constraints are not treated specially.  Every column constraint is
    equivalent to some table constraint.)
-   Not-null constraints are represented in the <structname>pg_attribute</structname>
+   Not-null constraints are represented in the
+   <link linkend="catalog-pg-attribute"><structname>pg_attribute</structname></link>
    catalog, not here.
   </para>
 
@@ -2707,7 +2713,7 @@
    For other cases, a zero appears in <structfield>conkey</structfield>
    and the associated index must be consulted to discover the expression
    that is constrained.  (<structfield>conkey</structfield> thus has the
-   same contents as <structname>pg_index</structname>.<structfield>indkey</structfield> for the
+   same contents as <link
linkend="catalog-pg-index"><structname>pg_index</structname></link>.<structfield>indkey</structfield>for the
 
    index.)
   </para>
 
@@ -2975,7 +2981,7 @@
        track whether the database needs to be vacuumed in order to prevent
        transaction ID wraparound or to allow <literal>pg_xact</literal> to be shrunk.
        It is the minimum of the per-table
-       <structname>pg_class</structname>.<structfield>relfrozenxid</structfield> values.
+       <link
linkend="catalog-pg-class"><structname>pg_class</structname></link>.<structfield>relfrozenxid</structfield>values.
 
       </para></entry>
      </row>
 
@@ -2989,7 +2995,7 @@
        track whether the database needs to be vacuumed in order to prevent
        multixact ID wraparound or to allow <literal>pg_multixact</literal> to be shrunk.
        It is the minimum of the per-table
-       <structname>pg_class</structname>.<structfield>relminmxid</structfield> values.
+       <link linkend="catalog-pg-class"><structname>pg_class</structname></link>.<structfield>relminmxid</structfield>
values.
       </para></entry>
      </row>
 
@@ -3001,7 +3007,7 @@
       <para>
        The default tablespace for the database.
        Within this database, all tables for which
-       <structname>pg_class</structname>.<structfield>reltablespace</structfield> is zero
+       <link
linkend="catalog-pg-class"><structname>pg_class</structname></link>.<structfield>reltablespace</structfield>is zero
 
        will be stored in this tablespace; in particular, all the non-shared
        system catalogs will be there.
       </para></entry>
@@ -3600,7 +3606,7 @@
        (references <link
linkend="catalog-pg-type"><structname>pg_type</structname></link>.<structfield>oid</structfield>)
       </para>
       <para>
-       The OID of the <structname>pg_type</structname> entry owning this enum value
+       The OID of the <link linkend="catalog-pg-type"><structname>pg_type</structname></link> entry owning this enum
value
       </para></entry>
      </row>
 
@@ -4094,11 +4100,13 @@
 
   <para>
    The catalog <structname>pg_foreign_table</structname> contains
-   auxiliary information about foreign tables.  A foreign table is
-   primarily represented by a <structname>pg_class</structname> entry,
-   just like a regular table.  Its <structname>pg_foreign_table</structname>
-   entry contains the information that is pertinent only to foreign tables
-   and not any other kind of relation.
+   auxiliary information about foreign tables.
+   A foreign table is primarily represented by a
+   <link linkend="catalog-pg-class"><structname>pg_class</structname></link>
+   entry, just like a regular table.
+   Its <structname>pg_foreign_table</structname> entry contains the
+   information that is pertinent only to foreign tables and not any other kind
+   of relation.
   </para>
 
   <table>
@@ -4122,7 +4130,7 @@
        (references <link
linkend="catalog-pg-class"><structname>pg_class</structname></link>.<structfield>oid</structfield>)
       </para>
       <para>
-       OID of the <structname>pg_class</structname> entry for this foreign table
+       The OID of the <link linkend="catalog-pg-class"><structname>pg_class</structname></link> entry for this foreign
table
       </para></entry>
      </row>
 
@@ -4160,7 +4168,7 @@
   <para>
    The catalog <structname>pg_index</structname> contains part of the information
    about indexes.  The rest is mostly in
-   <structname>pg_class</structname>.
+   <link linkend="catalog-pg-class"><structname>pg_class</structname></link>.
   </para>
 
   <table>
@@ -4184,7 +4192,7 @@
        (references <link
linkend="catalog-pg-class"><structname>pg_class</structname></link>.<structfield>oid</structfield>)
       </para>
       <para>
-       The OID of the <structname>pg_class</structname> entry for this index
+       The OID of the <link linkend="catalog-pg-class"><structname>pg_class</structname></link> entry for this index
       </para></entry>
      </row>
 
@@ -4194,7 +4202,7 @@
        (references <link
linkend="catalog-pg-class"><structname>pg_class</structname></link>.<structfield>oid</structfield>)
       </para>
       <para>
-       The OID of the <structname>pg_class</structname> entry for the table this index is for
+       The OID of the <link linkend="catalog-pg-class"><structname>pg_class</structname></link> entry for the table
thisindex is for
 
       </para></entry>
      </row>
 
@@ -5391,7 +5399,7 @@
        (references <link
linkend="catalog-pg-class"><structname>pg_class</structname></link>.<structfield>oid</structfield>)
       </para>
       <para>
-       The OID of the <structname>pg_class</structname> entry for this partitioned table
+       The OID of the <link linkend="catalog-pg-class"><structname>pg_class</structname></link> entry for this
partitionedtable
 
       </para></entry>
      </row>
 
@@ -5420,7 +5428,7 @@
        (references <link
linkend="catalog-pg-class"><structname>pg_class</structname></link>.<structfield>oid</structfield>)
       </para>
       <para>
-       The OID of the <structname>pg_class</structname> entry for the default partition
+       The OID of the <link linkend="catalog-pg-class"><structname>pg_class</structname></link> entry for the default
partition
        of this partitioned table, or zero if this partitioned table does not
        have a default partition.
       </para></entry>
@@ -5600,7 +5608,7 @@
   <note>
    <para>
     Policies stored in <structname>pg_policy</structname> are applied only when
-    <structname>pg_class</structname>.<structfield>relrowsecurity</structfield> is set for
+    <link
linkend="catalog-pg-class"><structname>pg_class</structname></link>.<structfield>relrowsecurity</structfield>is set
for
     their table.
    </para>
   </note>
@@ -5625,7 +5633,7 @@
   <para>
    If <structfield>prokind</structfield> indicates that the entry is for an
    aggregate function, there should be a matching row in
-   <structfield>pg_aggregate</structfield>.
+   <link linkend="catalog-pg-aggregate"><structfield>pg_aggregate</structfield></link>.
   </para>
 
   <table>
@@ -6555,7 +6563,8 @@
   <para>
    The catalog <structname>pg_sequence</structname> contains information about
    sequences.  Some of the information about sequences, such as the name and
-   the schema, is in <structname>pg_class</structname>.
+   the schema, is in
+   <link linkend="catalog-pg-class"><structname>pg_class</structname></link>
   </para>
 
   <table>
@@ -6579,7 +6588,7 @@
        (references <link
linkend="catalog-pg-class"><structname>pg_class</structname></link>.<structfield>oid</structfield>)
       </para>
       <para>
-       The OID of the <structname>pg_class</structname> entry for this sequence
+       The OID of the <link linkend="catalog-pg-class"><structname>pg_class</structname></link> entry for this
sequence
       </para></entry>
      </row>
 
@@ -7338,13 +7347,14 @@
 
   <para>
    The catalog <structname>pg_statistic_ext_data</structname>
-   holds data for extended planner statistics defined in <structname>pg_statistic_ext</structname>.
+   holds data for extended planner statistics defined in
+   <link linkend="catalog-pg-statistic-ext"><structname>pg_statistic_ext</structname></link>.
    Each row in this catalog corresponds to a <firstterm>statistics object</firstterm>
    created with <xref linkend="sql-createstatistics"/>.
   </para>
 
   <para>
-   Like <structname>pg_statistic</structname>,
+   Like <link linkend="catalog-pg-statistic"><structname>pg_statistic</structname></link>,
    <structname>pg_statistic_ext_data</structname> should not be
    readable by the public, since the contents might be considered sensitive.
    (Example: most common combinations of values in columns might be quite
@@ -7352,7 +7362,7 @@
    <link linkend="view-pg-stats-ext"><structname>pg_stats_ext</structname></link>
    is a publicly readable view
    on <structname>pg_statistic_ext_data</structname> (after joining
-   with <structname>pg_statistic_ext</structname>) that only exposes
+   with <link linkend="catalog-pg-statistic-ext"><structname>pg_statistic_ext</structname></link>) that only exposes
    information about those tables and columns that are readable by the
    current user.
   </para>
@@ -7938,7 +7948,7 @@
        (references <link
linkend="catalog-pg-constraint"><structname>pg_constraint</structname></link>.<structfield>oid</structfield>)
       </para>
       <para>
-       The <structname>pg_constraint</structname> entry associated with the trigger, if any
+       The <link linkend="catalog-pg-constraint"><structname>pg_constraint</structname></link> entry associated with
thetrigger, if any
 
       </para></entry>
      </row>
 
@@ -8036,7 +8046,7 @@
     When <structfield>tgconstraint</structfield> is nonzero,
     <structfield>tgconstrrelid</structfield>, <structfield>tgconstrindid</structfield>,
     <structfield>tgdeferrable</structfield>, and <structfield>tginitdeferred</structfield> are
-    largely redundant with the referenced <structname>pg_constraint</structname> entry.
+    largely redundant with the referenced <link
linkend="catalog-pg-constraint"><structname>pg_constraint</structname></link>entry.
 
     However, it is possible for a non-deferrable trigger to be associated
     with a deferrable constraint: foreign key constraints can have some
     deferrable and some non-deferrable triggers.
@@ -8183,7 +8193,7 @@
        (references <link
linkend="catalog-pg-ts-config"><structname>pg_ts_config</structname></link>.<structfield>oid</structfield>)
       </para>
       <para>
-       The OID of the <structname>pg_ts_config</structname> entry owning this map entry
+       The OID of the <link linkend="catalog-pg-ts-config"><structname>pg_ts_config</structname></link> entry owning
thismap entry
 
       </para></entry>
      </row>
 
@@ -8697,11 +8707,11 @@
       <para>
        If this is a composite type (see
        <structfield>typtype</structfield>), then this column points to
-       the <structname>pg_class</structname> entry that defines the
+       the <link linkend="catalog-pg-class"><structname>pg_class</structname></link> entry that defines the
        corresponding table.  (For a free-standing composite type, the
-       <structname>pg_class</structname> entry doesn't really represent
+       <link linkend="catalog-pg-class"><structname>pg_class</structname></link> entry doesn't really represent
        a table, but it is needed anyway for the type's
-       <structname>pg_attribute</structname> entries to link to.)
+       <link linkend="catalog-pg-attribute"><structname>pg_attribute</structname></link> entries to link to.)
        Zero for non-composite types.
       </para></entry>
      </row>
@@ -9964,8 +9974,9 @@
 
   <para>
    The view <structname>pg_hba_file_rules</structname> provides a summary of
-   the contents of the client authentication configuration
-   file, <filename>pg_hba.conf</filename>.  A row appears in this view for each
+   the contents of the client authentication configuration file,
+   <link linkend="auth-pg-hba-conf"><filename>pg_hba.conf</filename></link>.
+   A row appears in this view for each
    non-empty, non-comment line in the file, with annotations indicating
    whether the rule could be applied successfully.
   </para>
@@ -10206,8 +10217,10 @@
    individual tuples of relations,
    transaction IDs (both virtual and permanent IDs),
    and general database objects (identified by class OID and object OID,
-   in the same way as in <structname>pg_description</structname> or
-   <structname>pg_depend</structname>).  Also, the right to extend a
+   in the same way as in
+   <link linkend="catalog-pg-description"><structname>pg_description</structname></link>
+   or <link linkend="catalog-pg-depend"><structname>pg_depend</structname></link>).
+   Also, the right to extend a
    relation is represented as a separate lockable object.
    Also, <quote>advisory</quote> locks can be taken on numbers that have
    user-defined meanings.
@@ -10447,7 +10460,7 @@
    <structname>pg_locks</structname> provides a global view of all locks
    in the database cluster, not only those relevant to the current database.
    Although its <structfield>relation</structfield> column can be joined
-   against <structname>pg_class</structname>.<structfield>oid</structfield> to identify locked
+   against <link linkend="catalog-pg-class"><structname>pg_class</structname></link>.<structfield>oid</structfield> to
identifylocked
 
    relations, this will only work correctly for relations in the current
    database (those for which the <structfield>database</structfield> column
    is either the current database's OID or zero).
@@ -10944,8 +10957,9 @@
   <para>
    The view <structname>pg_publication_tables</structname> provides
    information about the mapping between publications and the tables they
-   contain.  Unlike the underlying
-   catalog <structname>pg_publication_rel</structname>, this view expands
+   contain.  Unlike the underlying catalog
+   <link linkend="catalog-pg-publication-rel"><structname>pg_publication_rel</structname></link>,
+   this view expands
    publications defined as <literal>FOR ALL TABLES</literal>, so for such
    publications there will be a row for each eligible table.
   </para>
@@ -11505,7 +11519,7 @@
   <para>
    The <structname>pg_rules</structname> view excludes the <literal>ON SELECT</literal> rules
    of views and materialized views; those can be seen in
-   <structname>pg_views</structname> and <structname>pg_matviews</structname>.
+   <link linkend="view-pg-views"><structname>pg_views</structname></link> and <link
linkend="view-pg-matviews"><structname>pg_matviews</structname></link>.
   </para>
 
  </sect1>
@@ -12334,7 +12348,7 @@
    the information stored in the <link
    linkend="catalog-pg-statistic"><structname>pg_statistic</structname></link>
    catalog.  This view allows access only to rows of
-   <structname>pg_statistic</structname> that correspond to tables the
+   <link linkend="catalog-pg-statistic"><structname>pg_statistic</structname></link> that correspond to tables the
    user has permission to read, and therefore it is safe to allow public
    read access to this view.
   </para>
@@ -12343,7 +12357,7 @@
    <structname>pg_stats</structname> is also designed to present the
    information in a more readable format than the underlying catalog
    — at the cost that its schema must be extended whenever new slot types
-   are defined for <structname>pg_statistic</structname>.
+   are defined for <link linkend="catalog-pg-statistic"><structname>pg_statistic</structname></link>.
   </para>
 
   <table>
@@ -12545,7 +12559,7 @@
    linkend="catalog-pg-statistic-ext"><structname>pg_statistic_ext</structname></link>
    and <link linkend="catalog-pg-statistic-ext-data"><structname>pg_statistic_ext_data</structname></link>
    catalogs.  This view allows access only to rows of
-   <structname>pg_statistic_ext</structname> and <structname>pg_statistic_ext_data</structname>
+   <link linkend="catalog-pg-statistic-ext"><structname>pg_statistic_ext</structname></link> and <link
linkend="catalog-pg-statistic-ext-data"><structname>pg_statistic_ext_data</structname></link>
    that correspond to tables the user has permission to read, and therefore
    it is safe to allow public read access to this view.
   </para>
@@ -12554,7 +12568,7 @@
    <structname>pg_stats_ext</structname> is also designed to present the
    information in a more readable format than the underlying catalogs
    — at the cost that its schema must be extended whenever new types
-   of extended statistics are added to <structname>pg_statistic_ext</structname>.
+   of extended statistics are added to <link
linkend="catalog-pg-statistic-ext"><structname>pg_statistic_ext</structname></link>.
   </para>
 
   <table>
-- 
2.26.2

From dfbe82db56eba85eb0e36db4c39c1d584e4b062d Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Dagfinn=20Ilmari=20Manns=C3=A5ker?= <ilmari@ilmari.org>
Date: Sun, 21 Jun 2020 14:56:21 +0100
Subject: [PATCH v3 2/2] Make SQL command names in the catlog documentation
 links

In passing, fix the initdb references to be <application> rather than
<command>, which is what we normally use.
---
 doc/src/sgml/catalogs.sgml | 114 +++++++++++++++++++------------------
 1 file changed, 58 insertions(+), 56 deletions(-)

diff --git a/doc/src/sgml/catalogs.sgml b/doc/src/sgml/catalogs.sgml
index 47d78d2ff8..fe2ffc993f 100644
--- a/doc/src/sgml/catalogs.sgml
+++ b/doc/src/sgml/catalogs.sgml
@@ -14,8 +14,8 @@
    tables.  You can drop and recreate the tables, add columns, insert
    and update values, and severely mess up your system that way.
    Normally, one should not change the system catalogs by hand, there
-   are normally SQL commands to do that.  (For example, <command>CREATE
-   DATABASE</command> inserts a row into the
+   are normally SQL commands to do that.  (For example,
+   <xref linkend="sql-createdatabase"/> inserts a row into the
    <link linkend="catalog-pg-database"><structname>pg_database</structname></link>
    catalog — and actually
    creates the database on disk.)  There are some exceptions for
@@ -1966,9 +1966,9 @@
       <para>
        Size of the on-disk representation of this table in pages (of size
        <symbol>BLCKSZ</symbol>).  This is only an estimate used by the
-       planner.  It is updated by <command>VACUUM</command>,
-       <command>ANALYZE</command>, and a few DDL commands such as
-       <command>CREATE INDEX</command>.
+       planner.  It is updated by <xref linkend="sql-vacuum"/>,
+       <xref linkend="sql-analyze"/>, and a few DDL commands such as
+       <xref linkend="sql-createindex"/>.
       </para></entry>
      </row>
 
@@ -1978,9 +1978,9 @@
       </para>
       <para>
        Number of live rows in the table.  This is only an estimate used by
-       the planner.  It is updated by <command>VACUUM</command>,
-       <command>ANALYZE</command>, and a few DDL commands such as
-       <command>CREATE INDEX</command>.
+       the planner.  It is updated by <xref linkend="sql-vacuum"/>,
+       <xref linkend="sql-analyze"/>, and a few DDL commands such as
+       <xref linkend="sql-createindex"/>.
       </para></entry>
      </row>
 
@@ -1991,9 +1991,9 @@
       <para>
        Number of pages that are marked all-visible in the table's
        visibility map.  This is only an estimate used by the
-       planner.  It is updated by <command>VACUUM</command>,
-       <command>ANALYZE</command>, and a few DDL commands such as
-       <command>CREATE INDEX</command>.
+       planner.  It is updated by <xref linkend="sql-vacuum"/>,
+       <xref linkend="sql-analyze"/>, and a few DDL commands such as
+       <xref linkend="sql-createindex"/>.
       </para></entry>
      </row>
 
@@ -2237,8 +2237,8 @@
    lazily: they are guaranteed to be true if that's the correct state, but
    may not be reset to false immediately when the condition is no longer
    true.  For example, <structfield>relhasindex</structfield> is set by
-   <command>CREATE INDEX</command>, but it is never cleared by
-   <command>DROP INDEX</command>.  Instead, <command>VACUUM</command> clears
+   <xref linkend="sql-createindex"/>, but it is never cleared by
+   <xref linkend="sql-dropindex"/>.  Instead, <xref linkend="sql-vacuum"/> clears
    <structfield>relhasindex</structfield> if it finds the table has no indexes.  This
    arrangement avoids race conditions and improves concurrency.
   </para>
@@ -2415,8 +2415,8 @@
   </para>
 
   <para>
-   User-defined constraint triggers (created with <command>CREATE CONSTRAINT
-   TRIGGER</command>) also give rise to an entry in this table.
+   User-defined constraint triggers (created with <link linkend="sql-createtrigger">
+   <command>CREATE CONSTRAINT TRIGGER</command></link>) also give rise to an entry in this table.
   </para>
 
   <para>
@@ -3421,7 +3421,7 @@
        the referenced object (see
        <link linkend="catalog-pg-extension"><structname>pg_extension</structname></link>).
        The dependent object can be dropped only via
-       <command>DROP EXTENSION</command> on the referenced object.
+       <xref linkend="sql-dropextension"/> on the referenced object.
        Functionally this dependency type acts the same as
        an <literal>INTERNAL</literal> dependency, but it's kept separate for
        clarity and to simplify <application>pg_dump</application>.
@@ -3452,7 +3452,7 @@
        There is no dependent object; this type of entry is a signal
        that the system itself depends on the referenced object, and so
        that object must never be deleted.  Entries of this type are
-       created only by <command>initdb</command>.  The columns for the
+       created only by <application>initdb</application>.  The columns for the
        dependent object contain zeroes.
       </para>
      </listitem>
@@ -4282,7 +4282,7 @@
       <para>
        If true, the index is currently valid for queries.  False means the
        index is possibly incomplete: it must still be modified by
-       <command>INSERT</command>/<command>UPDATE</command> operations, but it cannot safely
+       <xref linkend="sql-insert"/>/<xref linkend="sql-update"/> operations, but it cannot safely
        be used for queries. If it is unique, the uniqueness property is not
        guaranteed true either.
       </para></entry>
@@ -4306,7 +4306,7 @@
       </para>
       <para>
        If true, the index is currently ready for inserts.  False means the
-       index must be ignored by <command>INSERT</command>/<command>UPDATE</command>
+       index must be ignored by <xref linkend="sql-insert"/>/<xref linkend="sql-update"/>
        operations.
       </para></entry>
      </row>
@@ -4327,8 +4327,8 @@
       </para>
       <para>
        If true this index has been chosen as <quote>replica identity</quote>
-       using <command>ALTER TABLE ... REPLICA IDENTITY USING INDEX
-       ...</command>
+       using <link linkend="sql-createtable-replica-identity"><command>ALTER TABLE ...
+       REPLICA IDENTITY USING INDEX ...</command></link>
       </para></entry>
      </row>
 
@@ -4497,11 +4497,11 @@
   <para>
    Objects can have initial privileges either by having those privileges set
    when the system is initialized (by <application>initdb</application>) or when the
-   object is created during a <command>CREATE EXTENSION</command> and the
-   extension script sets initial privileges using the <command>GRANT</command>
+   object is created during a <xref linkend="sql-createextension"/> and the
+   extension script sets initial privileges using the <xref linkend="sql-grant"/>
    system.  Note that the system will automatically handle recording of the
    privileges during the extension script and that extension authors need
-   only use the <command>GRANT</command> and <command>REVOKE</command>
+   only use the <xref linkend="sql-grant"/> and <xref linkend="sql-revoke"/>
    statements in their script to have the privileges recorded.  The
    <literal>privtype</literal> column indicates if the initial privilege was
    set by <application>initdb</application> or during a
@@ -5557,10 +5557,10 @@
       </para>
       <para>
        The command type to which the policy is applied:
-       <literal>r</literal> for <command>SELECT</command>,
-       <literal>a</literal> for <command>INSERT</command>,
-       <literal>w</literal> for <command>UPDATE</command>,
-       <literal>d</literal> for <command>DELETE</command>,
+       <literal>r</literal> for <xref linkend="sql-select"/>,
+       <literal>a</literal> for <xref linkend="sql-insert"/>,
+       <literal>w</literal> for <xref linkend="sql-update"/>,
+       <literal>d</literal> for <xref linkend="sql-delete"/>,
        or <literal>*</literal> for all
       </para></entry>
      </row>
@@ -6068,7 +6068,7 @@
        <structfield>pubinsert</structfield> <type>bool</type>
       </para>
       <para>
-       If true, <command>INSERT</command> operations are replicated for
+       If true, <xref linkend="sql-insert"/> operations are replicated for
        tables in the publication.
       </para></entry>
      </row>
@@ -6078,7 +6078,7 @@
        <structfield>pubupdate</structfield> <type>bool</type>
       </para>
       <para>
-       If true, <command>UPDATE</command> operations are replicated for
+       If true, <xref linkend="sql-update"/> operations are replicated for
        tables in the publication.
       </para></entry>
      </row>
@@ -6088,7 +6088,7 @@
        <structfield>pubdelete</structfield> <type>bool</type>
       </para>
       <para>
-       If true, <command>DELETE</command> operations are replicated for
+       If true, <xref linkend="sql-delete"/> operations are replicated for
        tables in the publication.
       </para></entry>
      </row>
@@ -6098,7 +6098,7 @@
        <structfield>pubtruncate</structfield> <type>bool</type>
       </para>
       <para>
-       If true, <command>TRUNCATE</command> operations are replicated for
+       If true, <xref linkend="sql-truncate"/> operations are replicated for
        tables in the publication.
       </para></entry>
      </row>
@@ -6401,9 +6401,9 @@
        <structfield>ev_type</structfield> <type>char</type>
       </para>
       <para>
-       Event type that the rule is for: 1 = <command>SELECT</command>, 2 =
-       <command>UPDATE</command>, 3 = <command>INSERT</command>, 4 =
-       <command>DELETE</command>
+       Event type that the rule is for: 1 = <xref linkend="sql-select"/>, 2 =
+       <xref linkend="sql-update"/>, 3 = <xref linkend="sql-insert"/>, 4 =
+       <xref linkend="sql-delete"/>
       </para></entry>
      </row>
 
@@ -6825,7 +6825,7 @@
        There is no dependent object; this type of entry is a signal
        that the system itself depends on the referenced object, and so
        that object must never be deleted.  Entries of this type are
-       created only by <command>initdb</command>.  The columns for the
+       created only by <application>initdb</application>.  The columns for the
        dependent object contain zeroes.
       </para>
      </listitem>
@@ -7329,9 +7329,9 @@
 
   <para>
    The <structname>pg_statistic_ext</structname> entry is filled in
-   completely during <command>CREATE STATISTICS</command>, but the actual
+   completely during <xref linkend="sql-createstatistics"/>, but the actual
    statistical values are not computed then.
-   Subsequent <command>ANALYZE</command> commands compute the desired values
+   Subsequent <xref linkend="sql-analyze"/> commands compute the desired values
    and populate an entry in the
    <link linkend="catalog-pg-statistic-ext-data"><structname>pg_statistic_ext_data</structname></link>
    catalog.
@@ -7572,8 +7572,9 @@
 
   <para>
    This catalog only contains tables known to the subscription after running
-   either <command>CREATE SUBSCRIPTION</command> or
-   <command>ALTER SUBSCRIPTION ... REFRESH PUBLICATION</command>.
+   either <xref linkend="sql-createsubscription"/> or
+   <link linkend="sql-altersubscription"><command>ALTER SUBSCRIPTION ... REFRESH
+   PUBLICATION</command></link>.
   </para>
 
   <table>
@@ -8817,7 +8818,7 @@
        (references <link
linkend="catalog-pg-proc"><structname>pg_proc</structname></link>.<structfield>oid</structfield>)
       </para>
       <para>
-       Custom <command>ANALYZE</command> function, or 0 to use the standard function
+       Custom <xref linkend="sql-analyze"/> function, or 0 to use the standard function
       </para></entry>
      </row>
 
@@ -10178,7 +10179,7 @@
        <structfield>indexdef</structfield> <type>text</type>
       </para>
       <para>
-       Index definition (a reconstructed <command>CREATE INDEX</command>
+       Index definition (a reconstructed <xref linkend="sql-createindex"/>
        command)
       </para></entry>
      </row>
@@ -10633,7 +10634,7 @@
        <structfield>definition</structfield> <type>text</type>
       </para>
       <para>
-       Materialized view definition (a reconstructed <command>SELECT</command> query)
+       Materialized view definition (a reconstructed <xref linkend="sql-select"/> query)
       </para></entry>
      </row>
     </tbody>
@@ -10803,7 +10804,7 @@
       <para>
        The query string submitted by the client to create this
        prepared statement. For prepared statements created via SQL,
-       this is the <command>PREPARE</command> statement submitted by
+       this is the <xref linkend="sql-prepare"/> statement submitted by
        the client. For prepared statements created via the
        frontend/backend protocol, this is the text of the prepared
        statement itself.
@@ -10837,7 +10838,7 @@
       </para>
       <para>
        <literal>true</literal> if the prepared statement was created
-       via the <command>PREPARE</command> SQL command;
+       via the <xref linkend="sql-prepare"/> SQL command;
        <literal>false</literal> if the statement was prepared via the
        frontend/backend protocol
       </para></entry>
@@ -11935,7 +11936,7 @@
        <structfield>reset_val</structfield> <type>text</type>
       </para>
       <para>
-       Value that <command>RESET</command> would reset the parameter to
+       Value that <xref linkend="sql-reset"/> would reset the parameter to
        in the current session
       </para></entry>
      </row>
@@ -11993,7 +11994,7 @@
       These settings cannot be changed directly; they reflect internally
       determined values.  Some of them may be adjustable by rebuilding the
       server with different configuration options, or by changing options
-      supplied to <command>initdb</command>.
+      supplied to <application>initdb</application>.
      </para>
     </listitem>
    </varlistentry>
@@ -12068,7 +12069,7 @@
     <listitem>
      <para>
       These settings can be set from <filename>postgresql.conf</filename>,
-      or within a session via the <command>SET</command> command; but only superusers
+      or within a session via the <xref linkend="sql-set"/> command; but only superusers
       can change them via <command>SET</command>.  Changes in
       <filename>postgresql.conf</filename> will affect existing sessions
       only if no session-local value has been established with <command>SET</command>.
@@ -12081,7 +12082,7 @@
     <listitem>
      <para>
       These settings can be set from <filename>postgresql.conf</filename>,
-      or within a session via the <command>SET</command> command.  Any user is
+      or within a session via the <xref linkend="sql-set"/> command.  Any user is
       allowed to change their session-local value.  Changes in
       <filename>postgresql.conf</filename> will affect existing sessions
       only if no session-local value has been established with <command>SET</command>.
@@ -12097,7 +12098,7 @@
 
   <para>
    The <structname>pg_settings</structname> view cannot be inserted into or
-   deleted from, but it can be updated.  An <command>UPDATE</command> applied
+   deleted from, but it can be updated.  An <xref linkend="sql-update"/> applied
    to a row of <structname>pg_settings</structname> is equivalent to executing
    the <xref linkend="sql-set"/> command on that named
    parameter. The change only affects the value used by the current
@@ -12441,7 +12442,7 @@
        If greater than zero, the estimated number of distinct values in the
        column.  If less than zero, the negative of the number of distinct
        values divided by the number of rows.  (The negated form is used when
-       <command>ANALYZE</command> believes that the number of distinct values is
+       <xref linkend="sql-analyze"/> believes that the number of distinct values is
        likely to increase as the table grows; the positive form is used when
        the column seems to have a fixed number of possible values.)  For
        example, -1 indicates a unique column in which the number of distinct
@@ -12539,7 +12540,8 @@
 
   <para>
    The maximum number of entries in the array fields can be controlled on a
-   column-by-column basis using the <command>ALTER TABLE SET STATISTICS</command>
+   column-by-column basis using the <link linkend="sql-altertable"><command>ALTER
+   TABLE SET STATISTICS</command></link>
    command, or globally by setting the
    <xref linkend="guc-default-statistics-target"/> run-time parameter.
   </para>
@@ -12664,7 +12666,7 @@
        than zero, the estimated number of distinct values in the combination.
        If less than zero, the negative of the number of distinct values divided
        by the number of rows.
-       (The negated form is used when <command>ANALYZE</command> believes that
+       (The negated form is used when <xref linkend="sql-analyze"/> believes that
        the number of distinct values is likely to increase as the table grows;
        the positive form is used when the column seems to have a fixed number
        of possible values.)  For example, -1 indicates a unique combination of
@@ -12729,8 +12731,8 @@
 
   <para>
    The maximum number of entries in the array fields can be controlled on a
-   column-by-column basis using the <command>ALTER TABLE SET STATISTICS</command>
-   command, or globally by setting the
+   column-by-column basis using the <link linkend="sql-altertable"><command>ALTER
+   TABLE SET STATISTICS</command></link> command, or globally by setting the
    <xref linkend="guc-default-statistics-target"/> run-time parameter.
   </para>
 
@@ -13292,7 +13294,7 @@
        <structfield>definition</structfield> <type>text</type>
       </para>
       <para>
-       View definition (a reconstructed <command>SELECT</command> query)
+       View definition (a reconstructed <xref linkend="sql-select"/> query)
       </para></entry>
      </row>
     </tbody>
-- 
2.26.2