Thread: Missing links between system catalog documentation pages

Missing links between system catalog documentation pages

From
ilmari@ilmari.org (Dagfinn Ilmari Mannsåker)
Date:
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


[PATCH] Missing links between system catalog documentation pages

From
ilmari@ilmari.org (Dagfinn Ilmari Mannsåker)
Date:
ilmari@ilmari.org (Dagfinn Ilmari Mannsåker) writes:

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

bump...

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



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

From
ilmari@ilmari.org (Dagfinn Ilmari Mannsåker)
Date:
ilmari@ilmari.org (Dagfinn Ilmari Mannsåker) writes:

> ilmari@ilmari.org (Dagfinn Ilmari Mannsåker) writes:
>
>> 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.
>
> bump...

Added to the current commitfest:

https://commitfest.postgresql.org/28/2599/

- 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



Re: [PATCH] Missing links between system catalog documentationpages

From
Fabien COELHO
Date:
Hello Dagfinn,

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

Why only the first mention? It seems unlikely that I would ever read such 
chapter linearly, and even so that I would want to jump especially on the 
first occurrence but not on others, so ISTM that it should be done all 
mentions?

-- 
Fabien.



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

From
ilmari@ilmari.org (Dagfinn Ilmari Mannsåker)
Date:
Fabien COELHO <coelho@cri.ensmp.fr> writes:

> Hello Dagfinn,
>
>>> 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.
>
> Why only the first mention? It seems unlikely that I would ever read
> such chapter linearly, and even so that I would want to jump especially
> on the first occurrence but not on others, so ISTM that it should be
> done all mentions?

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.

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



Re: [PATCH] Missing links between system catalog documentationpages

From
Fabien COELHO
Date:
Hello Dagfinn,

>>>> The attached patch

applies cleanly, doc generation is ok. I'm ok with adding such links 
systematically.

>>>> 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.
>>
>> Why only the first mention? It seems unlikely that I would ever read
>> such chapter linearly, and even so that I would want to jump especially
>> on the first occurrence but not on others, so ISTM that it should be
>> done all mentions?
>
> 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.

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…

-- 
Fabien.

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

From
ilmari@ilmari.org (Dagfinn Ilmari Mannsåker)
Date:
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


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

From
Tom Lane
Date:
Fabien COELHO <coelho@cri.ensmp.fr> writes:
>> 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.

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.

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.

            regards, tom lane



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

From
Alvaro Herrera
Date:
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 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.

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



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

From
ilmari@ilmari.org (Dagfinn Ilmari Mannsåker)
Date:
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


Re: [PATCH] Missing links between system catalog documentationpages

From
Fabien COELHO
Date:
Hello Tom,

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

Hmmm. That looks like an underlying CSS issue, not that links are 
intrinsically bad.

I find it annoying that the same thing appears differently from one line 
to the next. It seems I'm the only one who likes things to be uniform, 
though.

> and for users of screen-reader software.

I do not know about those, and what constraints it puts on markup.

-- 
Fabien.



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

From
Peter Eisentraut
Date:
On 2020-06-21 19:49, Dagfinn Ilmari Mannsåker wrote:
> 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.

Committed after some rebasing and tweaking.

-- 
Peter Eisentraut              http://www.2ndQuadrant.com/
PostgreSQL Development, 24x7 Support, Remote DBA, Training & Services



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

From
ilmari@ilmari.org (Dagfinn Ilmari Mannsåker)
Date:
Hi Peter,

Peter Eisentraut <peter.eisentraut@2ndquadrant.com> writes:

> On 2020-06-21 19:49, Dagfinn Ilmari Mannsåker wrote:
>> 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.
>
> Committed after some rebasing and tweaking.

Thanks!

I just noticed that both this and the command link patch modified the
same sentence about CREATE DATABASE and pg_database, so those changes
seem to have been lost in the merge.  Attached is a follow-up patch that
adds them both.

- ilmari
-- 
"The surreality of the universe tends towards a maximum" -- Skud's Law
"Never formulate a law or axiom that you're not prepared to live with
 the consequences of."                              -- Skud's Meta-Law

From d043e64c925a21d42bfd28e6c4ca2e44e4b4d356 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 two more missing command and catalog cross-links

The two earlier doc patches both modified this paragraph, so these two
changes appear to have been lost while resolving the conflict.
---
 doc/src/sgml/catalogs.sgml | 15 ++++++++-------
 1 file changed, 8 insertions(+), 7 deletions(-)

diff --git a/doc/src/sgml/catalogs.sgml b/doc/src/sgml/catalogs.sgml
index 508bea3bc6..6f2e0d19dc 100644
--- a/doc/src/sgml/catalogs.sgml
+++ b/doc/src/sgml/catalogs.sgml
@@ -14,13 +14,14 @@
    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
-   <structname>pg_database</structname> 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
-   of the system catalogs is ever decreasing.
+   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 particularly esoteric operations, but many
+   of those have been made available as SQL commands over time, and so
+   the need for direct manipulation of the system catalogs is ever
+   decreasing.
   </para>
 
  <sect1 id="catalogs-overview">
-- 
2.27.0


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

From
Peter Eisentraut
Date:
On 2020-09-03 17:40, Dagfinn Ilmari Mannsåker wrote:
> I just noticed that both this and the command link patch modified the
> same sentence about CREATE DATABASE and pg_database, so those changes
> seem to have been lost in the merge.  Attached is a follow-up patch that
> adds them both.

I think in those cases I would leave off the link.  The mentions there 
are just examples of the relationship between a catalog and a command. 
It doesn't mean you are meant to look up the specific catalog and command.

-- 
Peter Eisentraut              http://www.2ndQuadrant.com/
PostgreSQL Development, 24x7 Support, Remote DBA, Training & Services