No title
Hi hackers,
Recently when looking at the "System Catalogs" Tables of Contents [1]https://www.postgresql.org/docs/15/catalogs.html,
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.
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
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.htmlit 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
Attachments:
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:
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:
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:
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
