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 1jbE7A-00067Z-Cv
	for pgsql-docs@arkaria.postgresql.org; Wed, 20 May 2020 02:05:48 +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 1jbE78-00030G-IV
	for pgsql-docs@arkaria.postgresql.org; Wed, 20 May 2020 02:05:46 +0000
Received: from makus.postgresql.org ([2001:4800:3e1:1::229])
	by malur.postgresql.org with esmtps (TLS1.3:ECDHE_RSA_AES_256_GCM_SHA384:256)
	(Exim 4.92)
	(envelope-from <tgl@sss.pgh.pa.us>)
	id 1jbE78-000309-Ci
	for pgsql-docs@lists.postgresql.org; Wed, 20 May 2020 02:05:46 +0000
Received: from sss.pgh.pa.us ([66.207.139.130])
	by makus.postgresql.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256)
	(Exim 4.92)
	(envelope-from <tgl@sss.pgh.pa.us>)
	id 1jbE75-0005qZ-A3
	for pgsql-docs@lists.postgresql.org; Wed, 20 May 2020 02:05:45 +0000
Received: from sss1.sss.pgh.pa.us (localhost [127.0.0.1])
	by sss.pgh.pa.us (8.14.4/8.14.4) with ESMTP id 04K25fni023669;
	Tue, 19 May 2020 22:05:41 -0400
From: Tom Lane <tgl@sss.pgh.pa.us>
To: Fujii Masao <masao.fujii@oss.nttdata.com>
cc: pgsql-docs@lists.postgresql.org
Subject: Re: descriptions of pg_stat_user_functions and pg_stat_slru
In-reply-to: <6f8a482c-b3fa-4ed9-21c3-6d222a2cb87d@oss.nttdata.com>
References: <6f8a482c-b3fa-4ed9-21c3-6d222a2cb87d@oss.nttdata.com>
Comments: In-reply-to Fujii Masao <masao.fujii@oss.nttdata.com>
	message dated "Wed, 20 May 2020 10:29:55 +0900"
MIME-Version: 1.0
Content-Type: text/plain; charset="us-ascii"
Content-ID: <23667.1589940341.1@sss.pgh.pa.us>
Date: Tue, 19 May 2020 22:05:41 -0400
Message-ID: <23668.1589940341@sss.pgh.pa.us>
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

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