Thread:

From
Peter Smith
Date:
Hi hackers,

Recently when looking at the "System Catalogs" Tables of Contents [1],
I was wondering why are those headings "Overview" and "System Views"
at the same section level as the catalogs/views within them.

~~~

e.g.1. Current:

Chapter 53. "System Catalogs"
======
53.1. Overview
53.2. pg_aggregate
53.3. pg_am
53.4. pg_amop
53.5. pg_amproc
...
53.66. System Views
53.67. pg_available_extensions
53.68. pg_available_extension_versions
53.69. pg_backend_memory_contexts
53.70. pg_config
...
======

e.g.2 What I thought it should look like:

Chapter 53. "System Catalogs and Views" <-- chapter name change
======
53.1. System Catalogs  <-- heading name change
53.1.1. pg_aggregate
53.1.2. pg_am
53.1.3. pg_amop
53.1.4. pg_amproc
...
53.2. System Views
53.2.1. pg_available_extensions
53.2.2. pg_available_extension_versions
53.2.3. pg_backend_memory_contexts
53.2.4. pg_config
...
======

~~~

OTOH it looks like this table of contents page has been this way
forever (20+ years?). It is hard to believe nobody else suggested
modifying it in all that time, so perhaps there is some reason for it
being like it is?

Thoughts?

------
[1] https://www.postgresql.org/docs/15/catalogs.html

Kind Regards,
Peter Smith.
Fujitsu Australia



Re:

From
Peter Eisentraut
Date:
On 09.06.22 01:29, Peter Smith wrote:
> OTOH it looks like this table of contents page has been this way
> forever (20+ years?). It is hard to believe nobody else suggested
> modifying it in all that time, so perhaps there is some reason for it
> being like it is?

Initially, that chapter did not document any system views.



From
Tom Lane
Date:
Peter Eisentraut <peter.eisentraut@enterprisedb.com> writes:
> Initially, that chapter did not document any system views.

Maybe we could make the system views a separate chapter?

            regards, tom lane



Re:

From
Peter Smith
Date:
On Thu, Jun 9, 2022 at 11:50 PM Tom Lane <tgl@sss.pgh.pa.us> wrote:
>
> Peter Eisentraut <peter.eisentraut@enterprisedb.com> writes:
> > Initially, that chapter did not document any system views.
>
> Maybe we could make the system views a separate chapter?

+1

------
Kind Regards,
Peter Smith.
Fujitsu Australia



Re:

From
Peter Smith
Date:
On Thu, Jun 16, 2022 at 10:59 AM Peter Smith <smithpb2250@gmail.com> wrote:
>
> On Thu, Jun 9, 2022 at 11:50 PM Tom Lane <tgl@sss.pgh.pa.us> wrote:
> >
> > Peter Eisentraut <peter.eisentraut@enterprisedb.com> writes:
> > > Initially, that chapter did not document any system views.
> >
> > Maybe we could make the system views a separate chapter?
>
> +1

There has not been any activity on this thread for a while, so I am
just wondering what I should do next about it:

Are there any other opinions about this?

If there is no interest whatsoever in splitting the existing "System
Catalogs" into 2 chapters ("System Catalogs" and "System Views") then
I will abandon the idea.

But if others also feel it might be better to split them, I can put
patching this on my TODO list and share it sometime later.

TIA.

------
Kind Regards,
Peter Smith.
Fujitsu Australia



System catalog documentation chapter

From
Bruce Momjian
Date:
On Thu, Jul  7, 2022 at 09:29:13AM +1000, Peter Smith wrote:
> On Thu, Jun 16, 2022 at 10:59 AM Peter Smith <smithpb2250@gmail.com> wrote:
> >
> > On Thu, Jun 9, 2022 at 11:50 PM Tom Lane <tgl@sss.pgh.pa.us> wrote:
> > >
> > > Peter Eisentraut <peter.eisentraut@enterprisedb.com> writes:
> > > > Initially, that chapter did not document any system views.
> > >
> > > Maybe we could make the system views a separate chapter?
> >
> > +1
> 
> There has not been any activity on this thread for a while, so I am
> just wondering what I should do next about it:
> 
> Are there any other opinions about this?
> 
> If there is no interest whatsoever in splitting the existing "System
> Catalogs" into 2 chapters ("System Catalogs" and "System Views") then
> I will abandon the idea.
> 
> But if others also feel it might be better to split them, I can put
> patching this on my TODO list and share it sometime later.

