doc: Add missing cross-links in system catalog documentation
authorPeter Eisentraut
Thu, 3 Sep 2020 11:15:53 +0000 (13:15 +0200)
committerPeter Eisentraut
Thu, 3 Sep 2020 11:17:22 +0000 (13:17 +0200)
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.

Author: Dagfinn Ilmari Mannsåker 
Discussion: https://www.postgresql.org/message-id/flat/[email protected]

doc/src/sgml/catalogs.sgml

index 1d1b8ce8fb1269b0377ee0238ea848fd78011109..85084a7c2333a09eabd3b95125937dc4095a34cd 100644 (file)
    sumcount, and
    max.  Each entry in
    pg_aggregate is an extension of an entry
-   in pg_proc.  The pg_proc
-   entry carries the aggregate's name, input and output data types, and
-   other information that is similar to ordinary functions.
+   in pg_proc.
+   The pg_proc entry carries the aggregate's name,
+   input and output data types, and other information that is similar to
+   ordinary functions.
   
 
   
    catalog structure for performance reasons).  Also,
    amoplefttype and amoprighttype must match
    the oprleft and oprright fields of the
-   referenced <structname>pg_operator> entry.
+   referenced <link linkend="catalog-pg-operator">pg_operator> entry.
   
 
  
    table columns.  There will be exactly one
    pg_attribute row for every column in every
    table in the database.  (There will also be attribute entries for
-   indexes, and indeed all objects that have pg_class
+   indexes, and indeed all objects that have
+   pg_class
    entries.)
   
 
       
        This column has a default expression or generation expression, in which
        case there will be a corresponding entry in the
-       <structname>pg_attrdef> catalog that actually defines the
+       <link linkend="catalog-pg-attrdef">pg_attrdef> catalog that actually defines the
        expression.  (Check attgenerated to
        determine whether this is a default or a generation expression.)
       
    In a dropped column's pg_attribute entry,
    atttypid is reset to zero, but
    attlen and the other fields copied from
-   <structname>pg_type> are still valid.  This arrangement is needed
+   <link linkend="catalog-pg-type">pg_type> 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 pg_type row anymore.
    attlen and the other fields can be used
@@ -1836,13 +1838,15 @@ SCRAM-SHA-256$<iteration count>:&l
   
    The catalog pg_class catalogs tables and most
    everything else that has columns or is otherwise similar to a
-   table.  This includes indexes (but see also
-   pg_index), sequences (but see also
-   pg_sequence), views, materialized
-   views, composite types, and TOAST tables; see relkind.
-   Below, when we mean all of these
-   kinds of objects we speak of relations.  Not all
-   columns are meaningful for all relation types.
+   table.  This includes indexes (but see also 
+   linkend="catalog-pg-index">pg_index),
+   sequences (but see also 
+   linkend="catalog-pg-sequence">pg_sequence),
+   views, materialized views, composite types, and TOAST tables;
+   see relkind.
+   Below, when we mean all of these kinds of objects we speak of
+   relations.  Not all columns are meaningful for all relation
+   types.
   
 
   
@@ -2024,7 +2028,7 @@ SCRAM-SHA-256$<iteration count>:&l
       
       
        True if this table is shared across all databases in the cluster.  Only
-       certain system catalogs (such as <structname>pg_database>)
+       certain system catalogs (such as <link linkend="catalog-pg-database">pg_database>)
        are shared.
       
      
@@ -2064,8 +2068,8 @@ SCRAM-SHA-256$<iteration count>:&l
       
        Number of user columns in the relation (system columns not
        counted).  There must be this many corresponding entries in
-       <structname>pg_attribute>.  See also
-       <literal>pg_attribute.attnum>.
+       <link linkend="catalog-pg-attribute">pg_attribute>.  See also
+       <structname>pg_attribute.attnum>.
       
      
 
@@ -2409,7 +2413,8 @@ SCRAM-SHA-256$<iteration count>:&l
    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 pg_attribute
+   Not-null constraints are represented in the
+   pg_attribute
    catalog, not here.
   
 
