[PATCH] Improvements to "Getting started" tutorial for Google Code-in task

Hello,

On 02.11.18 14:07, LAM JUN RONG wrote:

I’m a student taking part in Google Code-in 2018. The
<http://Code-in 2018. The&gt; task I am currently working on,
https://codein.withgoogle.com/dashboard/task-instances/6406170207059968/,
requires that I review and improve the “Getting Started” tutorial in
the PostgreSQL docs, and submit a patch to this mailing list.

Thank you for picking up this task.

After reviewing the documentation, I found some parts to be slightly
unclear. For example, in section 1.3 on creating databases, I found
“no response” a bit unclear or ambiguous, so I replaced it with “exit
without any error messages”.

After some experimentation, I found that a part of the documentation
was incorrect. In Section 1.3, it was stated that “Database names must
have an alphabetic first character”. However, I was able to create
databases with names like “1234”, “$” or even “😀😀”. Hence, I decided
to remove that sentence.

A diff of my changes is attached.

+    then one or more of the packages 
<productname>PostgreSQL</productname> requires is not installed.
+    See <xref linkend="install-requirements"/> for the required packages.

How about:

then packages which are required to build
<productname>PostgreSQL</productname> are missing.
See <xref linkend="install-requirements"/> for a list of requirements.

      If you are not sure whether <productname>PostgreSQL</productname>
-    is already available or whether you can use it for your
-    experimentation then you can install it yourself.  Doing so is not
+    is already available for your experimentation,
+    you can install it yourself.  Doing so is not
      hard and it can be a good exercise.

This change does not make much sense, given that you leave the
second part of the sentence.

      As is typical of client/server applications, the client and the
-    server can be on different hosts.  In that case they communicate
+    server can be on different machines or networks.  In that case they 
communicate
      over a TCP/IP network connection.  You should keep this in mind,

I think "hosts" is preferred here. The differentiation between machines
and networks is not necessary.

-    The path at your site might be different.  Contact your site
+    The path at your site's server might be different.  Contact your site
      administrator or check the installation instructions to

Dunno if this change improves the wording, or the understanding.
How about replacing "site" with "installation"?

      <productname>PostgreSQL</productname> allows you to create any
-    number of databases at a given site.  Database names must have an
-    alphabetic first character and are limited to 63 bytes in
-    length.  A convenient choice is to create a database with the same
-    name as your current user name.  Many tools assume that database
-    name as the default, so it can save you some typing.  To create
-    that database, simply type:
+    number of databases at a given site.  Database names are limited to 
63 bytes in
+    length. Database names longer than 63 bytes will be truncated. A 
convenient
+    choice is to create a database with the same name as your current 
user name.
+    Many tools assume that database name as the default, so it
+    can save you some typing. To create that database, simply type:

The part about "truncate" is correct, maybe you can include NAMEDATALEN
here as well.

The part about the first character is correct - except you quote the name.
Then any name is allowed. If you rewrite this part, maybe include this
as well.

The other changes look good.

--
Andreas 'ads' Scherbaum
German PostgreSQL User Group
European PostgreSQL User Group - Board of Directors
Volunteer Regional Contact, Germany - PostgreSQL Project

Thanks for your feedback.

I'll make some changes based on your suggestions and send a new diff.

Thanks!
From: Andreas 'ads' Scherbaum <ads@pgug.de>
Sent: Saturday, November 3, 2018 9:17:54 PM
To: LAM JUN RONG; pgsql-hackers@postgresql.org
Subject: Re: [PATCH] Improvements to "Getting started" tutorial for Google Code-in task

Hello,

On 02.11.18 14:07, LAM JUN RONG wrote:

I’m a student taking part in Google Code-in 2018. The<http://Code-in 2018. The&gt; task I am currently working on, https://codein.withgoogle.com/dashboard/task-instances/6406170207059968/, requires that I review and improve the “Getting Started” tutorial in the PostgreSQL docs, and submit a patch to this mailing list.

Thank you for picking up this task.

After reviewing the documentation, I found some parts to be slightly unclear. For example, in section 1.3 on creating databases, I found “no response” a bit unclear or ambiguous, so I replaced it with “exit without any error messages”.

