Re: descriptions of pg_stat_user_functions and pg_stat_slru

On 2020/05/22 22:35, Fujii Masao wrote:
>
>
> On 2020/05/21 4:53, Tom Lane wrote:
>> Fujii Masao <masao(dot)fujii(at)oss(dot)nttdata(dot)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