Looking at the docs:

    https://www.postgresql.org/docs/devel/catalogs.html
    https://www.postgresql.org/docs/devel/views-overview.html

it is clear this needs to be fixed, and I would be glad to do it soon. 
I don't need a submitted patch.

My only question is whether we apply this to head, head & PG 15, or all
branches?  I think the URLs will change with this adjustment so we might
want to do only head & PG 15.

There are two reasons this didn't get addressed earlier.  First, I have
been focusing on some larger community issues the past few months, and I
now see people are complaining some of these issues are being ignored
--- I need to refocus on those smaller issues.  Second, the original
email thread had no email subject, which tends to cause it to get
ignored and to sometimes be threaded with other unrelated emails that
also have no subject line.

-- 
  Bruce Momjian  <bruce@momjian.us>        https://momjian.us
  EDB                                      https://enterprisedb.com

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




Re: System catalog documentation chapter

From
Peter Smith
Date:
On Fri, Jul 8, 2022 at 2:17 AM Bruce Momjian <bruce@momjian.us> wrote:
>
> On Thu, Jul  7, 2022 at 09:29:13AM +1000, Peter Smith wrote:
> > On Thu, Jun 16, 2022 at 10:59 AM Peter Smith <smithpb2250@gmail.com> wrote:
> > >
> > > On Thu, Jun 9, 2022 at 11:50 PM Tom Lane <tgl@sss.pgh.pa.us> wrote:
> > > >
> > > > Peter Eisentraut <peter.eisentraut@enterprisedb.com> writes:
> > > > > Initially, that chapter did not document any system views.
> > > >
> > > > Maybe we could make the system views a separate chapter?
> > >
> > > +1
> >
> > There has not been any activity on this thread for a while, so I am
> > just wondering what I should do next about it:
> >
> > Are there any other opinions about this?
> >
> > If there is no interest whatsoever in splitting the existing "System
> > Catalogs" into 2 chapters ("System Catalogs" and "System Views") then
> > I will abandon the idea.
> >
> > But if others also feel it might be better to split them, I can put
> > patching this on my TODO list and share it sometime later.
>
> Looking at the docs:

Thanks for looking at this.

>
>         https://www.postgresql.org/docs/devel/catalogs.html
>         https://www.postgresql.org/docs/devel/views-overview.html
>
> it is clear this needs to be fixed, and I would be glad to do it soon.
> I don't need a submitted patch.

Sure. I will step back now and let you fix it.

>
> My only question is whether we apply this to head, head & PG 15, or all
> branches?  I think the URLs will change with this adjustment so we might
> want to do only head & PG 15.

AFAIK the chapter has been structured like this for many years and
nobody patched it sooner, so perhaps that is an indication the older
branches don't really need changing?

>
> There are two reasons this didn't get addressed earlier.  First, I have
> been focusing on some larger community issues the past few months, and I
> now see people are complaining some of these issues are being ignored
> --- I need to refocus on those smaller issues.  Second, the original
> email thread had no email subject, which tends to cause it to get
> ignored and to sometimes be threaded with other unrelated emails that
> also have no subject line.
>

I'm not complaining - the initial dodgy subject was entirely my fault.
I immediately re-posted the email to include a proper subject, but
then the responses came back on the (no subject) thread anyway so that
became the dominant one. Next time I'll try to take more care.

------
Kind Regards,
Peter Smith.
Fujitsu Australia



Re: System catalog documentation chapter

From
Bruce Momjian
Date:
On Fri, Jul  8, 2022 at 09:21:13AM +1000, Peter Smith wrote:
> > My only question is whether we apply this to head, head & PG 15, or all
> > branches?  I think the URLs will change with this adjustment so we might
> > want to do only head & PG 15.
> 
> AFAIK the chapter has been structured like this for many years and
> nobody patched it sooner, so perhaps that is an indication the older
> branches don't really need changing?

Agreed. I don't want to break links into the documentation in final
released versions, so head and PG15 seem wise.

-- 
  Bruce Momjian  <bruce@momjian.us>        https://momjian.us
  EDB                                      https://enterprisedb.com

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




Re: System catalog documentation chapter

From
Tom Lane
Date:
Bruce Momjian <bruce@momjian.us> writes:
> Agreed. I don't want to break links into the documentation in final
> released versions, so head and PG15 seem wise.

I would not expect this to change the doc URLs for any individual
catalogs or views --- if it does, I won't be happy.

            regards, tom lane



Re: System catalog documentation chapter