After some experimentation, I found that a part of the documentation was incorrect. In Section 1.3, it was stated that “Database names must have an alphabetic first character”. However, I was able to create databases with names like “1234”, “$” or even “😀😀”. Hence, I decided to remove that sentence.

A diff of my changes is attached.

+    then one or more of the packages <productname>PostgreSQL</productname> requires is not installed.
+    See <xref linkend="install-requirements"/> for the required packages.

How about:

then packages which are required to build
<productname>PostgreSQL</productname> are missing.
See <xref linkend="install-requirements"/> for a list of requirements.

     If you are not sure whether <productname>PostgreSQL</productname>
-    is already available or whether you can use it for your
-    experimentation then you can install it yourself.  Doing so is not
+    is already available for your experimentation,
+    you can install it yourself.  Doing so is not
     hard and it can be a good exercise.

This change does not make much sense, given that you leave the
second part of the sentence.

     As is typical of client/server applications, the client and the
-    server can be on different hosts.  In that case they communicate
+    server can be on different machines or networks.  In that case they communicate
     over a TCP/IP network connection.  You should keep this in mind,

I think "hosts" is preferred here. The differentiation between machines
and networks is not necessary.

-    The path at your site might be different.  Contact your site
+    The path at your site's server might be different.  Contact your site
     administrator or check the installation instructions to

Dunno if this change improves the wording, or the understanding.
How about replacing "site" with "installation"?

     <productname>PostgreSQL</productname> allows you to create any
-    number of databases at a given site.  Database names must have an
-    alphabetic first character and are limited to 63 bytes in
-    length.  A convenient choice is to create a database with the same
-    name as your current user name.  Many tools assume that database
-    name as the default, so it can save you some typing.  To create
-    that database, simply type:
+    number of databases at a given site.  Database names are limited to 63 bytes in
+    length. Database names longer than 63 bytes will be truncated. A convenient
+    choice is to create a database with the same name as your current user name.
+    Many tools assume that database name as the default, so it
+    can save you some typing. To create that database, simply type:

The part about "truncate" is correct, maybe you can include NAMEDATALEN here as well.

The part about the first character is correct - except you quote the name.
Then any name is allowed. If you rewrite this part, maybe include this as well.

The other changes look good.

-- Andreas 'ads' Scherbaum German PostgreSQL User Group European PostgreSQL User Group - Board of Directors Volunteer Regional Contact, Germany - PostgreSQL Project

Hi,

I have made some changes based on Andreas’ suggestions.

+    then one or more of the packages <productname>PostgreSQL</productname> requires is not installed.
+    See <xref linkend="install-requirements"/> for the required packages.

How about:
then packages which are required to build
<productname>PostgreSQL</productname> are missing.
See <xref linkend="install-requirements"/> for a list of requirements.

This seems better than mine, I have included it.

If you are not sure whether <productname>PostgreSQL</productname>
-    is already available or whether you can use it for your
-    experimentation then you can install it yourself.  Doing so is not
+    is already available for your experimentation,
+    you can install it yourself.  Doing so is not
hard and it can be a good exercise.

This change does not make much sense, given that you leave the
second part of the sentence.

How’s this:
If you are not sure whether <productname>PostgreSQL</productname>
is already available for your experimentation,
you can install it yourself, which is not hard.

As is typical of client/server applications, the client and the
-    server can be on different hosts.  In that case they communicate
+    server can be on different machines or networks.  In that case they communicate
over a TCP/IP network connection.  You should keep this in mind,
I think "hosts" is preferred here. The differentiation between machines
and networks is not necessary.

-    The path at your site might be different.  Contact your site
+    The path at your site's server might be different.  Contact your site
administrator or check the installation instructions to
Dunno if this change improves the wording, or the understanding.
How about replacing "site" with "installation"?

For the 2 points above, I decided that the original documentation seems fine.

<productname>PostgreSQL</productname> allows you to create any
-    number of databases at a given site.  Database names must have an
-    alphabetic first character and are limited to 63 bytes in
-    length.  A convenient choice is to create a database with the same
-    name as your current user name.  Many tools assume that database
-    name as the default, so it can save you some typing.  To create
-    that database, simply type:
+    number of databases at a given site.  Database names are limited to 63 bytes in
+    length. Database names longer than 63 bytes will be truncated. A convenient
+    choice is to create a database with the same name as your current user name.
+    Many tools assume that database name as the default, so it
+    can save you some typing. To create that database, simply type:
The part about "truncate" is correct, maybe you can include NAMEDATALEN here as well.
The part about the first character is correct - except you quote the name.
Then any name is allowed. If you rewrite this part, maybe include this as well.

