Re: Additional Chapter for Tutorial

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