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

Hi Fabien,

Fabien COELHO <coelho@cri.ensmp.fr> writes:

>> It's the first mention in the introductory paragraph of _each_ catalog
>> table/view page, not the first mention in the entire catalogs.sgml file.
>> E.g. https://www.postgresql.org/docs/current/catalog-pg-aggregate.html
>> has two mentions of pg_proc one word apart:
>>
>>   Each entry in pg_aggregate is an extension of an entry in pg_proc. The
>>   pg_proc entry carries the aggregate's name, …
>>
>> I didn't think there was much point in linkifying both in that case, and
>> other similar situations.
>
> The point is that the user reads a sentence, attempts to jump but
> sometimes can't, because the is not the first occurrence. I'd go for all
> mentions of another relation should be link.

Okay, I'll make them all links, except the pg_aggregate aggfnoid column,
which I've changed from "pg_proc OID of the aggregate function" to just
"OID of the agregate function", since pg_proc is linked immediately
prior in the "references" section, and we generally don't mention the
catalog table again in similar cases elsehwere.

> Alse, ISTM you missed some, maybe you could consider adding them? eg
> pg_database in the very first paragraph of the file, pg_attrdef in
> pg_attribute description, quite a few in pg_class…

Yes, I only looked at the intro paragraphs of the per-catalog pages, not
the overview section nor the text after the column tables.  I've gone
through them all now and linked them.  Updated patch attached.

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


From b2940b93f5ed17c0e739d6ed0c9411a44bd87428 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 v2 1/2] Add missing cross-links in system catalog
 documentation

This makes all mentions of other system catalogs and views 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 | 142 ++++++++++++++++++++-----------------
 1 file changed, 78 insertions(+), 64 deletions(-)

diff --git a/doc/src/sgml/catalogs.sgml b/doc/src/sgml/catalogs.sgml
index 700271fd40..051fa7d361 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 <link linkend="catalog-pg-proc"><structname>pg_proc</structname></link> 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,9 +1405,9 @@
    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.
+   later dropped, and so there is no <link linkend="catalog-pg-type"><structname>pg_type</structname></link> row
anymore.
    <structfield>attlen</structfield> and the other fields can be used
    to interpret the contents of a row of the table.
   </para>
@@ -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
+       <link
linkend="catalog-pg-attribute"><structname>pg_attribute</structname></link>.<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