public inbox for [email protected]
help / color / mirror / Atom feedFrom: Alvaro Herrera <[email protected]>
To: Robert Haas <[email protected]>
Cc: Tom Lane <[email protected]>
Cc: Andrew Dunstan <[email protected]>
Cc: [email protected] <[email protected]>
Subject: Re: documentation structure
Date: Thu, 21 Mar 2024 17:42:58 +0100
Message-ID: <[email protected]> (raw)
In-Reply-To: <CA+Tgmoaf2ziTh9Z36hdBA47VwoQa8GG_EmvdN8PN3eKygECTKQ@mail.gmail.com>
On 2024-Mar-21, Robert Haas wrote:
> On Thu, Mar 21, 2024 at 9:38 AM Tom Lane <[email protected]> wrote:
> > 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.
>
> OK, here's a new patch set. I've revised 0003 and 0004 to use this
> approach,
Great, thanks. Looking at the index in the PDF after (only) 0003, we
now have this structure
62. Table Access Method Interface Definition ....................................................... 2475
63. Index Access Method Interface Definition ....................................................... 2476
63.1. Basic API Structure for Indexes .......................................................... 2476
63.2. Index Access Method Functions .......................................................... 2479
63.3. Index Scanning ................................................................................ 2485
63.4. Index Locking Considerations ............................................................. 2486
63.5. Index Uniqueness Checks .................................................................. 2487
63.6. Index Cost Estimation Functions ......................................................... 2489
64. Generic WAL Records ................................................................................. 2492
65. Custom WAL Resource Managers ................................................................. 2494
66. Built-in Index Access Methods ...................................................................... 2496
which is a bit odd: why are the two WAL chapters in the middle of the
chapters 62 and 63 talking about AMs? Maybe put 66 right after 63
instead. Also, is it really better to have 62/63 first and 66
later? It sounds to me like 66 is more user-oriented and the other two
are developer-oriented, so I'm inclined to suggest putting them the
other way around, but I'm not really sure about this. (Also, starting
chapter 66 straight with 66.1 BTree without any intro text looks a bit
odd; maybe one short introductory paragraph is sufficient?)
> and I've added a new 0005 that does essentially the same
> thing for the PL chapters.
I was looking at the PL chapters earlier today too, wondering whether
this would be valuable; but I worry that there are too many
sub-sub-sections there, so it could end up being a bit messy. I didn't
look at the resulting output though.
> 0001 and 0002 are [un]changed. Should 0002 use the include-an-entity
> approach as well?
Shrug, I wouldn't, doesn't look worth it.
--
Álvaro Herrera 48°01'N 7°57'E — https://www.EnterpriseDB.com/
"No es bueno caminar con un hombre muerto"
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