Re: System catalog documentation chapter

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.

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
pg_backend_memory_contexts is documented here and not somewhere near
the stats views. We also have stuff like pg_available_extensions,
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.

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.

regards, tom lane