@@ -2712,7 +2717,7 @@ SCRAM-SHA-256$<iteration count>:&l
    For other cases, a zero appears in conkey
    and the associated index must be consulted to discover the expression
    that is constrained.  (conkey thus has the
-   same contents as <structname>pg_index>.indkey for the
+   same contents as <link linkend="catalog-pg-index">pg_index>.indkey for the
    index.)
   
 
@@ -2980,7 +2985,7 @@ SCRAM-SHA-256$<iteration count>:&l
        track whether the database needs to be vacuumed in order to prevent
        transaction ID wraparound or to allow pg_xact to be shrunk.
        It is the minimum of the per-table
-       <structname>pg_class>.relfrozenxid values.
+       <link linkend="catalog-pg-class">pg_class>.relfrozenxid values.
       
      
 
@@ -2994,7 +2999,7 @@ SCRAM-SHA-256$<iteration count>:&l
        track whether the database needs to be vacuumed in order to prevent
        multixact ID wraparound or to allow pg_multixact to be shrunk.
        It is the minimum of the per-table
-       <structname>pg_class>.relminmxid values.
+       <link linkend="catalog-pg-class">pg_class>.relminmxid values.
       
      
 
@@ -3006,7 +3011,7 @@ SCRAM-SHA-256$<iteration count>:&l
       
        The default tablespace for the database.
        Within this database, all tables for which
-       <structname>pg_class>.reltablespace is zero
+       <link linkend="catalog-pg-class">pg_class>.reltablespace is zero
        will be stored in this tablespace; in particular, all the non-shared
        system catalogs will be there.
       
@@ -3605,7 +3610,7 @@ SCRAM-SHA-256$<iteration count>:&l
        (references pg_type.oid)
       
       
-       The OID of the <structname>pg_type> entry owning this enum value
+       The OID of the <link linkend="catalog-pg-type">pg_type> entry owning this enum value
       
      
 
@@ -4100,8 +4105,9 @@ SCRAM-SHA-256$<iteration count>:&l
   
    The catalog pg_foreign_table contains
    auxiliary information about foreign tables.  A foreign table is
-   primarily represented by a pg_class entry,
-   just like a regular table.  Its pg_foreign_table
+   primarily represented by a
+   pg_class
+   entry, just like a regular table.  Its pg_foreign_table
    entry contains the information that is pertinent only to foreign tables
    and not any other kind of relation.
   
@@ -4127,7 +4133,7 @@ SCRAM-SHA-256$<iteration count>:&l
        (references pg_class.oid)
       
       
-       OID of the pg_class> entry for this foreign table
+       The OID of the pg_class> entry for this foreign table
       
      
 
@@ -4165,7 +4171,7 @@ SCRAM-SHA-256$<iteration count>:&l
   
    The catalog pg_index contains part of the information
    about indexes.  The rest is mostly in
-   <structname>pg_class>.
+   <link linkend="catalog-pg-class">pg_class>.
   
 
   
@@ -4189,7 +4195,7 @@ SCRAM-SHA-256$<iteration count>:&l
        (references pg_class.oid)
       
       
-       The OID of the <structname>pg_class> entry for this index
+       The OID of the <link linkend="catalog-pg-class">pg_class> entry for this index
       
      
 
@@ -4199,7 +4205,7 @@ SCRAM-SHA-256$<iteration count>:&l
        (references pg_class.oid)
       
       
-       The OID of the <structname>pg_class> entry for the table this index is for
+       The OID of the <link linkend="catalog-pg-class">pg_class> entry for the table this index is for
       
      
 
@@ -5400,7 +5406,7 @@ SCRAM-SHA-256$<iteration count>:&l
        (references pg_class.oid)
       
       
-       The OID of the <structname>pg_class> entry for this partitioned table
+       The OID of the <link linkend="catalog-pg-class">pg_class> entry for this partitioned table
       
      
 
@@ -5429,7 +5435,7 @@ SCRAM-SHA-256$<iteration count>:&l
        (references pg_class.oid)
       
       
