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