Re: Installation on Cygwin

[Magnus Hagander]

On Mon, Aug 31, 2020 at 5:52 PM Bruce Momjian  wrote:

> On Fri, Aug 28, 2020 at 09:40:59PM +0200, Daniel Gustafsson wrote:
> > I happened to stumble over the Cygwin section of the installation docs,
> and was
> > surprised to see references to not entirely bleeding-edge Windows
> versions:
> >
> > "The adduser command is not supported; use the appropriate user
> management
> > application on Windows NT, 2000, or XP.  Otherwise, skip this step."
> >
> > Not knowing the first thing about Cygwin I might be out cycling here; it
> does
> > sound like it's about due for an update to reflect current versions of
> Windows,
> > or is this just relevant for older versions?  Skimming backwards we
> have, with
> > various wordings, recommendeed against Cygwin since 8.0, the current
> wording
> > going back to 8.4 more or less unchanged.
>

It's cute that it also talks about doing things on "Windows NT" Any
"non-NT" Windows has not existed for *many* years.



>
> I am thinking the list of operating systems should just be removed.
>

Are you referring to the whole section 16.7 in the 12 version (
https://www.postgresql.org/docs/current/installation-platform-notes.html)?

I can agree with that, and say that maybe that type of content is better
maintained on the wiki?

-- 
 Magnus Hagander
 Me: https://www.hagander.net/ 
 Work: https://www.redpill-linpro.com/ 

Re: Installation instructions vs binaries

[Magnus Hagander]

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 
> 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/ 
 Work: https://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 @@
 
 
 
+
 
 
 
diff --git a/doc/src/sgml/install-binaries.sgml b/doc/src/sgml/install-binaries.sgml
new file mode 100644
index 00..36405e74cc
--- /dev/null
+++ b/doc/src/sgml/install-binaries.sgml
@@ -0,0 +1,24 @@
+
+
+ Installation from Binaries
+
+ 
+  installation
+  binaries
+ 
+
+ 
+  PostgreSQL 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 ) is only recommended for
+  people developing PostgreSQL or extensions.
+ 
+
+ 
+  For an updated list of platforms providing binary packages, please visit
+  the Download section on the PostgreSQL website at
+  https://www.postgresql.org/download/";> and follow the
+  instructions for the specific platform.
+ 
+
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 @@
  
   It is recommended that most users download the binary distribution for
   Windows, available as a graphical installer package
-  from the PostgreSQL website. Building from source
+  from the PostgreSQL website at
+  https://www.postgresql.org/download/";>. Building from source
   is only intended for people developing PostgreSQL
   or extensions.
  
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.
   PostgreSQL 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  instead.
  
 
  
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.

   
 
+  &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.
   
 
+  
+   PostgreSQL  binary packages will normally create the user account
+   automatically.
+  
+
   
To add a Unix user account to your s

Re: Installation instructions vs binaries

[Tom Lane]

Magnus Hagander  writes:
> Yeah, that makes a lot of sense. How about like this?

Isn't this pretty duplicative of d2511d713?

regards, tom lane

Re: Installation instructions vs binaries

[Magnus Hagander]

On Tue, Sep 8, 2020 at 4:06 PM Tom Lane  wrote:

> Magnus Hagander  writes:
> > Yeah, that makes a lot of sense. How about like this?
>
> Isn't this pretty duplicative of d2511d713?
>

Eh yes, I clearly missed that one -- that's what I get for forgetting to
put it in the CF :)

That said, I still think it's worthwhile to have a separate chapter on
installing from binaries, ahead of the source one, rather than just a note
in the source chapter -- and with proper links to the website.

And I think Davids comment about repetitive language would apply to yours
as well, and should maybe be simplified there too?

-- 
 Magnus Hagander
 Me: https://www.hagander.net/ 
 Work: https://www.redpill-linpro.com/ 

Re: Installation instructions vs binaries

[Tom Lane]

Magnus Hagander  writes:
> And I think Davids comment about repetitive language would apply to yours
> as well, and should maybe be simplified there too?

Per the discussion in the other thread, we concluded that being repetitive
was the only way to be sure people would see the material at all.
If you look at

https://www.postgresql.org/docs/devel/runtime.html

a lot of people are going to follow one of the section links before
they ever see any of the chapter head material.

(This would be less of a problem if we could get DocBook to insert
the chapter TOC at the bottom of the page not the top.  I dunno
how to do that, though.)

