Re: System catalog documentation chapter

On Mon, Jul 18, 2022 at 09:22:24PM -0400, Tom Lane wrote:
> Bruce Momjian <bruce(at)momjian(dot)us> writes:
> > On Sat, Jul 16, 2022 at 10:53:17AM +0200, Peter Eisentraut wrote:
> >> Maybe this whole notion that "system views" is one thing is not suitable.
>
> > Are you thinking we should just call the chapter "System Catalogs and
> > Views" and just place them alphabetically in a single chapter?
>
> I didn't think that was Peter's argument at all. He's complaining
> that "system views" isn't a monolithic category, which is a reasonable
> point, especially since we have a bunch of built-in views that appear
> in other chapters. But to then also confuse them with catalogs isn't
> improving the situation.

I think I see now --- system _tables_ are really not for user consumption
but system views often are. I am thinking the best approach is to move
most of the system views out of the system views section and into the
sections where they make sense.

> The views that are actually reinterpretations of catalog contents should
> probably be documented near the catalogs. But a lot of stuff in that
> chapter is no such thing. For example, it's really unclear why

Right.

> pg_backend_memory_contexts is documented here and not somewhere near
> the stats views. We also have stuff like pg_available_extensions,

Right.

> pg_file_settings, and pg_timezone_names, which are reporting ground truth
> of some sort that didn't come from the catalogs. I'm not sure if those
> belong near the catalogs or not.

I am thinking some of those need to be in the Server Configuration
chapter.

> The larger point, perhaps, is that this whole area is underneath
> "Part VII: Internals", and that being the case what you would expect
> to find here is stuff that we don't intend people to interact with
> in day-to-day usage. Most of the "system views" are specifically
> intended for day-to-day use, maybe only by DBAs, but nonetheless they
> are user-facing in a way that the catalogs aren't.
>
> Maybe we should move them all to Part IV, in a chapter or chapters
> adjacent to the Information Schema chapter. Or maybe try to separate
> "user" views from "DBA" views, and put user views in Part IV while
> DBA views go into a new chapter in Part III, near the stats views.

I am going to look at moving system views that make sense into the
chapters where their contents are mentioned. I don't think having a
central list of views is really helping us because we expect the views
to be used in ways the system catalogs would not be.

I will develop a proposed patch.

--
Bruce Momjian <bruce(at)momjian(dot)us> https://momjian.us
EDB https://enterprisedb.com

Indecision is a decision. Inaction is an action. Mark Batterson