Date: Tue, 26 Mar 2024 09:52:10 -0500
From: Nathan Bossart <nathandbossart@gmail.com>
To: Robert Haas <robertmhaas@gmail.com>
Cc: Nathan Bossart <nathan@postgresql.org>,
	"pgsql-hackers@postgresql.org" <pgsql-hackers@postgresql.org>
Subject: Re: pgsql: Allow using syncfs() in frontend utilities.
Message-ID: <20240326145210.GA3181099@nathanxps13>
References: <E1qe1wG-002jjs-Fr@gemulon.postgresql.org>
 <CA+TgmobUiqKr+ZMCLc5Qap-sXBnjfGUU+ZBmzYEjUuWyjsGr1g@mail.gmail.com>
MIME-Version: 1.0
Content-Type: text/plain; charset=us-ascii
Content-Disposition: inline
In-Reply-To: 
 <CA+TgmobUiqKr+ZMCLc5Qap-sXBnjfGUU+ZBmzYEjUuWyjsGr1g@mail.gmail.com>
Archived-At: 
 <https://www.postgresql.org/message-id/20240326145210.GA3181099%40nathanxps13>
Precedence: bulk

On Fri, Mar 22, 2024 at 12:52:15PM -0400, Robert Haas wrote:
> I'd like to complain about this commit's addition of a new appendix. I
> do understand the temptation to document caveats like this centrally
> instead of in multiple places, but as I've been complaining about over
> in the "documentation structure" thread, our top-level documentation
> index is too big, and I feel strongly that we need to de-clutter it
> rather than cluttering it further. This added a new chapter which is
> just 5 sentences long. I understand that this was done because the
> same issue applies to a bunch of different utilities and we didn't
> want to duplicate this text in all of those places, but I feel like
> this approach just doesn't scale. If we did this in every place where
> we have this much text that we want to avoid duplicating, we'd soon
> have hundreds of appendixes.

Sorry I missed this.  I explored a couple of options last year but the
discussion trailed off [0].

> What I would suggest we do instead is pick one of the places where
> this comes up and document it there, perhaps the
> recovery_init_sync_method GUC. And then make the documentation for the
> other say something like, you know those issues we documented for
> recovery_init_sync_method? Well they also apply to this.

WFM.  I'll put together a patch.

[0] https://postgr.es/m/20231009204823.GA659480%40nathanxps13

-- 
Nathan Bossart
Amazon Web Services: https://aws.amazon.com