I’ve made some changes to include the part about NAMEDATALEN and quoting:
However, if you would like to create databases with
names that do not start with an alphabetic character, you will need to quote it like so: "1234".
Database names are limited to 63 bytes in length. Database names longer than 63 bytes will be
truncated. You can change this limit by modifying the NAMEDATALEN variable,
but that would require recompiling <productname>PostgreSQL</productname>.

A full diff is attached.

Thank you,
Jun Rong
From: LAM JUN RONG<mailto:h1710074@nushigh.edu.sg>
Sent: Sunday, November 4, 2018 6:17 AM
Subject: Re: [PATCH] Improvements to "Getting started" tutorial for Google Code-in task

Thanks for your feedback.
I'll make some changes based on your suggestions and send a new diff.
Thanks!
From: Andreas 'ads' Scherbaum <ads@pgug.de>
Sent: Saturday, November 3, 2018 9:17:54 PM
To: LAM JUN RONG; pgsql-hackers@postgresql.org
Subject: Re: [PATCH] Improvements to "Getting started" tutorial for Google Code-in task

Hello,
On 02.11.18 14:07, LAM JUN RONG wrote:

I’m a student taking part in Google Code-in 2018. The<http://Code-in 2018. The&gt; task I am currently working on, https://codein.withgoogle.com/dashboard/task-instances/6406170207059968/, requires that I review and improve the “Getting Started” tutorial in the PostgreSQL docs, and submit a patch to this mailing list.

Thank you for picking up this task.

After reviewing the documentation, I found some parts to be slightly unclear. For example, in section 1.3 on creating databases, I found “no response” a bit unclear or ambiguous, so I replaced it with “exit without any error messages”.

After some experimentation, I found that a part of the documentation was incorrect. In Section 1.3, it was stated that “Database names must have an alphabetic first character”. However, I was able to create databases with names like “1234”, “$” or even “😀😀”. Hence, I decided to remove that sentence.

A diff of my changes is attached.

+    then one or more of the packages <productname>PostgreSQL</productname> requires is not installed.
+    See <xref linkend="install-requirements"/> for the required packages.

How about:
then packages which are required to build
<productname>PostgreSQL</productname> are missing.
See <xref linkend="install-requirements"/> for a list of requirements.

     If you are not sure whether <productname>PostgreSQL</productname>
-    is already available or whether you can use it for your
-    experimentation then you can install it yourself.  Doing so is not
+    is already available for your experimentation,
+    you can install it yourself.  Doing so is not
     hard and it can be a good exercise.

This change does not make much sense, given that you leave the
second part of the sentence.

     As is typical of client/server applications, the client and the
-    server can be on different hosts.  In that case they communicate
+    server can be on different machines or networks.  In that case they communicate
     over a TCP/IP network connection.  You should keep this in mind,
I think "hosts" is preferred here. The differentiation between machines
and networks is not necessary.

-    The path at your site might be different.  Contact your site
+    The path at your site's server might be different.  Contact your site
     administrator or check the installation instructions to
Dunno if this change improves the wording, or the understanding.
How about replacing "site" with "installation"?

     <productname>PostgreSQL</productname> allows you to create any
-    number of databases at a given site.  Database names must have an
-    alphabetic first character and are limited to 63 bytes in
-    length.  A convenient choice is to create a database with the same
-    name as your current user name.  Many tools assume that database
-    name as the default, so it can save you some typing.  To create
-    that database, simply type:
+    number of databases at a given site.  Database names are limited to 63 bytes in
+    length. Database names longer than 63 bytes will be truncated. A convenient
+    choice is to create a database with the same name as your current user name.
+    Many tools assume that database name as the default, so it
+    can save you some typing. To create that database, simply type:
The part about "truncate" is correct, maybe you can include NAMEDATALEN here as well.
The part about the first character is correct - except you quote the name.
Then any name is allowed. If you rewrite this part, maybe include this as well.

