On Thu, Jul 16, 2020 at 6:25 PM David G. Johnston < david.g.johns...@gmail.com> wrote:
> On Wed, Jul 15, 2020 at 4:13 AM Magnus Hagander <mag...@hagander.net> > wrote: > >> It's kind of strange that if you start your PostgreSQL journey by reading >> our instructions, you get nothing useful about installing PostgreSQL from >> binary packages other than "go ask somebody else about it". Yet we have >> pretty good step by step instructions on our *website* for it. >> >> Attached patch adds a chapter to the docs about installing from binaries, >> and refers those users to the website download instructions (and updates >> the Windows instructions to include an actual link to the website). >> >> It also adds mention of it in a few other places - -there are probably >> more that could use some help with that in the future. But I've seen a lot >> of people get confused by our documentation assuming everything is from >> source when it comes to initdb and pg_ctl that I think it's worth specially >> mentioning it there. >> > Dang, I forgot to add this to the cf page, so I forgot about it myself :) Thanks. Adding tips calling out common package-specific/handled pieces > seems ok. > > One typo for the patch as-is: > > + When PostgreSQL is installed using binary packages, starting and > stopping > + of the system is normally integrated with the service management on > the > + platform. Refer to the documentation for the documentation for these > + packages and the platform for more information. > > Remove "for the documentation" > Hah, yeah, that's cute. However, maybe we should avoid repeated use of the passive "When PostgreSQL > is installed using binary packages". Consider just: "PostgreSQL binary > packages". e.g., > > PostgreSQL binary packages normally include platform-appropriate service > management (starting and stopping). Consult the package documentation for > more information. > > (the other two can be rewording similarly if this is deemed better - all > three should be consistent). > Yeah, that makes a lot of sense. How about like this? -- Magnus Hagander Me: https://www.hagander.net/ <http://www.hagander.net/> Work: https://www.redpill-linpro.com/ <http://www.redpill-linpro.com/>
diff --git a/doc/src/sgml/filelist.sgml b/doc/src/sgml/filelist.sgml index 64b5da0070..463bdfd29c 100644 --- a/doc/src/sgml/filelist.sgml +++ b/doc/src/sgml/filelist.sgml @@ -36,6 +36,7 @@ <!ENTITY client-auth SYSTEM "client-auth.sgml"> <!ENTITY diskusage SYSTEM "diskusage.sgml"> <!ENTITY high-availability SYSTEM "high-availability.sgml"> +<!ENTITY installbin SYSTEM "install-binaries.sgml"> <!ENTITY installation SYSTEM "installation.sgml"> <!ENTITY installw SYSTEM "install-windows.sgml"> <!ENTITY maintenance SYSTEM "maintenance.sgml"> diff --git a/doc/src/sgml/install-binaries.sgml b/doc/src/sgml/install-binaries.sgml new file mode 100644 index 0000000000..36405e74cc --- /dev/null +++ b/doc/src/sgml/install-binaries.sgml @@ -0,0 +1,24 @@ +<!-- doc/src/sgml/install-binaries.sgml --> +<chapter id="install-binaries"> + <title>Installation from Binaries</title> + + <indexterm> + <primary>installation</primary> + <secondary>binaries</secondary> + </indexterm> + + <para> + <productname>PostgreSQL</productname> is available in the form of binary + packages for most common operating systems today. When available, this is + the recommended way to install PostgreSQL for users of the system. Building + from source (see <xref linkend="installation" />) is only recommended for + people developing <productname>PostgreSQL</productname> or extensions. + </para> + + <para> + For an updated list of platforms providing binary packages, please visit + the Download section on the <productname>PostgreSQL</productname> website at + <ulink url="https://www.postgresql.org/download/";></ulink> and follow the + instructions for the specific platform. + </para> +</chapter> diff --git a/doc/src/sgml/install-windows.sgml b/doc/src/sgml/install-windows.sgml index 11f5957aca..844ef2cbd2 100644 --- a/doc/src/sgml/install-windows.sgml +++ b/doc/src/sgml/install-windows.sgml @@ -11,7 +11,8 @@ <para> It is recommended that most users download the binary distribution for Windows, available as a graphical installer package - from the <productname>PostgreSQL</productname> website. Building from source + from the <productname>PostgreSQL</productname> website at + <ulink url="https://www.postgresql.org/download/";></ulink>. Building from source is only intended for people developing <productname>PostgreSQL</productname> or extensions. </para> diff --git a/doc/src/sgml/installation.sgml b/doc/src/sgml/installation.sgml index 552303e211..ce9bdb1297 100644 --- a/doc/src/sgml/installation.sgml +++ b/doc/src/sgml/installation.sgml @@ -21,7 +21,7 @@ documentation. See standalone-profile.xsl for details. <productname>PostgreSQL</productname> using the source code distribution. If you are installing a pre-packaged distribution, such as an RPM or Debian package, ignore this chapter - and read the packager's instructions instead. + and see <xref linkend="install-binaries" /> instead. </para> <para> diff --git a/doc/src/sgml/postgres.sgml b/doc/src/sgml/postgres.sgml index c41ce9499b..730d5fdc34 100644 --- a/doc/src/sgml/postgres.sgml +++ b/doc/src/sgml/postgres.sgml @@ -154,6 +154,7 @@ break is not needed in a wider output rendering. </para> </partintro> + &installbin; &installation; &installw; &runtime; diff --git a/doc/src/sgml/runtime.sgml b/doc/src/sgml/runtime.sgml index f584231935..3b0710e63d 100644 --- a/doc/src/sgml/runtime.sgml +++ b/doc/src/sgml/runtime.sgml @@ -44,6 +44,11 @@ package installation. </para> + <para> + PostgreSQL binary packages will normally create the user account + automatically. + </para> + <para> To add a Unix user account to your system, look for a command <command>useradd</command> or <command>adduser</command>. The user @@ -118,6 +123,14 @@ described in the previous section. </para> + <tip> + <para> + PostgreSQL binary packages normally integrates the initialization process, + making it automatic or look slightly different. Refer to the documentation + for these packages for more information. + </para> + </tip> + <tip> <para> As an alternative to the <option>-D</option> option, you can set @@ -338,6 +351,14 @@ postgres$ <userinput>initdb -D /usr/local/pgsql/data</userinput> <sect1 id="server-start"> <title>Starting the Database Server</title> + <tip> + <para> + PostgreSQL binary packages normally include platform-appropriate service + management (starting and stopping). Refer to the documentation for these + packages and the platform for more information. + </para> + </tip> + <para> Before anyone can access the database, you must start the database server. The database server program is called