regards, tom lane

Re: Installation instructions vs binaries

[Magnus Hagander]

On Tue, Sep 8, 2020 at 4:27 PM Tom Lane  wrote:

> Magnus Hagander  writes:
> > And I think Davids comment about repetitive language would apply to yours
> > as well, and should maybe be simplified there too?
>
> Per the discussion in the other thread, we concluded that being repetitive
> was the only way to be sure people would see the material at all.
> If you look at
>
> https://www.postgresql.org/docs/devel/runtime.html
>
> a lot of people are going to follow one of the section links before
> they ever see any of the chapter head material.
>


I think we're talking about a different repetitiveness. If I apply Davids
suggestion to that patch, then instead of:

+  
+   If you are using a pre-packaged version
+   of PostgreSQL, it may well have a specific
+   convention for where to place the data directory, and it may also
+   provide a script for creating the data directory.  In that case you


It would say something like
Pre-packaged versions of PostgreSQL may have a specific convention

(rest unchanged).

//Magnus

Re: Installation instructions vs binaries

[Tom Lane]

Magnus Hagander  writes:
> I think we're talking about a different repetitiveness. If I apply Davids
> suggestion to that patch, then instead of:

> +  
> +   If you are using a pre-packaged version
> +   of PostgreSQL, it may well have a specific
> +   convention for where to place the data directory, and it may also
> +   provide a script for creating the data directory.  In that case you

> It would say something like
> Pre-packaged versions of PostgreSQL may have a specific convention
> (rest unchanged).

[ shrug... ]  Well, I wrote that text, so naturally I like it the way
it is ;-).  Perhaps a neutral observer would like the shorter version
better, not sure.  But I think pluralizing "versions" is going to make
it harder to construct the rest of the sentence non-ambiguously.
You really only want to be talking about one data directory location
and one wrapper script.

regards, tom lane

Re: Installation instructions vs binaries

[Magnus Hagander]

On Tue, Sep 8, 2020 at 4:51 PM Tom Lane  wrote:

> Magnus Hagander  writes:
> > I think we're talking about a different repetitiveness. If I apply Davids
> > suggestion to that patch, then instead of:
>
> > +  
> > +   If you are using a pre-packaged version
> > +   of PostgreSQL, it may well have a specific
> > +   convention for where to place the data directory, and it may also
> > +   provide a script for creating the data directory.  In that case you
>
> > It would say something like
> > Pre-packaged versions of PostgreSQL may have a specific convention
> > (rest unchanged).
>
> [ shrug... ]  Well, I wrote that text, so naturally I like it the way
> it is ;-).  Perhaps a neutral observer would like the shorter version
> better, not sure.  But I think pluralizing "versions" is going to make
> it harder to construct the rest of the sentence non-ambiguously.
> You really only want to be talking about one data directory location
> and one wrapper script.
>

Yeah, I guess it can work either way. I don't feel too strongly about that
one, so I'll leave it to David to argue for that standpoint if he thinks it
applies here as well.

That leaves just the part of adding the actual new chapter of my patch.
PFA. Thoughts on that?

-- 
 Magnus Hagander
 Me: https://www.hagander.net/ 
 Work: https://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 @@
 
 
 
+
 
 
 
diff --git a/doc/src/sgml/install-binaries.sgml b/doc/src/sgml/install-binaries.sgml
new file mode 100644
index 00..36405e74cc
--- /dev/null
+++ b/doc/src/sgml/install-binaries.sgml
@@ -0,0 +1,24 @@
+
+
+ Installation from Binaries
+
+ 
+  installation
+  binaries
+ 
+
+ 
+  PostgreSQL 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 ) is only recommended for
+  people developing PostgreSQL or extensions.
+ 
+
+ 
+  For an updated list of platforms providing binary packages, please visit
+  the Download section on the PostgreSQL website at
+  https://www.postgresql.org/download/";> and follow the
+  instructions for the specific platform.
+ 
+
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 @@
  
   It is recommended that most users download the binary distribution for
   Windows, available as a graphical installer package
-  from the PostgreSQL website. Building from source
+  from the PostgreSQL website at
+  https://www.postgresql.org/download/";>. Building from source
   is only intended for people developing PostgreSQL
   or extensions.
  
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.
   PostgreSQL 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  instead.
  
 
  
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.

   
 
+  &installbin;
   &installation;
   &installw;
   &runtime;