The other changes look good.
-- Andreas 'ads' Scherbaum German PostgreSQL User Group European PostgreSQL User Group - Board of Directors Volunteer Regional Contact, Germany - PostgreSQL Project

On 04.11.18 02:53, LAM JUN RONG wrote:

Hi,

I have made some changes based on Andreas’ suggestions.

+    then one or more of the packages

<productname>PostgreSQL</productname> requires is not installed.

+    See <xref linkend="install-requirements"/> for the required

packages.

How about:

then packages which are required to build

<productname>PostgreSQL</productname> are missing.

See <xref linkend="install-requirements"/> for a list of requirements.

This seems better than mine, I have included it.

Ok.

      If you are not sure whether <productname>PostgreSQL</productname>

-    is already available or whether you can use it for your

-    experimentation then you can install it yourself.  Doing so is not

+    is already available for your experimentation,

+    you can install it yourself. Doing so is not

      hard and it can be a good exercise.

This change does not make much sense, given that you leave the

second part of the sentence.

How’s this:

If you are not sure whether <productname>PostgreSQL</productname>

is already available for your experimentation,

you can install it yourself, which is not hard.

"you can install it by yourself, which is not complicated"?
I don't like the "hard" there.

      As is typical of client/server applications, the client and the

-    server can be on different hosts.  In that case they communicate

+    server can be on different machines or networks.  In that case

they communicate

      over a TCP/IP network connection.  You should keep this in mind,

I think "hosts" is preferred here. The differentiation between machines

and networks is not necessary.

-    The path at your site might be different.  Contact your site

+    The path at your site's server might be different.  Contact

your site

      administrator or check the installation instructions to

Dunno if this change improves the wording, or the understanding.

How about replacing "site" with "installation"?

For the 2 points above, I decided that the original documentation
seems fine.

Ok.

  <productname>PostgreSQL</productname> allows you to create any

-    number of databases at a given site.  Database names must have an

-    alphabetic first character and are limited to 63 bytes in

-    length.  A convenient choice is to create a database with the same

-    name as your current user name. Many tools assume that database

-    name as the default, so it can save you some typing.  To create

-    that database, simply type:

+    number of databases at a given site.  Database names are

limited to 63 bytes in

+    length. Database names longer than 63 bytes will be truncated.

A convenient

+    choice is to create a database with the same name as your

current user name.

+    Many tools assume that database name as the default, so it

+    can save you some typing. To create that database, simply type:

The part about "truncate" is correct, maybe you can include

NAMEDATALEN here as well.

The part about the first character is correct - except you quote the

name.

Then any name is allowed. If you rewrite this part, maybe include

this as well.

I’ve made some changes to include the part about NAMEDATALEN and quoting:

However, if you would like to create databases with

names that do not start with an alphabetic character, you will need to
quote it like so: "1234".

Database names are limited to 63 bytes in length. Database names
longer than 63 bytes will be

truncated. You can change this limit by modifying the NAMEDATALEN
variable,

but that would require recompiling <productname>PostgreSQL</productname>.

you will need to quote the the identifier, like "1st database".

Database names are limited to 63 bytes in length, or more specifically
to the length defined in NAMEDATALEN. Changing this value requires
recompiling the database. Names which are longer than that are
truncated.

A convenient choice ...

Regards,

--
Andreas 'ads' Scherbaum
German PostgreSQL User Group
European PostgreSQL User Group - Board of Directors
Volunteer Regional Contact, Germany - PostgreSQL Project

Hi,

If you are not sure whether <productname>PostgreSQL</productname>
-    is already available or whether you can use it for your
-    experimentation then you can install it yourself.  Doing so is not
+    is already available for your experimentation,
+    you can install it yourself.  Doing so is not
hard and it can be a good exercise.

This change does not make much sense, given that you leave the
second part of the sentence.

This should be fine:

If you are not sure whether <productname>PostgreSQL</productname>
is already available for your experimentation,
you can install it yourself, which is not complicated.

For the bit on Postgres database names and length,

