public inbox for [email protected]  

help / color / mirror / Atom feed

From: Tom Lane <[email protected]>
To: Robert Haas <[email protected]>
Cc: Alvaro Herrera <[email protected]>
Cc: Andrew Dunstan <[email protected]>
Cc: [email protected] <[email protected]>
Subject: Re: documentation structure
Date: Thu, 21 Mar 2024 09:38:18 -0400
Message-ID: <[email protected]> (raw)
In-Reply-To: <CA+Tgmoa6MiN4pBvAevyvv56c7DGW1WDjg3TeE0xhx2BGW4PhoQ@mail.gmail.com>
References: <CA+TgmobvXwu+iJmBg3hncdjY0-agg3giP-aLi_KhDyrL9+OLew@mail.gmail.com>
	<[email protected]>
	<CA+TgmobJcFAKtS9frnEHTGyV3L54m8NynfHpwRO5fihSYGsHfg@mail.gmail.com>
	<[email protected]>
	<CA+Tgmoa6MiN4pBvAevyvv56c7DGW1WDjg3TeE0xhx2BGW4PhoQ@mail.gmail.com>

Robert Haas <[email protected]> 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

view thread (7+ messages)  latest in thread

reply

Reply instructions:

You may reply publicly to this message via plain-text email
using any one of the following methods:

* Reply to all the recipients using the --to and --cc options:
  reply via email

  To: [email protected]
  Cc: [email protected], [email protected], [email protected], [email protected]
  Subject: Re: documentation structure
  In-Reply-To: <[email protected]>

* Save the following mbox file, import it into your mail client,
  and reply-to-all from there: mbox

This inbox is served by agora; see mirroring instructions
for how to clone and mirror all data and code used for this inbox