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.
>
> Two, I find the amount of detail being provided here to be on the
> too-much side.  A bit more judicious use of links into the appropriate
> detail chapters seems warranted.
>
> I took a pretty heavy hand to the original section though aside from
> the scope comment it can probably be considered a bit weighted toward
> style preferences.  Though I did note/rewrite a couple of things that
> seemed factually incorrect - and seemingly not done intentionally in
> the interest of simplification.  Specifically the client connection
> process and, I think, the relationship between the checkpointer and
> background writer.
>
> I do like the idea and the general flow of the material so far -
> though I haven't really looked at the overall structure yet, just
> started reading and editing from the top of the new file.
>
> I've attached the original 0007 patch and my diff against it applied
> to HEAD.
>
> Took a quick peek at the image (at the end) and while I will need a
> second pass over this section regardless I figured I'd provide this
> subset of feedback now in order to move things along a bit.
>
> David J.

The attached patch is an intermediate, mostly formal step. It includes:

- Moving the chapter to "Part VII. Internals".

- Changing the title of the current chapter "Chapter 50. Overview of
PostgreSQL Internals" to "Overview of Query Handling" because the old
title is too generic. This chapter is focused on the handling of queries.

- Integration of David's smaller suggestions. For the more important
suggestions I need some days.

The patch is intended to give every interested person an overall
impression of the chapter within its new position. Because it has moved
from part 'Tutorial' to 'Internals' the text should be very accurate
concerning technical issues - like all the other chapters in this part.
A tutorial chapter has a more superficial nature.

--

J. Purtz