However, if you would like to create databases with names that do not start with an alphabetic character,
you will need to quote the identifier, like "1234". The length of database names are limited to 63 bytes,
which is the default length defined in NAMEDATALEN. Changing this value requires recompiling the database.
Names longer than the set value will be truncated.

New diff is attached.

Thanks,
Jun Rong

From: Andreas 'ads' Scherbaum<mailto:ads@pgug.de>
Sent: Monday, November 5, 2018 1:48 AM
To: LAM JUN RONG<mailto:h1710074@nushigh.edu.sg>; pgsql-hackers@postgresql.org<mailto:pgsql-hackers@postgresql.org>
Subject: Re: [PATCH] Improvements to "Getting started" tutorial for Google Code-in task

On 04.11.18 02:53, LAM JUN RONG wrote:
Hi,

I have made some changes based on Andreas’ suggestions.

+    then one or more of the packages <productname>PostgreSQL</productname> requires is not installed.
+    See <xref linkend="install-requirements"/> for the required packages.

How about:
then packages which are required to build
<productname>PostgreSQL</productname> are missing.
See <xref linkend="install-requirements"/> for a list of requirements.

This seems better than mine, I have included it.

Ok.

If you are not sure whether <productname>PostgreSQL</productname>
-    is already available or whether you can use it for your
-    experimentation then you can install it yourself.  Doing so is not
+    is already available for your experimentation,
+    you can install it yourself.  Doing so is not
hard and it can be a good exercise.

This change does not make much sense, given that you leave the
second part of the sentence.

How’s this:
If you are not sure whether <productname>PostgreSQL</productname>
is already available for your experimentation,
you can install it yourself, which is not hard.

"you can install it by yourself, which is not complicated"?
I don't like the "hard" there.

As is typical of client/server applications, the client and the
-    server can be on different hosts.  In that case they communicate
+    server can be on different machines or networks.  In that case they communicate
over a TCP/IP network connection.  You should keep this in mind,
I think "hosts" is preferred here. The differentiation between machines
and networks is not necessary.

-    The path at your site might be different.  Contact your site
+    The path at your site's server might be different.  Contact your site
administrator or check the installation instructions to
Dunno if this change improves the wording, or the understanding.
How about replacing "site" with "installation"?

For the 2 points above, I decided that the original documentation seems fine.

Ok.

<productname>PostgreSQL</productname> allows you to create any
-    number of databases at a given site.  Database names must have an
-    alphabetic first character and are limited to 63 bytes in
-    length.  A convenient choice is to create a database with the same
-    name as your current user name.  Many tools assume that database
-    name as the default, so it can save you some typing.  To create
-    that database, simply type:
+    number of databases at a given site.  Database names are limited to 63 bytes in
+    length. Database names longer than 63 bytes will be truncated. A convenient
+    choice is to create a database with the same name as your current user name.
+    Many tools assume that database name as the default, so it
+    can save you some typing. To create that database, simply type:
The part about "truncate" is correct, maybe you can include NAMEDATALEN here as well.
The part about the first character is correct - except you quote the name.
Then any name is allowed. If you rewrite this part, maybe include this as well.

I’ve made some changes to include the part about NAMEDATALEN and quoting:
However, if you would like to create databases with
names that do not start with an alphabetic character, you will need to quote it like so: "1234".
Database names are limited to 63 bytes in length. Database names longer than 63 bytes will be
truncated. You can change this limit by modifying the NAMEDATALEN variable,
but that would require recompiling <productname>PostgreSQL</productname>.

you will need to quote the the identifier, like "1st database".

Database names are limited to 63 bytes in length, or more specifically
to the length defined in NAMEDATALEN. Changing this value requires
recompiling the database. Names which are longer than that are
truncated.

A convenient choice ...

Regards,

--

Andreas 'ads' Scherbaum

German PostgreSQL User Group

European PostgreSQL User Group - Board of Directors

Volunteer Regional Contact, Germany - PostgreSQL Project

On 05.11.18 09:22, LAM JUN RONG wrote:

New diff is attached.

This still has the "hard" in it. Everything else looks fine.
Once you changed that, please register the new patch in the Commitfest
application.

Regards,

--
Andreas 'ads' Scherbaum
German PostgreSQL User Group
European PostgreSQL User Group - Board of Directors
Volunteer Regional Contact, Germany - PostgreSQL Project

