From: Tom Lane <tgl@sss.pgh.pa.us>
To: Daniel Gustafsson <daniel@yesql.se>
Cc: mpnash@google.com
Cc: pgsql-docs@lists.postgresql.org
Subject: Re: Typo/wording on https://www.postgresql.org/docs/current/catalog-pg-class.html
Date: Fri, 22 Sep 2023 13:04:02 -0400
Message-ID: <1016844.1695402242@sss.pgh.pa.us> (raw)
In-Reply-To: <520464.1695217750@sss.pgh.pa.us>
References: <169518739902.3727338.4793815593763320945@wrigleys.postgresql.org>
<A4F03320-8592-4BF6-8C22-B81CF681BD96@yesql.se>
<520464.1695217750@sss.pgh.pa.us>
I wrote:
> "Most" here is good English, although I concede it's a slightly
> old-fashioned usage. Maybe it'd be clearer to just remove the
> word altogether.
> If we were going to touch this sentence I'd worry about some other
> things too. Use of "catalogs" as a verb is probably not the greatest
> choice right here, since one could easily think that the verb is
> missing and what was meant was "pg_class lists catalogs, [user]
> tables, and ...". Also, I think that the reference to special
> relations is obsolete --- we don't list any relkind for that anymore.
> What probably does deserve to be called out in place of those is
> composite types, since their appearance in pg_class might be pretty
> surprising to newbies.
Hmm, I must have been looking at some old version of the docs, because
when I went to prepare a draft patch I found that those last couple of
points were addressed some time ago. I think we just need some slightly
better wording here rather than any change of technical content.
I propose the attached. (I also modified the para's last sentence to
speak of "kind" not "type", for consistency with the relkind field name
and the rest of the para.)
regards, tom lane
Attachments:
[text/x-diff] tweak-description-of-pg_class.patch (1.2K, ../1016844.1695402242@sss.pgh.pa.us/2-tweak-description-of-pg_class.patch)
download | inline diff:diff --git a/doc/src/sgml/catalogs.sgml b/doc/src/sgml/catalogs.sgmlindex d17ff51e28..e09adb45e4 100644--- a/doc/src/sgml/catalogs.sgml+++ b/doc/src/sgml/catalogs.sgml@@ -1893,8 +1893,8 @@ SCRAM-SHA-256$<replaceable><iteration count></replaceable>:<replaceable>&l
</indexterm>
<para>
- The catalog <structname>pg_class</structname> catalogs tables and most- everything else that has columns or is otherwise similar to a+ The catalog <structname>pg_class</structname> describes tables and+ other objects that have columns or are 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
@@ -1902,8 +1902,8 @@ SCRAM-SHA-256$<replaceable><iteration count></replaceable>:<replaceable>&l
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.+ <quote>relations</quote>. Not all of <structname>pg_class</structname>'s+ columns are meaningful for all relation kinds.
</para>
<table>
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Reply to all the recipients using the --to and --cc options:
reply via email
To: pgsql-docs@postgresql.org
Cc: tgl@sss.pgh.pa.us, daniel@yesql.se, mpnash@google.com, pgsql-docs@lists.postgresql.org
Subject: Re: Typo/wording on https://www.postgresql.org/docs/current/catalog-pg-class.html
In-Reply-To: <1016844.1695402242@sss.pgh.pa.us>
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
This inbox is served by DDX for PostgreSQL; see mirroring instructions
for how to clone and mirror all data and code used for this inbox