Thread: descriptions of pg_stat_user_functions and pg_stat_slru
Hi, In monitoring.sgml, there are the tables and corresponding descriptions for pg_stat_user_functions and pg_stat_slru views. I found that those descriptions are located in opposite places. For example, the description for pg_stat_user_functions wrongly comes just after the table for pg_stat_slru view. Attached patch fixes this issue. Regards, -- Fujii Masao Advanced Computing Technology Center Research and Development Headquarters NTT DATA CORPORATION
Attachment
Fujii Masao <masao.fujii@oss.nttdata.com> writes:
> In monitoring.sgml, there are the tables and corresponding descriptions
> for pg_stat_user_functions and pg_stat_slru views. I found that those
> descriptions are located in opposite places. For example, the description
> for pg_stat_user_functions wrongly comes just after the table for
> pg_stat_slru view. Attached patch fixes this issue.
Hm, I see your point, but I think there is a bigger problem here:
this entire section was written with great disregard for our normal
conventions of how to lay out text around tables. The standard thing,
as seen in Chapter 9 or the system catalog section, is that first
you have an introductory paragraph --- preferably containing an actual
link to the table --- then you have the table, and then if you feel a
need for any footnote-like comments on the table, you put those below it.
I seem to recall Peter E. explaining that this is important because some
presentations might put the table out-of-line entirely, so you should
have an <xref> to it.
What we've mostly got in 27.2 as it stands is that the explanations are
below the tables, which is just backwards. I think the discrepancy
you spotted is because I added some text about the pg_stat_slru view
and just automatically added it above the table, not noticing that that
wasn't what the surrounding stuff did.
regards, tom lane
On 2020/05/20 11:05, Tom Lane wrote: > Fujii Masao <masao.fujii@oss.nttdata.com> writes: >> In monitoring.sgml, there are the tables and corresponding descriptions >> for pg_stat_user_functions and pg_stat_slru views. I found that those >> descriptions are located in opposite places. For example, the description >> for pg_stat_user_functions wrongly comes just after the table for >> pg_stat_slru view. Attached patch fixes this issue. > > Hm, I see your point, but I think there is a bigger problem here: > this entire section was written with great disregard for our normal > conventions of how to lay out text around tables. The standard thing, > as seen in Chapter 9 or the system catalog section, is that first > you have an introductory paragraph --- preferably containing an actual > link to the table --- then you have the table, and then if you feel a > need for any footnote-like comments on the table, you put those below it. Yeah, I agree to change the layout that way. Also I don't like that all the stats views are packed in one section currently. Which makes the docs difficult to read, I'm afraid. Thought? If we change the layout entirely, at the same time, what about separating each view into different section by adding <sect2>? Regards, -- Fujii Masao Advanced Computing Technology Center Research and Development Headquarters NTT DATA CORPORATION
Fujii Masao <masao.fujii@oss.nttdata.com> writes:
> Also I don't like that all the stats views are packed in one section
> currently. Which makes the docs difficult to read, I'm afraid. Thought?
> If we change the layout entirely, at the same time, what about separating
> each view into different section by adding <sect2>?
OK by me --- that, too, would be more like the existing catalogs
chapter.
regards, tom lane
On 2020/05/20 22:32, Tom Lane wrote: > Fujii Masao <masao.fujii@oss.nttdata.com> writes: >> Also I don't like that all the stats views are packed in one section >> currently. Which makes the docs difficult to read, I'm afraid. Thought? >> If we change the layout entirely, at the same time, what about separating >> each view into different section by adding <sect2>? > > OK by me --- that, too, would be more like the existing catalogs > chapter. Yeah, so I'd like to propose the attached patch. - 6644 | LWLock | ProcArrayLock + 6644 | LWLock | ProcArray I found "ProcArrayLock" is still used in monitoring.sgml though it was renamed to ProcArray. So the patch also includes the above change. Regards, -- Fujii Masao Advanced Computing Technology Center Research and Development Headquarters NTT DATA CORPORATION
Attachment
Fujii Masao <masao.fujii@oss.nttdata.com> writes:
> On 2020/05/20 22:32, Tom Lane wrote:
>> OK by me --- that, too, would be more like the existing catalogs
>> chapter.
> Yeah, so I'd like to propose the attached patch.
Hmmm ... I'm not exactly convinced about sticking xreflabels onto
the <sect2>s as you've done here. Presumably that would make <xref>s
render like "pg_stat_slru" not "Section 27.2.3", which I think is
not consistent with our practice elsewhere. I'd be inclined to
leave the id attributes on the <table>s, and add xreflabels there
if we want them.
I see that catalogs.sgml doesn't really match either of those approaches,
though. Not sure if we want to change it. It looks like people have
tended to use <link> to substitute text for xref's to the catalog
sections, so maybe it would be better to add xreflabels there too
and simplify the references.
Other than that markup quibble, this looks fine to me.
> - 6644 | LWLock | ProcArrayLock
> + 6644 | LWLock | ProcArray
> I found "ProcArrayLock" is still used in monitoring.sgml though
> it was renamed to ProcArray. So the patch also includes the above change.
Ooops, my oversight.
regards, tom lane
On 2020/05/21 4:53, Tom Lane wrote:
> Fujii Masao <masao.fujii@oss.nttdata.com> writes:
>> On 2020/05/20 22:32, Tom Lane wrote:
>>> OK by me --- that, too, would be more like the existing catalogs
>>> chapter.
>
>> Yeah, so I'd like to propose the attached patch.
>
> Hmmm ... I'm not exactly convinced about sticking xreflabels onto
> the <sect2>s as you've done here. Presumably that would make <xref>s
> render like "pg_stat_slru" not "Section 27.2.3", which I think is
> not consistent with our practice elsewhere. I'd be inclined to
> leave the id attributes on the <table>s, and add xreflabels there
> if we want them.
>
> I see that catalogs.sgml doesn't really match either of those approaches,
> though. Not sure if we want to change it. It looks like people have
> tended to use <link> to substitute text for xref's to the catalog
> sections, so maybe it would be better to add xreflabels there too
> and simplify the references.
Yeah, since I think that using <xref> is simpler than <link>, I added xlabel
in <sect2>. But if we don't do that for the consistency with catalog.sgml,
I think that there are two approaches.
(1) Replace <xref> with <link> when referencing to the monitoring views
docs. For example, add <sect2 id="monitoring-pg-stat-relication-view">
and replace <xref linkend="pg-stat-replication-view"/> with
<link linkend="monitoring-pg-stat-replication-view">.
(2) Leave <xref> as it is. In this case, for example,
<xref linkend="pg-stat-replication-view"/> references to the table
of pg_stat_replication instead of the section.
I prefer (1) because it's better to reference to the section rather than
the table. There are thirty <xref> for monitoring views in the docs and
they need to be updated.
>
> Other than that markup quibble, this looks fine to me.
Thanks for the review!
Regards,
--
Fujii Masao
Advanced Computing Technology Center
Research and Development Headquarters
NTT DATA CORPORATION
On 2020/05/22 22:35, Fujii Masao wrote: > > > On 2020/05/21 4:53, Tom Lane wrote: >> Fujii Masao <masao.fujii@oss.nttdata.com> writes: >>> On 2020/05/20 22:32, Tom Lane wrote: >>>> OK by me --- that, too, would be more like the existing catalogs >>>> chapter. >> >>> Yeah, so I'd like to propose the attached patch. >> >> Hmmm ... I'm not exactly convinced about sticking xreflabels onto >> the <sect2>s as you've done here. Presumably that would make <xref>s >> render like "pg_stat_slru" not "Section 27.2.3", which I think is >> not consistent with our practice elsewhere. I'd be inclined to >> leave the id attributes on the <table>s, and add xreflabels there >> if we want them. >> >> I see that catalogs.sgml doesn't really match either of those approaches, >> though. Not sure if we want to change it. It looks like people have >> tended to use <link> to substitute text for xref's to the catalog >> sections, so maybe it would be better to add xreflabels there too >> and simplify the references. > > Yeah, since I think that using <xref> is simpler than <link>, I added xlabel > in <sect2>. But if we don't do that for the consistency with catalog.sgml, > I think that there are two approaches. > > (1) Replace <xref> with <link> when referencing to the monitoring views > docs. For example, add <sect2 id="monitoring-pg-stat-relication-view"> > and replace <xref linkend="pg-stat-replication-view"/> with > <link linkend="monitoring-pg-stat-replication-view">. > > (2) Leave <xref> as it is. In this case, for example, > <xref linkend="pg-stat-replication-view"/> references to the table > of pg_stat_replication instead of the section. > > I prefer (1) because it's better to reference to the section rather than > the table. There are thirty <xref> for monitoring views in the docs and > they need to be updated. Attached (monitoring_docfix_v2.patch) is the patch for (1). I also attached the patch (update_release_note_for_monitoring_stats_views_v1.patch) that updates the tags referencing to pg_stat_xxx views in release note. I will propose this to Bruce if we can agree with the changes in monitoring.sgml. Regards, -- Fujii Masao Advanced Computing Technology Center Research and Development Headquarters NTT DATA CORPORATION
Attachment
On 2020/05/25 14:23, Fujii Masao wrote: > > > On 2020/05/22 22:35, Fujii Masao wrote: >> >> >> On 2020/05/21 4:53, Tom Lane wrote: >>> Fujii Masao <masao.fujii@oss.nttdata.com> writes: >>>> On 2020/05/20 22:32, Tom Lane wrote: >>>>> OK by me --- that, too, would be more like the existing catalogs >>>>> chapter. >>> >>>> Yeah, so I'd like to propose the attached patch. >>> >>> Hmmm ... I'm not exactly convinced about sticking xreflabels onto >>> the <sect2>s as you've done here. Presumably that would make <xref>s >>> render like "pg_stat_slru" not "Section 27.2.3", which I think is >>> not consistent with our practice elsewhere. I'd be inclined to >>> leave the id attributes on the <table>s, and add xreflabels there >>> if we want them. >>> >>> I see that catalogs.sgml doesn't really match either of those approaches, >>> though. Not sure if we want to change it. It looks like people have >>> tended to use <link> to substitute text for xref's to the catalog >>> sections, so maybe it would be better to add xreflabels there too >>> and simplify the references. >> >> Yeah, since I think that using <xref> is simpler than <link>, I added xlabel >> in <sect2>. But if we don't do that for the consistency with catalog.sgml, >> I think that there are two approaches. >> >> (1) Replace <xref> with <link> when referencing to the monitoring views >> docs. For example, add <sect2 id="monitoring-pg-stat-relication-view"> >> and replace <xref linkend="pg-stat-replication-view"/> with >> <link linkend="monitoring-pg-stat-replication-view">. >> >> (2) Leave <xref> as it is. In this case, for example, >> <xref linkend="pg-stat-replication-view"/> references to the table >> of pg_stat_replication instead of the section. >> >> I prefer (1) because it's better to reference to the section rather than >> the table. There are thirty <xref> for monitoring views in the docs and >> they need to be updated. > > Attached (monitoring_docfix_v2.patch) is the patch for (1). Barring any objection, I will commit this patch. Regards, -- Fujii Masao Advanced Computing Technology Center Research and Development Headquarters NTT DATA CORPORATION
On 2020/05/27 12:17, Fujii Masao wrote: > > > On 2020/05/25 14:23, Fujii Masao wrote: >> >> >> On 2020/05/22 22:35, Fujii Masao wrote: >>> >>> >>> On 2020/05/21 4:53, Tom Lane wrote: >>>> Fujii Masao <masao.fujii@oss.nttdata.com> writes: >>>>> On 2020/05/20 22:32, Tom Lane wrote: >>>>>> OK by me --- that, too, would be more like the existing catalogs >>>>>> chapter. >>>> >>>>> Yeah, so I'd like to propose the attached patch. >>>> >>>> Hmmm ... I'm not exactly convinced about sticking xreflabels onto >>>> the <sect2>s as you've done here. Presumably that would make <xref>s >>>> render like "pg_stat_slru" not "Section 27.2.3", which I think is >>>> not consistent with our practice elsewhere. I'd be inclined to >>>> leave the id attributes on the <table>s, and add xreflabels there >>>> if we want them. >>>> >>>> I see that catalogs.sgml doesn't really match either of those approaches, >>>> though. Not sure if we want to change it. It looks like people have >>>> tended to use <link> to substitute text for xref's to the catalog >>>> sections, so maybe it would be better to add xreflabels there too >>>> and simplify the references. >>> >>> Yeah, since I think that using <xref> is simpler than <link>, I added xlabel >>> in <sect2>. But if we don't do that for the consistency with catalog.sgml, >>> I think that there are two approaches. >>> >>> (1) Replace <xref> with <link> when referencing to the monitoring views >>> docs. For example, add <sect2 id="monitoring-pg-stat-relication-view"> >>> and replace <xref linkend="pg-stat-replication-view"/> with >>> <link linkend="monitoring-pg-stat-replication-view">. >>> >>> (2) Leave <xref> as it is. In this case, for example, >>> <xref linkend="pg-stat-replication-view"/> references to the table >>> of pg_stat_replication instead of the section. >>> >>> I prefer (1) because it's better to reference to the section rather than >>> the table. There are thirty <xref> for monitoring views in the docs and >>> they need to be updated. >> >> Attached (monitoring_docfix_v2.patch) is the patch for (1). > > Barring any objection, I will commit this patch. Pushed. Thanks! Regards, -- Fujii Masao Advanced Computing Technology Center Research and Development Headquarters NTT DATA CORPORATION