From
Bruce Momjian
Date:
On Fri, Jul  8, 2022 at 11:49:47AM -0400, Tom Lane wrote:
> Bruce Momjian <bruce@momjian.us> writes:
> > Agreed. I don't want to break links into the documentation in final
> > released versions, so head and PG15 seem wise.
> 
> I would not expect this to change the doc URLs for any individual
> catalogs or views --- if it does, I won't be happy.

Good point --- I thought the chapter was in the URL, but I now see it is
just the section heading:

    https://www.postgresql.org/docs/devel/view-pg-available-extensions.html

so I guess we can backpatch this with no issues.

-- 
  Bruce Momjian  <bruce@momjian.us>        https://momjian.us
  EDB                                      https://enterprisedb.com

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




Re: System catalog documentation chapter

From
Bruce Momjian
Date:
On Fri, Jul  8, 2022 at 12:07:45PM -0400, Bruce Momjian wrote:
> On Fri, Jul  8, 2022 at 11:49:47AM -0400, Tom Lane wrote:
> > Bruce Momjian <bruce@momjian.us> writes:
> > > Agreed. I don't want to break links into the documentation in final
> > > released versions, so head and PG15 seem wise.
> > 
> > I would not expect this to change the doc URLs for any individual
> > catalogs or views --- if it does, I won't be happy.
> 
> Good point --- I thought the chapter was in the URL, but I now see it is
> just the section heading:
> 
>     https://www.postgresql.org/docs/devel/view-pg-available-extensions.html
> 
> so I guess we can backpatch this with no issues.

Attached is a patch to accomplish this.  Its output can be seen here:

    https://momjian.us/tmp/pgsql/internals.html

-- 
  Bruce Momjian  <bruce@momjian.us>        https://momjian.us
  EDB                                      https://enterprisedb.com

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


Attachment

Re: System catalog documentation chapter

From
Peter Smith
Date:
On Sat, Jul 9, 2022 at 5:32 AM Bruce Momjian <bruce@momjian.us> wrote:
>
...

> Attached is a patch to accomplish this.  Its output can be seen here:
>
>         https://momjian.us/tmp/pgsql/internals.html
>

That output looks good to me.

------
Kind Regards,
Peter Smith.
Fujitsu Australia



Re: System catalog documentation chapter

From
Peter Eisentraut
Date:
On 08.07.22 18:07, Bruce Momjian wrote:
> so I guess we can backpatch this with no issues.

It inserts a new chapter, which would renumber all other chapters. 
That's a pretty big change to backpatch.  I'm against that.



Re: System catalog documentation chapter

From
Peter Eisentraut
Date:
On 08.07.22 21:32, Bruce Momjian wrote:
> On Fri, Jul  8, 2022 at 12:07:45PM -0400, Bruce Momjian wrote:
>> On Fri, Jul  8, 2022 at 11:49:47AM -0400, Tom Lane wrote:
>>> Bruce Momjian <bruce@momjian.us> writes:
>>>> Agreed. I don't want to break links into the documentation in final
>>>> released versions, so head and PG15 seem wise.
>>>
>>> I would not expect this to change the doc URLs for any individual
>>> catalogs or views --- if it does, I won't be happy.
>>
>> Good point --- I thought the chapter was in the URL, but I now see it is
>> just the section heading:
>>
>>     https://www.postgresql.org/docs/devel/view-pg-available-extensions.html
>>
>> so I guess we can backpatch this with no issues.
> 
> Attached is a patch to accomplish this.  Its output can be seen here:
> 
>     https://momjian.us/tmp/pgsql/internals.html

views.sgml is a pretty generic name for a chapter that just contains 
system views.




Re: System catalog documentation chapter

From
Bruce Momjian
Date:
On Tue, Jul 12, 2022 at 08:56:01PM +0200, Peter Eisentraut wrote:
> On 08.07.22 18:07, Bruce Momjian wrote:
> > so I guess we can backpatch this with no issues.
> 
> It inserts a new chapter, which would renumber all other chapters. That's a
> pretty big change to backpatch.  I'm against that.

Okay, I can see the renumbering as being confusing so I will do PG 15
and head only.

-- 
  Bruce Momjian  <bruce@momjian.us>        https://momjian.us
  EDB                                      https://enterprisedb.com

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




Re: System catalog documentation chapter