Hi,

I must have forgotten to change the diff.

A revised diff is attached.

Jun Rong
________________________________
From: Andreas 'ads' Scherbaum <ads@pgug.de>
Sent: Tuesday, November 6, 2018 8:41:15 AM
To: LAM JUN RONG; pgsql-hackers@postgresql.org
Subject: Re: [PATCH] Improvements to "Getting started" tutorial for Google Code-in task

On 05.11.18 09:22, LAM JUN RONG wrote:

New diff is attached.

This still has the "hard" in it. Everything else looks fine.
Once you changed that, please register the new patch in the Commitfest application.

Regards,

--
Andreas 'ads' Scherbaum
German PostgreSQL User Group
European PostgreSQL User Group - Board of Directors
Volunteer Regional Contact, Germany - PostgreSQL Project

The following review has been posted through the commitfest application:
make installcheck-world: not tested
Implements feature: not tested
Spec compliant: not tested
Documentation: not tested

This is a documentation update, no code changes. The initial idea came from the Google Code-In project, and the changes were modified and reviewed until the wording is appropriate.

The new status of this patch is: Ready for Committer

On 2018-Nov-06, LAM JUN RONG wrote:

Hi,

I must have forgotten to change the diff.

I noticed that you edited the diff by hand -- the line count in the last
hunk doesn't match. This causes both "path" and "git apply" to reject
the patch saying it's corrupted. I suggest not to do that. I can get
it to apply by changing the "+239,14" in the previous-to-last hunk
header to "+239,13" IIRC. (I think there's a utility to recompute line
counts in hunk headers, "rediff" I think, but better not to edit the
patch manually in the first place.)

Besides that, I have a hard time considering this patch committable.
There are some good additions, but they are mixed with some wording
changes that seem to be there just because the author doesn't like the
original, not because they're actual improvements.

One thing I definitely didn't like is that lines go well over 80 chars
per line. We aren't terribly strict about that when there are long XML
tags, but this patch is over the top in that department.

--
�lvaro Herrera https://www.2ndQuadrant.com/
PostgreSQL Development, 24x7 Support, Remote DBA, Training & Services

On 04/01/2019 00:05, Alvaro Herrera wrote:

Besides that, I have a hard time considering this patch committable.
There are some good additions, but they are mixed with some wording
changes that seem to be there just because the author doesn't like the
original, not because they're actual improvements.

I agree. I don't find any of the changes to be improvements.

diff --git a/doc/src/sgml/installation.sgml b/doc/src/sgml/installation.sgml
index 4487d0cfd1..460a2279b6 100644
--- a/doc/src/sgml/installation.sgml
+++ b/doc/src/sgml/installation.sgml
@@ -75,7 +75,7 @@ su - postgres
<application>make</application> programs or older <acronym>GNU</acronym> <application>make</application> versions will <emphasis>not</emphasis> work.
(<acronym>GNU</acronym> <application>make</application> is sometimes installed under
the name <filename>gmake</filename>.)  To test for <acronym>GNU</acronym>
-      <application>make</application> enter:
+      <application>make</application> and check its version, enter:
<screen>
<userinput>make --version</userinput>
</screen>

This might be worthwhile, but it kind of restates something obvious.

@@ -385,8 +385,8 @@ su - postgres
This script will run a number of tests to determine values for various
system dependent variables and detect any quirks of your
operating system, and finally will create several files in the
-    build tree to record what it found.  You can also run
-    <filename>configure</filename> in a directory outside the source
+    build tree to record what it found.  If it does not print any error messages, configuration was successful.
+    You can also run <filename>configure</filename> in a directory outside the source
tree, if you want to keep the build directory separate.  This
procedure is also called a
<indexterm><primary>VPATH</primary></indexterm><firstterm>VPATH</firstterm>

This just says that if there were no errors, it was successful. I think
we don't need to state that. The (from-source) installation chapter is
not for beginners.

