From: Joshua D. Drake <jd@commandprompt.com>
To: pgsql-docs <pgsql-docs@postgresql.org>
Subject: readability changes to postgres.sgml
Date: Thu, 15 Aug 2019 12:30:17 -0700
Message-ID: <5ac2c96d-37a6-18aa-08c4-327a6fbff24b@commandprompt.com> (raw)
attached
Thanks,
JD
--
Command Prompt, Inc. || http://the.postgres.company/ || @cmdpromptinc
Postgres centered full stack support, consulting and development.
Advocate: @amplifypostgres || Get help: https://commandprompt.com/
***** Unless otherwise stated, opinions are my own. *****
Attachments:
[text/x-patch] postgres.diff (8.5K, ../5ac2c96d-37a6-18aa-08c4-327a6fbff24b@commandprompt.com/2-postgres.diff)
download | inline diff:diff --git a/doc/src/sgml/postgres.sgml b/doc/src/sgml/postgres.sgmlindex e59cba7997..9f78a62ed8 100644--- a/doc/src/sgml/postgres.sgml+++ b/doc/src/sgml/postgres.sgml@@ -31,24 +31,22 @@
<partintro>
<para>
Welcome to the <productname>PostgreSQL</productname> Tutorial. The
- following few chapters are intended to give a simple introduction+ tutorial is intended to give an introduction
to <productname>PostgreSQL</productname>, relational database
- concepts, and the SQL language to those who are new to any one of- these aspects. We only assume some general knowledge about how to- use computers. No particular Unix or programming experience is- required. This part is mainly intended to give you some hands-on- experience with important aspects of the- <productname>PostgreSQL</productname> system. It makes no attempt- to be a complete or thorough treatment of the topics it covers.+ concepts, and the SQL language. We assume some general knowledge about + how to use computers and no particular Unix or programming experience is+ required. This tutorial is intended to provide hands-on experience with + important aspects of the <productname>PostgreSQL</productname> system. + It makes no attempt to be a comprehensive treatment of the topics it covers.
</para>
<para>
- After you have worked through this tutorial you might want to move- on to reading <xref linkend="sql"/> to gain a more formal knowledge+ After you have successfully completed this tutorial you will want to+ read the <xref linkend="sql"/> section to gain a better understanding
of the SQL language, or <xref linkend="client-interfaces"/> for
- information about developing applications for- <productname>PostgreSQL</productname>. Those who set up and- manage their own server should also read <xref linkend="admin"/>.+ information about developing applications with+ <productname>PostgreSQL</productname>. Those who provision and+ manage their own PostgreSQL installation should also read <xref linkend="admin"/>.
</para>
</partintro>
@@ -66,28 +64,26 @@
This part describes the use of the <acronym>SQL</acronym> language
in <productname>PostgreSQL</productname>. We start with
describing the general syntax of <acronym>SQL</acronym>, then
- explain how to create the structures to hold data, how to populate- the database, and how to query it. The middle part lists the- available data types and functions for use in- <acronym>SQL</acronym> commands. The rest treats several- aspects that are important for tuning a database for optimal- performance.+ how to create tables, how to populate the database, and how to + query it. The middle part lists the available data types and + functions for use in <acronym>SQL</acronym> commands. Lasty,+ we address several aspects of importantance for tuning a database.
</para>
<para>
- The information in this part is arranged so that a novice user can- follow it start to end to gain a full understanding of the topics+ The information is arranged so that a novice user can+ follow it from start to end and gain a full understanding of the topics
without having to refer forward too many times. The chapters are
intended to be self-contained, so that advanced users can read the
- chapters individually as they choose. The information in this- part is presented in a narrative fashion in topical units.- Readers looking for a complete description of a particular command- should see <xref linkend="reference"/>.+ chapters individually as they choose. The information is presented + in narrative form with topical units. Readers looking for a complete + description of a particular command are encouraged to review + the <xref linkend="reference"/>.
</para>
<para>
- Readers of this part should know how to connect to a- <productname>PostgreSQL</productname> database and issue+ Readers should know how to connect to a+ <productname>PostgreSQL</productname> database and issue
<acronym>SQL</acronym> commands. Readers that are unfamiliar with
these issues are encouraged to read <xref linkend="tutorial"/>
first. <acronym>SQL</acronym> commands are typically entered
@@ -118,32 +114,32 @@
<partintro>
<para>
This part covers topics that are of interest to a
- <productname>PostgreSQL</productname> database administrator. This includes- installation of the software, set up and configuration of the- server, management of users and databases, and maintenance tasks.- Anyone who runs a <productname>PostgreSQL</productname> server, even for+ <productname>PostgreSQL</productname> administrator. This includes+ installation, configuration of the server, management of users + and databases, and maintenance tasks. Anyone running + <productname>PostgreSQL</productname> server, even for
personal use, but especially in production, should be familiar
- with the topics covered in this part.+ with these topics.
</para>
<para>
- The information in this part is arranged approximately in the- order in which a new user should read it. But the chapters are- self-contained and can be read individually as desired. The- information in this part is presented in a narrative fashion in- topical units. Readers looking for a complete description of a- particular command should see <xref linkend="reference"/>.+ The information attempts to be in the order in which + a new user should read it. The chapters are self-contained and + can be read individually as desired. The information is presented + in a narrative form in topical units. Readers looking for a complete + description of a command are encouraged to review the + <xref linkend="reference"/>.
</para>
<para>
The first few chapters are written so they can be understood
without prerequisite knowledge, so new users who need to set
- up their own server can begin their exploration with this part.- The rest of this part is about tuning and management; that material+ up their own server can begin their exploration. The rest of this + part is about tuning and management; that material
assumes that the reader is familiar with the general use of
the <productname>PostgreSQL</productname> database system. Readers are
- encouraged to look at <xref linkend="tutorial"/> and <xref- linkend="sql"/> for additional information.+ encouraged review the <xref linkend="tutorial"/> and <xref+ linkend="sql"/> parts for additional information.
</para>
</partintro>
@@ -174,13 +170,13 @@
<para>
This part describes the client programming interfaces distributed
with <productname>PostgreSQL</productname>. Each of these chapters can be
- read independently. Note that there are many other programming- interfaces for client programs that are distributed separately and+ read independently. There are many extrernal programming+ interfaces for client programs that are distributed separately. They
contain their own documentation (<xref linkend="external-projects"/>
lists some of the more popular ones). Readers of this part should be
- familiar with using <acronym>SQL</acronym> commands to manipulate+ familiar with using <acronym>SQL</acronym> to manipulate
and query the database (see <xref linkend="sql"/>) and of course
- with the programming language that the interface uses.+ with the programming language of their choice.
</para>
</partintro>
@@ -198,15 +194,15 @@
<para>
This part is about extending the server functionality with
user-defined functions, data types, triggers, etc. These are
- advanced topics which should probably be approached only after all+ advanced topics which should be approached only after all
the other user documentation about <productname>PostgreSQL</productname> has
been understood. Later chapters in this part describe the server-side
programming languages available in the
<productname>PostgreSQL</productname> distribution as well as
- general issues concerning server-side programming languages. It+ general issues concerning server-side programming. It
is essential to read at least the earlier sections of <xref
linkend="extend"/> (covering functions) before diving into the
- material about server-side programming languages.+ material about server-side programming.
</para>
</partintro>
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Reply to all the recipients using the --to and --cc options:
reply via email
To: pgsql-docs@postgresql.org
Cc: jd@commandprompt.com
Subject: Re: readability changes to postgres.sgml
In-Reply-To: <5ac2c96d-37a6-18aa-08c4-327a6fbff24b@commandprompt.com>
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
This inbox is served by DDX for PostgreSQL; see mirroring instructions
for how to clone and mirror all data and code used for this inbox