Missing links between system catalog documentation pages

Hi hackers,

While browsing the system catalog docs earlier I noticed that a lot of
them mention other catalogs or views in the introductory paragrah
without hyperlinking them.  Now, most of these are linked in the
"references" column in the table, but some, like pg_proc's mention of
pg_aggregate have no direct links at all.

The attached patch makes the first mention of another system catalog or
view (as well as pg_hba.conf in pg_hba_file_lines) a link, for easier
navigation.

- ilmari
-- 
- Twitter seems more influential [than blogs] in the 'gets reported in
  the mainstream press' sense at least.               - Matt McLeod
- That'd be because the content of a tweet is easier to condense down
  to a mainstream media article.                      - Calle Dybedahl

From bd0e807264e664034ae0cee62f77104da1da57a6 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] Add missing cross-links in system catalog documentation

This makes the first mention of another system catalog or view in
the introductory paragraph a system catalog or view a hyperlink, for
easier navigation.  Some of them are also linked because of columns
referencing them, but this avoids having to hunt for that.

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 | 69 ++++++++++++++++++++++----------------
 1 file changed, 41 insertions(+), 28 deletions(-)

diff --git a/doc/src/sgml/catalogs.sgml b/doc/src/sgml/catalogs.sgml
index 9851ef2713..8df73e3ba4 100644
--- a/doc/src/sgml/catalogs.sgml
+++ b/doc/src/sgml/catalogs.sgml
@@ -381,9 +381,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>
@@ -1099,7 +1100,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>
 
@@ -1835,14 +1837,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>
@@ -2404,7 +2408,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>
 
@@ -4094,11 +4099,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>
@@ -4160,7 +4167,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>
@@ -5625,7 +5632,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 +6562,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>
@@ -7338,7 +7346,8 @@
 
   <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>
@@ -9964,8 +9973,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 +10216,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.
@@ -10943,8 +10955,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>
-- 
2.26.2