Received: from malur.postgresql.org ([217.196.149.56])
	by arkaria.postgresql.org with esmtps  (TLS1.3) tls TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384
	(Exim 4.94.2)
	(envelope-from <pgsql-hackers-owner+archive@lists.postgresql.org>)
	id 1rnIcm-00CaFo-S8
	for pgsql-hackers@arkaria.postgresql.org; Thu, 21 Mar 2024 13:38:29 +0000
Received: from localhost ([127.0.0.1] helo=malur.postgresql.org)
	by malur.postgresql.org with esmtp (Exim 4.94.2)
	(envelope-from <pgsql-hackers-owner+archive@lists.postgresql.org>)
	id 1rnIcl-00Daxn-E4
	for pgsql-hackers@arkaria.postgresql.org; Thu, 21 Mar 2024 13:38:27 +0000
Received: from magus.postgresql.org ([2a02:c0:301:0:ffff::29])
	by malur.postgresql.org with esmtps  (TLS1.3) tls TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384
	(Exim 4.94.2)
	(envelope-from <tgl@sss.pgh.pa.us>)
	id 1rnIcl-00Daxf-4e
	for pgsql-hackers@lists.postgresql.org; Thu, 21 Mar 2024 13:38:27 +0000
Received: from sss.pgh.pa.us ([68.162.161.243])
	by magus.postgresql.org with esmtps  (TLS1.3) tls TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384
	(Exim 4.94.2)
	(envelope-from <tgl@sss.pgh.pa.us>)
	id 1rnIci-005jXX-32
	for pgsql-hackers@postgresql.org; Thu, 21 Mar 2024 13:38:27 +0000
Received: from sss1.sss.pgh.pa.us (localhost [127.0.0.1])
	by sss.pgh.pa.us (8.15.2/8.15.2) with ESMTP id 42LDcISH320033;
	Thu, 21 Mar 2024 09:38:18 -0400
From: Tom Lane <tgl@sss.pgh.pa.us>
To: Robert Haas <robertmhaas@gmail.com>
cc: Alvaro Herrera <alvherre@alvh.no-ip.org>,
        Andrew Dunstan <andrew@dunslane.net>,
        "pgsql-hackers@postgresql.org" <pgsql-hackers@postgresql.org>
Subject: Re: documentation structure
In-reply-to: <CA+Tgmoa6MiN4pBvAevyvv56c7DGW1WDjg3TeE0xhx2BGW4PhoQ@mail.gmail.com>
References: <CA+TgmobvXwu+iJmBg3hncdjY0-agg3giP-aLi_KhDyrL9+OLew@mail.gmail.com> <202403202105.bhhrojsf2diu@alvherre.pgsql> <CA+TgmobJcFAKtS9frnEHTGyV3L54m8NynfHpwRO5fihSYGsHfg@mail.gmail.com> <106570.1710969945@sss.pgh.pa.us> <CA+Tgmoa6MiN4pBvAevyvv56c7DGW1WDjg3TeE0xhx2BGW4PhoQ@mail.gmail.com>
Comments: In-reply-to Robert Haas <robertmhaas@gmail.com>
	message dated "Thu, 21 Mar 2024 09:23:57 -0400"
MIME-Version: 1.0
Content-Type: text/plain; charset="us-ascii"
Content-ID: <320031.1711028298.1@sss.pgh.pa.us>
Date: Thu, 21 Mar 2024 09:38:18 -0400
Message-ID: <320032.1711028298@sss.pgh.pa.us>
List-Id: <pgsql-hackers.lists.postgresql.org>
List-Help: <https://lists.postgresql.org/manage/>
List-Subscribe: <https://lists.postgresql.org/manage/>
List-Post: <mailto:pgsql-hackers@lists.postgresql.org>
List-Owner: <mailto:pgsql-hackers-owner@lists.postgresql.org>
List-Archive: <https://www.postgresql.org/list/pgsql-hackers>
Archived-At: <https://www.postgresql.org/message-id/320032.1711028298%40sss.pgh.pa.us>
Precedence: bulk

Robert Haas <robertmhaas@gmail.com> writes:
> Well, I suppose I thought it was a good idea because (1) we don't seem
> to have any existing precedent for file-per-sect1 rather than
> file-per-chapter and (2) all of the per-AM files combined are less
> than 20% of the size of func.sgml.

We have done (1) in places, eg. json.sgml, array.sgml,
rangetypes.sgml, rowtypes.sgml, and the bulk of extend.sgml is split
out into xaggr, xfunc, xindex, xoper, xtypes.  I'd be the first to
concede it's a bit haphazard, but it's not like there's no precedent.

As for (2), func.sgml likely should have been split years ago.

> But, OK, if you want to establish a new paradigm here, sure. I see two
> ways to do it. We can either put the <chapter> tag directly in
> postgres.sgml, or I can still create a new indextypes.sgml and put
> &btree; etc. inside of it. Which way do you prefer?

I'd follow the extend.sgml precedent: have a file corresponding to the
chapter and containing any top-level text we need, then that includes
a file per sect1.

			regards, tom lane