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

[LAM JUN RONG]

Hi,

I must have forgotten to change the diff.

A revised diff is attached.

Jun Rong

From: Andreas 'ads' Scherbaum 
Sent: Tuesday, November 6, 2018 8:41:15 AM
To: LAM JUN RONG; pgsql-hack...@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



GCI-pgsql-docs-v1.2.1.diff
Description: GCI-pgsql-docs-v1.2.1.diff

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

[LAM JUN RONG]

Hi,


>  If you are not sure whether PostgreSQL
> -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 PostgreSQL
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:a...@pgug.de>
Sent: Monday, November 5, 2018 1:48 AM
To: LAM JUN RONG<mailto:h1710...@nushigh.edu.sg>; 
pgsql-hack...@postgresql.org<mailto:pgsql-hack...@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 PostgreSQL 
> requires is not installed.
> +See  for the required packages.
>
> How about:
> then packages which are required to build
> PostgreSQL are missing.
> See  for a list of requirements.

This seems better than mine, I have included it.

Ok.



>  If you are not sure whether PostgreSQL
> -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 PostgreSQL
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.



>  PostgreSQL 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 

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

[LAM JUN RONG]

Hi,

I have made some changes based on Andreas’ suggestions.

> +then one or more of the packages PostgreSQL 
> requires is not installed.
> +See  for the required packages.
>
> How about:
> then packages which are required to build
> PostgreSQL are missing.
> See  for a list of requirements.

This seems better than mine, I have included it.

>  If you are not sure whether PostgreSQL
> -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 PostgreSQL
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.

>  PostgreSQL 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 PostgreSQL.


A full diff is attached.

Thank you,
Jun Rong
From: LAM JUN RONG<mailto:h1710...@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 
Sent: Saturday, November 3, 2018 9:17:54 PM
To: LAM JUN RONG; pgsql-hack...@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> 
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 t

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

[LAM JUN RONG]

Thanks for your feedback.

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

Thanks!
From: Andreas 'ads' Scherbaum 
Sent: Saturday, November 3, 2018 9:17:54 PM
To: LAM JUN RONG; pgsql-hack...@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> 
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 PostgreSQL 
requires is not installed.
+See  for the required packages.


How about:

then packages which are required to build
PostgreSQL are missing.
See  for a list of requirements.




 If you are not sure whether PostgreSQL
-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"?



 PostgreSQL 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

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

[LAM JUN RONG]

Hi,



I’m a student taking part in Google Code-in 2018. The 
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.



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.



Thank you and I would appreciate any feedback that would make my first Postgres 
patch better!

Jun Rong



diff --git a/doc/src/sgml/installation.sgml b/doc/src/sgml/installation.sgml
index 4487d0cfd1..2dc2b82d9a 100644
--- a/doc/src/sgml/installation.sgml
+++ b/doc/src/sgml/installation.sgml
@@ -75,7 +75,7 @@ su - postgres
   make programs or older GNU 
make versions will not work.
   (GNU make is sometimes 
installed under
   the name gmake.)  To test for GNU
-  make enter:
+  make and check its version, enter:
 
 make --version
 
@@ -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
-configure 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 configure in a directory outside the 
source
 tree, if you want to keep the build directory separate.  This
 procedure is also called a
 VPATHVPATH
@@ -1610,6 +1610,15 @@ su - postgres
 
 All of PostgreSQL successfully made. Ready to install.
 
+If you see an error message like:
+
+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.
+
+then one or more of the packages PostgreSQL 
requires is not installed.
+See  for the required packages.

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

 If you are not sure whether PostgreSQL
-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.
 PostgreSQL can be installed by any
 unprivileged user; no superuser (root)
@@ -83,7 +83,7 @@
 
  
   
-   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
@@ -99,7 +99,7 @@
 

 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,
 because the files that can be accessed on a client machine might
 not be accessible (or might only be accessible using a different
@@ -153,7 +153,7 @@
 
 $ createdb mydb
 
-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.

 
@@ -168,7 +168,7 @@ createdb: command not found
 
 $ /usr/local/pgsql/bin/createdb mydb
 
-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
 correct the situation.

@@ -240,12 +240,11 @@ createdb: database creation failed: ERROR:  permission 
denied to create database

 You can also create databases with other names.
 PostgreSQL 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
-