From
Bruce Momjian
Date:
On Tue, Jul 12, 2022 at 08:56:36PM +0200, Peter Eisentraut wrote:
> On 08.07.22 21:32, Bruce Momjian wrote:
> > On Fri, Jul  8, 2022 at 12:07:45PM -0400, Bruce Momjian wrote:
> > > On Fri, Jul  8, 2022 at 11:49:47AM -0400, Tom Lane wrote:
> > > > Bruce Momjian <bruce@momjian.us> writes:
> > > > > Agreed. I don't want to break links into the documentation in final
> > > > > released versions, so head and PG15 seem wise.
> > > > 
> > > > I would not expect this to change the doc URLs for any individual
> > > > catalogs or views --- if it does, I won't be happy.
> > > 
> > > Good point --- I thought the chapter was in the URL, but I now see it is
> > > just the section heading:
> > > 
> > >     https://www.postgresql.org/docs/devel/view-pg-available-extensions.html
> > > 
> > > so I guess we can backpatch this with no issues.
> > 
> > Attached is a patch to accomplish this.  Its output can be seen here:
> > 
> >     https://momjian.us/tmp/pgsql/internals.html
> 
> views.sgml is a pretty generic name for a chapter that just contains system
> views.

Yes, I struggled with that.  What made me choose "views" is that the
current name was catalogs.sgml, not syscatalogs.sgml.  If is acceptable
to use catalogs.sgml and sysviews.sgml?

-- 
  Bruce Momjian  <bruce@momjian.us>        https://momjian.us
  EDB                                      https://enterprisedb.com

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




Re: System catalog documentation chapter

From
Tom Lane
Date:
Bruce Momjian <bruce@momjian.us> writes:
> On Tue, Jul 12, 2022 at 08:56:36PM +0200, Peter Eisentraut wrote:
>> views.sgml is a pretty generic name for a chapter that just contains system
>> views.

> Yes, I struggled with that.  What made me choose "views" is that the
> current name was catalogs.sgml, not syscatalogs.sgml.  If is acceptable
> to use catalogs.sgml and sysviews.sgml?

"catalogs" isn't too confusable with user-defined objects, so I think
that name is fine --- and anyway it has decades of history so changing
it seems unwise.

We seem to have been trending towards less-abbreviated .sgml file names
over time, so personally I'd go for system-views.sgml.

            regards, tom lane



Re: System catalog documentation chapter

From
Bruce Momjian
Date:
On Tue, Jul 12, 2022 at 05:16:41PM -0400, Bruce Momjian wrote:
> On Tue, Jul 12, 2022 at 08:56:01PM +0200, Peter Eisentraut wrote:
> > On 08.07.22 18:07, Bruce Momjian wrote:
> > > so I guess we can backpatch this with no issues.
> > 
> > It inserts a new chapter, which would renumber all other chapters. That's a
> > pretty big change to backpatch.  I'm against that.
> 
> Okay, I can see the renumbering as being confusing so I will do PG 15
> and head only.

Patch applied to PG 15 and master.

-- 
  Bruce Momjian  <bruce@momjian.us>        https://momjian.us
  EDB                                      https://enterprisedb.com

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




Re: System catalog documentation chapter

From
Peter Eisentraut
Date:
On 14.07.22 22:07, Bruce Momjian wrote:
> On Tue, Jul 12, 2022 at 05:16:41PM -0400, Bruce Momjian wrote:
>> On Tue, Jul 12, 2022 at 08:56:01PM +0200, Peter Eisentraut wrote:
>>> On 08.07.22 18:07, Bruce Momjian wrote:
>>>> so I guess we can backpatch this with no issues.
>>>
>>> It inserts a new chapter, which would renumber all other chapters. That's a
>>> pretty big change to backpatch.  I'm against that.
>>
>> Okay, I can see the renumbering as being confusing so I will do PG 15
>> and head only.
> 
> Patch applied to PG 15 and master.

Now that I see the result, I don't think this is really the right 
improvement yet.

The new System Views chapter lists views that are effectively 
quasi-system catalogs, such as pg_shadow or pg_replication_origin_status 
-- the fact that these are views and not tables is secondary.  On the 
other hand, it lists views that are more on the level of information 
schema views, that is, they are explicitly user-facing wrappers around 
information available elsewhere, such as pg_sequences, pg_views.

I think most of them are in the second category.  So having this chapter 
in the "Internals" part seems wrong.  But then moving it, say, closer to 
where the information schema is documented wouldn't be right either, 
unless we move the views in the first category elsewhere.

Also, consider that we document the pg_stats_ views in yet another 
place, and it's not really clear why something like 
pg_replication_slots, which might often be used together with stats 
views, is documented so far away from them.

