Re: initdb - creating clusters

Laurenz Albe <laurenz.albe@cybertec.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

diff --git a/doc/src/sgml/runtime.sgml b/doc/src/sgml/runtime.sgml
index 937bb2e8ac..8cfc266799 100644
--- a/doc/src/sgml/runtime.sgml
+++ b/doc/src/sgml/runtime.sgml
@@ -8,6 +8,21 @@
   and its interactions with the operating system.
  </para>
 
+ <para>
+  The discussions in this chapter assume that you are working with
+  an unmodified version of <productname>PostgreSQL</productname>,
+  for example one that you built from source according to the directions
+  in the preceding chapters.  If you are working with a pre-packaged
+  version of <productname>PostgreSQL</productname>, it is likely that
+  the packager has made special provisions for installing and starting
+  the database server according to your system's conventions.
+  For example, there may be special scripts for creating a database
+  cluster.  There almost certainly will be a mechanism for starting
+  the server, which you should prefer over constructing your own start
+  script as described in <xref linkend="server-start"/>.
+  Consult the package-level documentation for details.
+ </para>
+
  <sect1 id="postgres-user">
   <title>The <productname>PostgreSQL</productname> User Account</title>