-       The OID of the <structname>pg_class> entry for the default partition
+       The OID of the <link linkend="catalog-pg-class">pg_class> entry for the default partition
        of this partitioned table, or zero if this partitioned table does not
        have a default partition.
       
@@ -5609,7 +5615,7 @@ SCRAM-SHA-256$<iteration count>:&l
   
    
     Policies stored in pg_policy are applied only when
-    <structname>pg_class>.relrowsecurity is set for
+    <link linkend="catalog-pg-class">pg_class>.relrowsecurity is set for
     their table.
    
   
@@ -5634,7 +5640,7 @@ SCRAM-SHA-256$<iteration count>:&l
   
    If prokind indicates that the entry is for an
    aggregate function, there should be a matching row in
-   <structfield>pg_aggregate>.
+   <link linkend="catalog-pg-aggregate">pg_aggregate>.
   
 
   
@@ -6564,7 +6570,8 @@ SCRAM-SHA-256$<iteration count>:&l
   
    The catalog pg_sequence contains information about
    sequences.  Some of the information about sequences, such as the name and
-   the schema, is in pg_class.
+   the schema, is in
+   pg_class
   
 
   
@@ -6588,7 +6595,7 @@ SCRAM-SHA-256$<iteration count>:&l
        (references pg_class.oid)
       
       
-       The OID of the <structname>pg_class> entry for this sequence
+       The OID of the <link linkend="catalog-pg-class">pg_class> entry for this sequence
       
      
 
@@ -7347,13 +7354,14 @@ SCRAM-SHA-256$<iteration count>:&l
 
   
    The catalog pg_statistic_ext_data
-   holds data for extended planner statistics defined in pg_statistic_ext.
+   holds data for extended planner statistics defined in
+   pg_statistic_ext.
    Each row in this catalog corresponds to a statistics object
    created with .
   
 
   
-   Like <structname>pg_statistic>,
+   Like <link linkend="catalog-pg-statistic">pg_statistic>,
    pg_statistic_ext_data 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
@@ -7361,7 +7369,7 @@ SCRAM-SHA-256$<iteration count>:&l
    pg_stats_ext
    is a publicly readable view
    on pg_statistic_ext_data (after joining
-   with <structname>pg_statistic_ext>) that only exposes
+   with <link linkend="catalog-pg-statistic-ext">pg_statistic_ext>) that only exposes
    information about those tables and columns that are readable by the
    current user.
   
@@ -7960,7 +7968,7 @@ SCRAM-SHA-256$<iteration count>:&l
        (references pg_constraint.oid)
       
       
-       The <structname>pg_constraint> entry associated with the trigger, if any
+       The <link linkend="catalog-pg-constraint">pg_constraint> entry associated with the trigger, if any
       
      
 
@@ -8058,7 +8066,7 @@ SCRAM-SHA-256$<iteration count>:&l
     When tgconstraint is nonzero,
     tgconstrrelidtgconstrindid,
     tgdeferrable, and tginitdeferred are
-    largely redundant with the referenced <structname>pg_constraint> entry.
+    largely redundant with the referenced <link linkend="catalog-pg-constraint">pg_constraint> 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.
@@ -8205,7 +8213,7 @@ SCRAM-SHA-256$<iteration count>:&l
        (references pg_ts_config.oid)
       
       
-       The OID of the <structname>pg_ts_config> entry owning this map entry
+       The OID of the <link linkend="catalog-pg-ts-config">pg_ts_config> entry owning this map entry
       
      
 
@@ -8719,11 +8727,11 @@ SCRAM-SHA-256$<iteration count>:&l
       
        If this is a composite type (see
        typtype), then this column points to
-       the <structname>pg_class> entry that defines the
+       the <link linkend="catalog-pg-class">pg_class> entry that defines the
        corresponding table.  (For a free-standing composite type, the
-       <structname>pg_class> entry doesn't really represent
+       <link linkend="catalog-pg-class">pg_class> entry doesn't really represent
        a table, but it is needed anyway for the type's
-       <structname>pg_attribute> entries to link to.)
+       <link linkend="catalog-pg-attribute">pg_attribute> entries to link to.)
        Zero for non-composite types.
       
      