Maybe this whole notion that "system views" is one thing is not suitable.



Re: System catalog documentation chapter

From
Bruce Momjian
Date:
On Sat, Jul 16, 2022 at 10:53:17AM +0200, Peter Eisentraut wrote:
> Now that I see the result, I don't think this is really the right
> improvement yet.
> 
> The new System Views chapter lists views that are effectively quasi-system
> catalogs, such as pg_shadow or pg_replication_origin_status -- the fact that
> these are views and not tables is secondary.  On the other hand, it lists
> views that are more on the level of information schema views, that is, they
> are explicitly user-facing wrappers around information available elsewhere,
> such as pg_sequences, pg_views.
> 
> I think most of them are in the second category.  So having this chapter in
> the "Internals" part seems wrong.  But then moving it, say, closer to where
> the information schema is documented wouldn't be right either, unless we
> move the views in the first category elsewhere.
> 
> Also, consider that we document the pg_stats_ views in yet another place,
> and it's not really clear why something like pg_replication_slots, which
> might often be used together with stats views, is documented so far away
> from them.
> 
> 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?

-- 
  Bruce Momjian  <bruce@momjian.us>        https://momjian.us
  EDB                                      https://enterprisedb.com

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




Re: System catalog documentation chapter

From
Tom Lane
Date:
Bruce Momjian <bruce@momjian.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



Re: System catalog documentation chapter

From
Peter Smith
Date:
On Tue, Jul 19, 2022 at 1:22 PM Tom Lane <tgl@sss.pgh.pa.us> wrote:
>
> Bruce Momjian <bruce@momjian.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.
>

My original post was prompted when I was scrolling in the
table-of-contents for chapter 53 "System Catalogs". unable to find a
Catalog because I did not realise it was really a View. It was only
when I couldn't find it alphabetically that I noticed there was
*another* appended list of Views, but then the "System Views" heading
seemed strangely buried at the same heading level as everything
else...  and although there was an "Overview" section for Catalogs
there was no "Overview" section for the Views...

Maybe I was only seeing the tip of the iceberg. I'm not sure anymore
what the best solution is. I do prefer the recent changes over how it
used to be, but perhaps they also introduce a whole new set of
problems.

---

(It used to look like this)

Chapter 53. "System Catalogs"
======
53.1. Overview
53.2. pg_aggregate
53.3. pg_am
53.4. pg_amop
53.5. pg_amproc
...
53.66. System Views <--- 2nd heading just hiding here....
53.67. pg_available_extensions
53.68. pg_available_extension_versions
53.69. pg_backend_memory_contexts
53.70. pg_config
...

------
Kind Regards,
Peter Smith.
Fujitsu Australia.



Re: System catalog documentation chapter

From
Bruce Momjian
Date:
On Mon, Jul 18, 2022 at 09:22:24PM -0400, Tom Lane wrote:
> Bruce Momjian <bruce@momjian.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@momjian.us>        https://momjian.us
  EDB                                      https://enterprisedb.com

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




Re: System catalog documentation chapter

From
Bruce Momjian
Date:
On Tue, Jul 19, 2022 at 01:41:44PM -0400, Bruce Momjian wrote:
> 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 have grouped the views by topic.  What I would like to do next is to
move these view sections to the end of relevant documentation chapters.
Is that going to be an improvement?

---------------------------------------------------------------------------

pg_available_extensions
pg_available_extension_versions

pg_backend_memory_contexts

pg_config

pg_cursors

pg_file_settings
pg_hba_file_rules
pg_ident_file_mappings
pg_settings

pg_locks

pg_policies

pg_prepared_statements

pg_prepared_xacts

pg_publication_tables
pg_replication_origin_status
pg_replication_slots

pg_group
pg_roles
pg_shadow
pg_user
pg_user_mappings

pg_shmem_allocations

pg_stats
pg_stats_ext
pg_stats_ext_exprs

pg_timezone_abbrevs
pg_timezone_names

pg_indexes
pg_matviews
pg_rules
pg_seclabels
pg_sequences
pg_tables
pg_views

-- 
  Bruce Momjian  <bruce@momjian.us>        https://momjian.us
  EDB                                      https://enterprisedb.com

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




Re: System catalog documentation chapter

