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

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(at)pgug(dot)de>
Sent: Monday, November 5, 2018 1:48 AM
To: LAM JUN RONG<mailto:h1710074(at)nushigh(dot)edu(dot)sg>; pgsql-hackers(at)postgresql(dot)org<mailto:pgsql-hackers(at)postgresql(dot)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