Re: Documentation - chapter 52, system catalogs

From: Jürgen Purtz <juergen(at)purtz(dot)de>
To: pgsql-docs(at)lists(dot)postgresql(dot)org, daelhithe(at)hotmail(dot)com
Subject: Re: Documentation - chapter 52, system catalogs
Date: 2020-05-05 10:20:44
Message-ID: aecbf4cf-9717-f83c-744e-4ed074989037@purtz.de
Views: Raw Message | Whole Thread | Download mbox | Resend email
Thread:
Lists: pgsql-docs

On 04.05.20 17:23, PG Doc comments form wrote:
> The following documentation comment has been logged on the website:
>
> Page: https://www.postgresql.org/docs/11/catalogs-overview.html
> Description:
>
> The documentation for chapter 52 does not clearly identify the schema
> associated with the system catalogs in either the chapter header or overview
> sections; had I not stumbled across a reference in the documentation for the
> postgres_fdw to the pg_catalog search path, I would have been unable to
> reference the content in those catalogs via foreign data wrappers, and
> although the majority of the content has been exposed via the
> information_schema views and tables, there remain a few elements of interest
> that appear to only exist in the pg_catalog qualified content.

I think that the topic "fdw" is only a symptom, not the real reason for
the confusion. We can improve the chapters "System Catalog" and
"Information Schema" in general by centralizing some already existing
paragraphs in the "Overview" chapter and adding some more explanations.
The attached patch contains:

- for "System Catalog": moving paragraphs from bottom of 51. to top of
51.1. (in PG 11 it is chapter 52); explanation that "System Catalog" is
a synonym for a concrete schema and its tables.

- for "Information Schema": moving paragraphs from bottom of 36. to
middle of 36.1. ; an explanation that it relies on the system catalog;
change the title of 36.1. to "Overview" in correlation with "System
Catalog".

--

Jürgen Purtz

Attachment Content-Type Size
0001-catalog.patch text/x-patch 6.0 KB

In response to

Responses

Browse pgsql-docs by date

  From Date Subject
Next Message Tom Lane 2020-05-05 14:27:53 Re: Another modest proposal for docs formatting: catalog descriptions
Previous Message Fabien COELHO 2020-05-05 05:52:08 Re: Another modest proposal for docs formatting: catalog descriptions