@@ -10112,8 +10120,9 @@ SCRAM-SHA-256$<iteration count>:&l
 
   
    The view pg_hba_file_rules provides a summary of
-   the contents of the client authentication configuration
-   file, pg_hba.conf.  A row appears in this view for each
+   the contents of the client authentication configuration file,
+   pg_hba.conf.
+   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.
   
@@ -10354,8 +10363,8 @@ SCRAM-SHA-256$<iteration count>:&l
    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> or
-   <structname>pg_depend>).  Also, the right to extend a
+   in the same way as in <link linkend="catalog-pg-description">pg_description> or
+   <link linkend="catalog-pg-depend">pg_depend>).  Also, the right to extend a
    relation is represented as a separate lockable object, as is the right to
    update pg_database.datfrozenxid.
    Also, advisory locks can be taken on numbers that have
@@ -10597,7 +10606,7 @@ SCRAM-SHA-256$<iteration count>:&l
    pg_locks provides a global view of all locks
    in the database cluster, not only those relevant to the current database.
    Although its relation column can be joined
-   against <structname>pg_class>.oid to identify locked
+   against <link linkend="catalog-pg-class">pg_class>.oid to identify locked
    relations, this will only work correctly for relations in the current
    database (those for which the database column
    is either the current database's OID or zero).
@@ -11112,8 +11121,9 @@ SELECT * FROM pg_locks pl LEFT JOIN pg_prepared_xacts ppx
   
    The view pg_publication_tables provides
    information about the mapping between publications and the tables they
-   contain.  Unlike the underlying
-   catalog pg_publication_rel, this view expands
+   contain.  Unlike the underlying catalog
+   pg_publication_rel,
+   this view expands
    publications defined as FOR ALL TABLES, so for such
    publications there will be a row for each eligible table.
   
@@ -11688,7 +11698,7 @@ SELECT * FROM pg_locks pl LEFT JOIN pg_prepared_xacts ppx
   
    The pg_rules view excludes the ON SELECT rules
    of views and materialized views; those can be seen in
-   <structname>pg_views and pg_matviews>.
+   <link linkend="view-pg-views">pg_views and pg_matviews>.
   
 
  
@@ -12517,7 +12527,7 @@ SELECT * FROM pg_locks pl LEFT JOIN pg_prepared_xacts ppx
    the information stored in the 
    linkend="catalog-pg-statistic">pg_statistic
    catalog.  This view allows access only to rows of
-   <structname>pg_statistic> that correspond to tables the
+   <link linkend="catalog-pg-statistic">pg_statistic> that correspond to tables the
    user has permission to read, and therefore it is safe to allow public
    read access to this view.
   
@@ -12526,7 +12536,7 @@ SELECT * FROM pg_locks pl LEFT JOIN pg_prepared_xacts ppx
    pg_stats 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>.
+   are defined for <link linkend="catalog-pg-statistic">pg_statistic>.
   
 
   
@@ -12728,7 +12738,7 @@ SELECT * FROM pg_locks pl LEFT JOIN pg_prepared_xacts ppx
    linkend="catalog-pg-statistic-ext">pg_statistic_ext
    and pg_statistic_ext_data
    catalogs.  This view allows access only to rows of
-   <structname>pg_statistic_ext and pg_statistic_ext_data>
+   <link linkend="catalog-pg-statistic-ext">pg_statistic_ext and pg_statistic_ext_data>
    that correspond to tables the user has permission to read, and therefore
    it is safe to allow public read access to this view.
   
@@ -12737,7 +12747,7 @@ SELECT * FROM pg_locks pl LEFT JOIN pg_prepared_xacts ppx
    pg_stats_ext 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>.
+   of extended statistics are added to <link linkend="catalog-pg-statistic-ext">pg_statistic_ext>.