Received: from malur.postgresql.org ([217.196.149.56])
	by arkaria.postgresql.org with esmtps
 (TLS1.3:ECDHE_RSA_AES_256_GCM_SHA384:256)
	(Exim 4.92)
	(envelope-from <pgsql-docs-owner+archive@lists.postgresql.org>)
	id 1jc7pa-0004Ti-Tb
	for pgsql-docs@arkaria.postgresql.org; Fri, 22 May 2020 13:35:22 +0000
Received: from localhost ([127.0.0.1] helo=malur.postgresql.org)
	by malur.postgresql.org with esmtp (Exim 4.92)
	(envelope-from <pgsql-docs-owner+archive@lists.postgresql.org>)
	id 1jc7pY-00037U-9D
	for pgsql-docs@arkaria.postgresql.org; Fri, 22 May 2020 13:35:20 +0000
Received: from magus.postgresql.org ([2a02:c0:301:0:ffff::29])
	by malur.postgresql.org with esmtps (TLS1.3:ECDHE_RSA_AES_256_GCM_SHA384:256)
	(Exim 4.92)
	(envelope-from <masao.fujii@oss.nttdata.com>)
	id 1jc7pY-000373-3S
	for pgsql-docs@lists.postgresql.org; Fri, 22 May 2020 13:35:20 +0000
Received: from oss.nttdata.com ([49.212.34.109])
	by magus.postgresql.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256)
	(Exim 4.92)
	(envelope-from <masao.fujii@oss.nttdata.com>)
	id 1jc7pU-0006CG-8O
	for pgsql-docs@lists.postgresql.org; Fri, 22 May 2020 13:35:19 +0000
Received: from hnk.local (p1864124-ipbf1405funabasi.chiba.ocn.ne.jp
 [123.216.143.124])
	by oss.nttdata.com (Postfix) with ESMTPSA id AF3B1600E3;
	Fri, 22 May 2020 22:35:09 +0900 (JST)
X-Virus-Status: Clean
X-Virus-Scanned: clamav-milter 0.102.2 at oss.nttdata.com
Subject: Re: descriptions of pg_stat_user_functions and pg_stat_slru
To: Tom Lane <tgl@sss.pgh.pa.us>
Cc: pgsql-docs@lists.postgresql.org
References: <6f8a482c-b3fa-4ed9-21c3-6d222a2cb87d@oss.nttdata.com>
 <23668.1589940341@sss.pgh.pa.us>
 <f31875d6-2300-87af-1479-c9d9abc013be@oss.nttdata.com>
 <19926.1589981558@sss.pgh.pa.us>
 <bd73f8fe-7a9f-d903-b84f-8410ba3e1d5f@oss.nttdata.com>
 <5996.1590004403@sss.pgh.pa.us>
From: Fujii Masao <masao.fujii@oss.nttdata.com>
Message-ID: <f5c9ace0-1691-06e7-7d36-4cebe9e64165@oss.nttdata.com>
Date: Fri, 22 May 2020 22:35:09 +0900
User-Agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10.14; rv:68.0)
 Gecko/20100101 Thunderbird/68.8.0
MIME-Version: 1.0
In-Reply-To: <5996.1590004403@sss.pgh.pa.us>
Content-Type: text/plain; charset=utf-8; format=flowed
Content-Language: en-US
Content-Transfer-Encoding: 7bit
List-Id: <pgsql-docs.lists.postgresql.org>
List-Help: <https://lists.postgresql.org/manage/>
List-Subscribe: <https://lists.postgresql.org/manage/>
List-Post: <mailto:pgsql-docs@lists.postgresql.org>
List-Owner: <mailto:pgsql-docs-owner@lists.postgresql.org>
List-Archive: <https://www.postgresql.org/list/pgsql-docs>
Precedence: bulk



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