public inbox for [email protected]  

help / color / mirror / Atom feed

From: Jürgen Purtz <[email protected]>
To: David G. Johnston <[email protected]>
Cc: Pg Docs <[email protected]>
Subject: Re: Additional Chapter for Tutorial
Date: Fri, 23 Oct 2020 15:58:46 +0200
Message-ID: <[email protected]> (raw)
In-Reply-To: <CAKFQuwZ_USvnhZ5wQLFtpr8v+iMiwvZOiVZhviQwPYGDVR7w+g@mail.gmail.com>
References: <[email protected]>
	<[email protected]>
	<[email protected]>
	<[email protected]>
	<[email protected]>
	<[email protected]>
	<[email protected]>
	<[email protected]>
	<[email protected]>
	<[email protected]>
	<[email protected]>
	<[email protected]>
	<[email protected]>
	<CAKFQuwZ_USvnhZ5wQLFtpr8v+iMiwvZOiVZhviQwPYGDVR7w+g@mail.gmail.com>

On 21.10.20 22:33, David G. Johnston wrote:
> I've begun looking at this and have included quite a few html comments 
> within the patch.  However, the two main items that I have found so 
> far are:
>
> One, I agree with Peter that this seems misplaced in Tutorial.  I 
> would create a new Internals Chapter and place this material there, or 
> maybe consider a sub-chapter under "Overview of PostgreSQL 
> Internals".  If this is deemed to be of a more primary importance than 
> the content in the Internals section I would recommend placing it in 
> Reference.  I feel it does fit there and given the general importance 
> of that section readers will be inclined to click into it and skim 
> over its content.

I like the idea of dividing the material into two different chapters. 
The existing part "I. Tutorial" contains the first concrete steps: 
installation, creating database and database objects, using SQL basic 
and advanced features. Its typical audience consists of persons doing 
their first steps with PG. The new material is aimed at persons 
interested in implementation aspects of PG. Therefore, the part "VII. 
Internals" seems to be the natural place to integrate it, something like 
"Architecture and Implementation Aspects" or "Architecture and 
Implementation Cornerstones".

Creating such a chapter in "VII. Internals" will increase the existing 
chapter numbers 50 - 71, which may lead to some confusion. On the other 
hand the content can possibly be applied to all supported PG versions at 
the same time, which will lead to a consistent behavior. Extending one 
of the existing chapters won't work because all of them handle their own 
topic, eg.: "50. Overview of PostgreSQL Internals" (misleading title?) 
focuses on the handling of SQL statements from parsing to execution.

What are your thoughts?

--

J. Purtz

reply

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: [email protected]
  Cc: [email protected], [email protected], [email protected]
  Subject: Re: Additional Chapter for Tutorial
  In-Reply-To: <[email protected]>

* Save the following mbox file, import it into your mail client,
  and reply-to-all from there: mbox

This inbox is served by agora; see mirroring instructions
for how to clone and mirror all data and code used for this inbox