Re: doc fixes: vacuum_cleanup_index_scale_factor

On Mon, May 07, 2018 at 07:26:25PM +0300, Alexander Korotkov wrote:
> Hi!
>
> I've revised docs and comments, and also made some fixes in the code.
> See the attached patchset.
>
> * 0004-btree-cleanup-docs-comments-fixes.patch
> Documentation and comment improvements from Justin Pryzby
> revised by me.

2nd iteration:

diff --git a/doc/src/sgml/config.sgml b/doc/src/sgml/config.sgml
index eabe2a9235..785ecf922a 100644
--- a/doc/src/sgml/config.sgml
+++ b/doc/src/sgml/config.sgml
@@ -1893,15 +1893,35 @@ include_dir 'conf.d'
</term>
<listitem>
<para>
- When no tuples were deleted from the heap, B-tree indexes might still
- be scanned during <command>VACUUM</command> cleanup stage by two
- reasons. The first reason is that B-tree index contains deleted pages
- which can be recycled during cleanup. The second reason is that B-tree
- index statistics is stalled. The criterion of stalled index statistics
- is number of inserted tuples since previous statistics collection
- is greater than <varname>vacuum_cleanup_index_scale_factor</varname>
- fraction of total number of heap tuples.
+ When no tuples were deleted from the heap, B-tree indexes are still
+ scanned during <command>VACUUM</command> cleanup stage unless two
+ conditions are met: the index contains no deleted pages which can be
+ recycled during cleanup; and, the index statistics are not stale.
+ In order to detect stale index statistics, number of total heap tuples
should say: "THE number"

+ during previous statistics collection is memorized in the index
s/memorized/stored/

+ meta-page. Once number number of inserted tuples since previous
Should say "Once the number of inserted tuples..."

+ statistics collection is more than
+ <varname>vacuum_cleanup_index_scale_factor</varname> fraction of
+ number of heap tuples memorized in the meta-page, index statistics is
s/memorized/stored/

+ considered to be stalled. Note, that number of heap tuples is written
"THE number"
s/stalled/stale/

+ to the meta-page at the first time when no dead tuples are found
remove "at"

+ during <command>VACUUM</command> cycle. Thus, skip of B-tree index
I think should say: "Thus, skipping of the B-tree index scan"

+ scan during cleanup stage is only possible in second and subsequent
s/in/when/

+ <para>
+ Zero value of <varname>vacuum_cleanup_index_scale_factor</varname>
I would say "A zero value of ..."

Thanks,
Justin