Hot Standby documentation updates

Attached is a patch that fixes up a couple of spots I felt could use
improvement in the Hot Standby documentation. Most of this is simple
wordsmithing, or minor expansion of points I tried to explain more
clearly. A few of the edits I'd marked up on paper were already applied
in the last update done today--even the same commas added or removed in
some spots. I think this section is closing in on complete and fully
edited when we are all finding the same things to nitpick over.

The main change I added here that could use a review is this addition:

+ Waiting to acquire buffer cleanup locks. This can occur when one
+ database backend is trying to access to data block that is
"pinned"
+ by another backend that is making a change to it. Such pins
should
+ normally be very short-lived, but they can take longer than normal
+ under some circumstances, such as when a cursor executing over
+ a set of data has stopped for some reason.

That's how I interpreted what Simon told me about this subject, but I
may not have captured the details accurately. I didn't think that
saying something as ominous sounding as "Waiting to acquire buffer
cleanup locks" should be there without any description at all what
conditions that happens under, which is what's there right now.

There are only two open things in these docs I'm still a little bugged by:

-The first paragraph mentions "restoring a backup to an exact state with
great precision"; I have no idea what that's supposed to mean in this
context.

-The section about stats collection says "The stats file is deleted at
the start of recovery, so stats from primary and standby will differ;
this is considered a feature not a bug". This left me going "why?", and
some clarification of the reasoning or limitation causing that drift
would be nice.

P.S. I touched a few other files as well, related to a debate from
dinner the other night that touched on Simon introducing more UK
spelling into the docs. This is what the docs look like now:

postgresql/doc/src/sgml $ grep -r behavior * | wc -l
386

postgresql/doc/src/sgml $ grep -r behaviour * | wc -l
9

Half of the latter were in the new material, so while on a binge fixing
those I adjusted the mis-"behaviour"s in other sections too.

--
Greg Smith 2ndQuadrant US Baltimore, MD
PostgreSQL Training, Services and Support
greg(at)2ndQuadrant(dot)com www.2ndQuadrant.us

Applied; updated version attached. I talked to Greg via IM and we
decide to not use his buffer cleanup locks text below but to use
something simpler:

The standby waiting longer than <varname>max_standby_delay</>
to acquire a buffer cleanup lock.

---------------------------------------------------------------------------

Greg Smith wrote:
> Attached is a patch that fixes up a couple of spots I felt could use
> improvement in the Hot Standby documentation. Most of this is simple
> wordsmithing, or minor expansion of points I tried to explain more
> clearly. A few of the edits I'd marked up on paper were already applied
> in the last update done today--even the same commas added or removed in
> some spots. I think this section is closing in on complete and fully
> edited when we are all finding the same things to nitpick over.
>
> The main change I added here that could use a review is this addition:
>
> + Waiting to acquire buffer cleanup locks. This can occur when one
> + database backend is trying to access to data block that is
> "pinned"
> + by another backend that is making a change to it. Such pins
> should
> + normally be very short-lived, but they can take longer than normal
> + under some circumstances, such as when a cursor executing over
> + a set of data has stopped for some reason.
>
> That's how I interpreted what Simon told me about this subject, but I
> may not have captured the details accurately. I didn't think that
> saying something as ominous sounding as "Waiting to acquire buffer
> cleanup locks" should be there without any description at all what
> conditions that happens under, which is what's there right now.
>
> There are only two open things in these docs I'm still a little bugged by:
>
> -The first paragraph mentions "restoring a backup to an exact state with
> great precision"; I have no idea what that's supposed to mean in this
> context.
>
> -The section about stats collection says "The stats file is deleted at
> the start of recovery, so stats from primary and standby will differ;
> this is considered a feature not a bug". This left me going "why?", and
> some clarification of the reasoning or limitation causing that drift
> would be nice.
>
> P.S. I touched a few other files as well, related to a debate from
> dinner the other night that touched on Simon introducing more UK
> spelling into the docs. This is what the docs look like now:
>
> postgresql/doc/src/sgml $ grep -r behavior * | wc -l
> 386
>
> postgresql/doc/src/sgml $ grep -r behaviour * | wc -l
> 9
>
> Half of the latter were in the new material, so while on a binge fixing
> those I adjusted the mis-"behaviour"s in other sections too.
>
> --
> Greg Smith 2ndQuadrant US Baltimore, MD
> PostgreSQL Training, Services and Support
> greg(at)2ndQuadrant(dot)com www.2ndQuadrant.us
>

>
> --
> Sent via pgsql-docs mailing list (pgsql-docs(at)postgresql(dot)org)
> To make changes to your subscription:
> http://www.postgresql.org/mailpref/pgsql-docs

--
Bruce Momjian <bruce(at)momjian(dot)us> http://momjian.us
EnterpriseDB http://enterprisedb.com

+ If your life is a hard drive, Christ can be your backup. +