improve installation short version
I just had a case where a new user was slightly confused by our
installation "Short Version" instructions. I think the confusion would
be lessened by adding a couple of comments, as in the attached patch.
cheers
andrew
--
Andrew Dunstan
EDB: https://www.enterprisedb.com
Attachments:
short-version-comments.patchtext/x-patch; charset=UTF-8; name=short-version-comments.patchDownload
diff --git a/doc/src/sgml/installation.sgml b/doc/src/sgml/installation.sgml
index 3c0aa118c7..4e4acb8e04 100644
--- a/doc/src/sgml/installation.sgml
+++ b/doc/src/sgml/installation.sgml
@@ -39,11 +39,13 @@ documentation. See standalone-profile.xsl for details.
./configure
make
su
+# The following commands will be executed as root
make install
adduser postgres
mkdir /usr/local/pgsql/data
chown postgres /usr/local/pgsql/data
su - postgres
+# The following commands will be executed as postgres
/usr/local/pgsql/bin/initdb -D /usr/local/pgsql/data
/usr/local/pgsql/bin/pg_ctl -D /usr/local/pgsql/data -l logfile start
/usr/local/pgsql/bin/createdb test
On Jun 2, 2021, at 1:43 PM, Andrew Dunstan <andrew@dunslane.net> wrote:
<short-version-comments.patch>
It's not the fault of your patch, but the docs seem to be misleading in ways that your comments don't fix. (Or perhaps my Windows knowledge is just too lacking to realize why these instructions are ok?)
Prior to where your patch makes changes, the docs say, "If you are building PostgreSQL for Microsoft Windows, read this chapter if you intend to build with MinGW or Cygwin". I think going on to tell the users to use `su` is a bit odd. Does that exist in standard MinGW and Cygwin environments? I thought "run as" was the Windows option for this.
—
Mark Dilger
EnterpriseDB: http://www.enterprisedb.com
The Enterprise PostgreSQL Company
On 6/2/21 4:58 PM, Mark Dilger wrote:
On Jun 2, 2021, at 1:43 PM, Andrew Dunstan <andrew@dunslane.net> wrote:
<short-version-comments.patch>
It's not the fault of your patch, but the docs seem to be misleading in ways that your comments don't fix. (Or perhaps my Windows knowledge is just too lacking to realize why these instructions are ok?)
Prior to where your patch makes changes, the docs say, "If you are building PostgreSQL for Microsoft Windows, read this chapter if you intend to build with MinGW or Cygwin". I think going on to tell the users to use `su` is a bit odd. Does that exist in standard MinGW and Cygwin environments? I thought "run as" was the Windows option for this.
Yes, good point. We should fix that. Yes, "runas" is a sort of su.
There's no adduser either.
cheers
andrew
--
Andrew Dunstan
EDB: https://www.enterprisedb.com
Andrew Dunstan <andrew@dunslane.net> writes:
On 6/2/21 4:58 PM, Mark Dilger wrote:
Prior to where your patch makes changes, the docs say, "If you are building PostgreSQL for Microsoft Windows, read this chapter if you intend to build with MinGW or Cygwin". I think going on to tell the users to use `su` is a bit odd. Does that exist in standard MinGW and Cygwin environments? I thought "run as" was the Windows option for this.
Yes, good point. We should fix that. Yes, "runas" is a sort of su.
There's no adduser either.
There's a whole lot of Unix systems that don't spell that command
as "adduser", either. That whole recipe has to be understood as
a guide, not something you can blindly copy-and-paste.
Maybe what we really need is an initial disclaimer saying something
along the lines of "Here's approximately what you need to do; adapt
these commands per local requirements."
And then, perhaps, change the last line to "For more detail, see
the rest of this chapter".
regards, tom lane
On 6/2/21 5:36 PM, Tom Lane wrote:
Andrew Dunstan <andrew@dunslane.net> writes:
On 6/2/21 4:58 PM, Mark Dilger wrote:
Prior to where your patch makes changes, the docs say, "If you are building PostgreSQL for Microsoft Windows, read this chapter if you intend to build with MinGW or Cygwin". I think going on to tell the users to use `su` is a bit odd. Does that exist in standard MinGW and Cygwin environments? I thought "run as" was the Windows option for this.
Yes, good point. We should fix that. Yes, "runas" is a sort of su.
There's no adduser either.There's a whole lot of Unix systems that don't spell that command
as "adduser", either. That whole recipe has to be understood as
a guide, not something you can blindly copy-and-paste.Maybe what we really need is an initial disclaimer saying something
along the lines of "Here's approximately what you need to do; adapt
these commands per local requirements."And then, perhaps, change the last line to "For more detail, see
the rest of this chapter".
Ok, patch attached
cheers
andrew
--
Andrew Dunstan
EDB: https://www.enterprisedb.com
Attachments:
short-version-comments-2.patchtext/x-patch; charset=UTF-8; name=short-version-comments-2.patchDownload
diff --git a/doc/src/sgml/installation.sgml b/doc/src/sgml/installation.sgml
index 3c0aa118c7..92b062bebb 100644
--- a/doc/src/sgml/installation.sgml
+++ b/doc/src/sgml/installation.sgml
@@ -34,22 +34,29 @@ documentation. See standalone-profile.xsl for details.
<sect1 id="install-short">
<title>Short Version</title>
+ <para>
+ The recipe below will work on some Unix platforms. It needs to be adapted
+ to local requirements on your platform.
+ </para>
+
<para>
<synopsis>
./configure
make
su
+# The following commands will be executed as root
make install
adduser postgres
mkdir /usr/local/pgsql/data
chown postgres /usr/local/pgsql/data
su - postgres
+# The following commands will be executed as postgres
/usr/local/pgsql/bin/initdb -D /usr/local/pgsql/data
/usr/local/pgsql/bin/pg_ctl -D /usr/local/pgsql/data -l logfile start
/usr/local/pgsql/bin/createdb test
/usr/local/pgsql/bin/psql test
</synopsis>
- The long version is the rest of this
+ For more detail see the rest of this
<phrase>chapter</phrase>.
</para>
</sect1>
On 02.06.21 23:27, Andrew Dunstan wrote:
<short-version-comments.patch>
It's not the fault of your patch, but the docs seem to be misleading in ways that your comments don't fix. (Or perhaps my Windows knowledge is just too lacking to realize why these instructions are ok?)
Prior to where your patch makes changes, the docs say, "If you are building PostgreSQL for Microsoft Windows, read this chapter if you intend to build with MinGW or Cygwin". I think going on to tell the users to use `su` is a bit odd. Does that exist in standard MinGW and Cygwin environments? I thought "run as" was the Windows option for this.
Yes, good point. We should fix that. Yes, "runas" is a sort of su.
There's no adduser either.
I think those instructions were written before "sudo" became common.
Maybe we should update them a bit.