@@ -1610,6 +1610,17 @@ su - postgres
<screen>
All of PostgreSQL successfully made. Ready to install.
</screen>
+    If you see an error message like:
+<screen>
+ERROR: `flex' is missing on your system. It is needed to create the
+file `bootscanner.c'. You can either get flex from a GNU mirror site
+or download an official distribution of PostgreSQL, which contains
+pre-packaged flex output.
+</screen>
+    then packages which are required to build 
+    <productname>PostgreSQL</productname> are missing. 
+    See <xref linkend="install-requirements"/> for a list of requirements. 
+
</para>

<para>

This says, if there was an error, you need to read what it says and follow
the instructions. Again, see above.

Moreover, I don't want to keep copies of particular error messages in the
documentation that we then need to keep updating.

diff --git a/doc/src/sgml/start.sgml b/doc/src/sgml/start.sgml
index 5b73557835..e29672a505 100644
--- a/doc/src/sgml/start.sgml
+++ b/doc/src/sgml/start.sgml
@@ -19,9 +19,8 @@

<para>
If you are not sure whether <productname>PostgreSQL</productname>
-    is already available or whether you can use it for your
-    experimentation then you can install it yourself.  Doing so is not
-    hard and it can be a good exercise.
+    is already available for your experimentation,
+    you can install it yourself, which is not complicated.
<productname>PostgreSQL</productname> can be installed by any
unprivileged user; no superuser (<systemitem>root</systemitem>)
access is required.

Doesn't look like a necessary change to me.

@@ -83,7 +82,7 @@

<listitem>
<para>
-       The user's client (frontend) application that wants to perform
+       The user's client (frontend), an application that wants to perform
database operations.  Client applications can be very diverse
in nature:  a client could be a text-oriented tool, a graphical
application, a web server that accesses the database to

Doesn't look like an improvement to me.

@@ -153,7 +152,7 @@
<screen>
<prompt>$</prompt> <userinput>createdb mydb</userinput>
</screen>
-    If this produces no response then this step was successful and you can skip over the
+    If this exits without any error message then this step was successful and you can skip over the
remainder of this section.
</para>

This removes the valuable information that in the success case, no output
is printed.

@@ -240,12 +239,14 @@ createdb: database creation failed: ERROR:  permission denied to create database
<para>
You can also create databases with other names.
<productname>PostgreSQL</productname> allows you to create any
-    number of databases at a given site.  Database names must have an
-    alphabetic first character and are limited to 63 bytes in
-    length.  A convenient choice is to create a database with the same
-    name as your current user name.  Many tools assume that database
-    name as the default, so it can save you some typing.  To create
-    that database, simply type:
+    number of databases at a given site. However, if you would like to create databases with names that do not start with an alphabetic character,
+    you will need to quote the identifier, like "1234". The length of database names are limited to 63 bytes, 
+    which is the default length defined in NAMEDATALEN. Changing this value requires recompiling the database.
+    Names longer than the set value will be truncated.
+    A convenient choice is to create a database with the same name as your current user name. 
+    Many tools assume that database name as the default, so it 
+    can save you some typing. To create that database, simply type:
<screen>
<prompt>$</prompt> <userinput>createdb</userinput>
</screen>

The stuff about the quoting is wrong (shell != SQL). The stuff about
recompiling is unnecessary for a getting-started tutorial.

@@ -355,7 +356,7 @@ mydb=#
<para>
The last line printed out by <command>psql</command> is the
prompt, and it indicates that <command>psql</command> is listening
-    to you and that you can type <acronym>SQL</acronym> queries into a
+    to you and that you can type commands and <acronym>SQL</acronym> queries into a
work space maintained by <command>psql</command>.  Try out these
commands:
<indexterm><primary>version</primary></indexterm>

What's the difference between a "command" and an "SQL query" one might
ask here. Doesn't look like useful change.

--
Peter Eisentraut http://www.2ndQuadrant.com/
PostgreSQL Development, 24x7 Support, Remote DBA, Training & Services

On Sat, Jan 05, 2019 at 04:21:23PM +0100, Peter Eisentraut wrote:

On 04/01/2019 00:05, Alvaro Herrera wrote:

Besides that, I have a hard time considering this patch committable.
There are some good additions, but they are mixed with some wording
changes that seem to be there just because the author doesn't like the
original, not because they're actual improvements.

I agree. I don't find any of the changes to be improvements.

I have marked the patch as returned with feedback, as it has been
waiting input from the author for four weeks now.
--
Michael