Hi,
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.
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
<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>
@@ -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>
@@ -1610,6 +1610,15 @@ 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 one or more of the packages <productname>PostgreSQL</productname>
requires is not installed.
+ See <xref linkend="install-requirements"/> for the required packages.
</para>
<para>
diff --git a/doc/src/sgml/start.sgml b/doc/src/sgml/start.sgml
index 5b73557835..4e3aaaac86 100644
--- a/doc/src/sgml/start.sgml
+++ b/doc/src/sgml/start.sgml
@@ -19,8 +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
+ is already available for your experimentation,
+ you can install it yourself. Doing so is not
hard and it can be a good exercise.
<productname>PostgreSQL</productname> can be installed by any
unprivileged user; no superuser (<systemitem>root</systemitem>)
@@ -83,7 +83,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
@@ -99,7 +99,7 @@
<para>
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 @@
<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>
@@ -168,7 +168,7 @@ createdb: command not found
<screen>
<prompt>$</prompt> <userinput>/usr/local/pgsql/bin/createdb mydb</userinput>
</screen>
- 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.
</para>
@@ -240,12 +240,11 @@ 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. 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:
<screen>
<prompt>$</prompt> <userinput>createdb</userinput>
</screen>
@@ -355,7 +354,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>
