Re: initdb - creating clusters

Laurenz Albe <laurenz(dot)albe(at)cybertec(dot)at> writes:
> On Thu, 2020-07-09 at 15:25 +0000, PG Doc comments form wrote:
>> I would suggest that you include a paragraph stating that various operating
>> systems use other commands to avoid version conflict and suggest the reader
>> search for '<user-system> pg_ctl'. I can understand why you might not want
>> to link to external sites in your documentation. (While writing this I have
>> searched to make sure I'm not writing rubbish and already understand that
>> pg_createcluster is a Debian solution/variant.)

> Something like the attached?

I think the problem is more general than that. The packager might
well provide a substitute or wrapper for initdb, but it's even more
likely that there's some other way to start and stop the server than
what we describe.

I experimented with putting a disclaimer at the very top of the chapter,
as attached. I like that from a wording standpoint, but from a usability
standpoint it's still got the question of whether users will see it at
all. (This is not helped any by the fact that our current docs toolchain
insists on putting a chapter TOC in front of the chapter head material,
so that what ought to be the most important information becomes something
you don't see at all unless you think to scroll down.)

Another approach would be to put something along this line at the heads
of each of the relevant sections, which'd be 18.1, 18.2, 18.3, 18.5,
and 18.6 by my count. That seems very repetitive; but it would have
the advantage that people could hardly miss it.

I do agree that we ought to do something here. I think only a small
minority of users build their own Postgres installations anymore.

regards, tom lane