Thread:
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
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.
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
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
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
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
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
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
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
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
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
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.
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.
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
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
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
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
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.
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
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
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.
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
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
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.
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
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
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