From
Isaac Morland
Date:
On Wed, 20 Jul 2022 at 16:08, Bruce Momjian <bruce@momjian.us> wrote:
On Tue, Jul 19, 2022 at 01:41:44PM -0400, Bruce Momjian wrote:
> 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 have grouped the views by topic.  What I would like to do next is to
move these view sections to the end of relevant documentation chapters.
Is that going to be an improvement?

Will there be a comprehensive list somewhere? Even if it just lists the views, gives maybe a one-sentence description, and links to the relevant chapter, I would find that helpful sometimes.

I ask because I occasionally find myself wanting a comprehensive list of functions, and as far as I can tell it doesn't exist. I'm hoping to avoid that situation for views.

Re: System catalog documentation chapter

From
Bruce Momjian
Date:
On Wed, Jul 20, 2022 at 04:23:21PM -0400, Isaac Morland wrote:
> On Wed, 20 Jul 2022 at 16:08, Bruce Momjian <bruce@momjian.us> wrote:
> 
>     On Tue, Jul 19, 2022 at 01:41:44PM -0400, Bruce Momjian wrote:
>     > 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 have grouped the views by topic.  What I would like to do next is to
>     move these view sections to the end of relevant documentation chapters.
>     Is that going to be an improvement?
> 
> 
> Will there be a comprehensive list somewhere? Even if it just lists the views,
> gives maybe a one-sentence description, and links to the relevant chapter, I
> would find that helpful sometimes.

I was not planning on that since we don't do that in any other cases I
can think of.

> I ask because I occasionally find myself wanting a comprehensive list of
> functions, and as far as I can tell it doesn't exist. I'm hoping to avoid that
> situation for views.

Well, then we just leave them where the are and link to them from other
parts of the documentation, which I assume/hope we already do.

-- 
  Bruce Momjian  <bruce@momjian.us>        https://momjian.us
  EDB                                      https://enterprisedb.com

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




Re: System catalog documentation chapter

From
Bruce Momjian
Date:
On Wed, Jul 20, 2022 at 04:32:46PM -0400, Bruce Momjian wrote:
> On Wed, Jul 20, 2022 at 04:23:21PM -0400, Isaac Morland wrote:
> > Will there be a comprehensive list somewhere? Even if it just lists the views,
> > gives maybe a one-sentence description, and links to the relevant chapter, I
> > would find that helpful sometimes.
> 
> I was not planning on that since we don't do that in any other cases I
> can think of.
> 
> > I ask because I occasionally find myself wanting a comprehensive list of
> > functions, and as far as I can tell it doesn't exist. I'm hoping to avoid that
> > situation for views.
> 
> Well, then we just leave them where the are and link to them from other
> parts of the documentation, which I assume/hope we already do.

People have mentioned the view documentation doesn't belong in the
Internals part.  Maybe we can just move it to the Server
Administration part and leave it together.

-- 
  Bruce Momjian  <bruce@momjian.us>        https://momjian.us
  EDB                                      https://enterprisedb.com

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




Re: System catalog documentation chapter

From
Bruce Momjian
Date:
On Wed, Jul 20, 2022 at 09:19:17PM -0400, Bruce Momjian wrote:
> On Wed, Jul 20, 2022 at 04:32:46PM -0400, Bruce Momjian wrote:
> > On Wed, Jul 20, 2022 at 04:23:21PM -0400, Isaac Morland wrote:
> > > Will there be a comprehensive list somewhere? Even if it just lists the views,
> > > gives maybe a one-sentence description, and links to the relevant chapter, I
> > > would find that helpful sometimes.
> > 
> > I was not planning on that since we don't do that in any other cases I
> > can think of.
> > 
> > > I ask because I occasionally find myself wanting a comprehensive list of
> > > functions, and as far as I can tell it doesn't exist. I'm hoping to avoid that
> > > situation for views.
> > 
> > Well, then we just leave them where the are and link to them from other
> > parts of the documentation, which I assume/hope we already do.
> 
> People have mentioned the view documentation doesn't belong in the
> Internals part.  Maybe we can just move it to the Server
> Administration part and leave it together.

Thinking some more about this, I wonder if we should distinguish system
views that are needed for a task vs those used for reporting.  For
example, pg_stat_activity is a dymamic view and is needed for
monitoring.  pg_prepared_statements just reports the prepared
statements.

Could it be that over time, we have moved the "needed for a task" views
into the relevant sections, and the reporting views have just stayed as
a group, and that is okay --- maybe they just need to be moved to Server
Administration?

-- 
  Bruce Momjian  <bruce@momjian.us>        https://momjian.us
  EDB                                      https://enterprisedb.com

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