Re: Autovacuum docs - Mailing list pgsql-patches

Alvaro Herrera <alvherre@alvh.no-ip.org> writes:
> I have prepared some docs for autovacuum.  I attach the patch.  Comments
> on grammar, style etc. are welcome.

A few piddling suggestions:

> +    See <xref linkend="autovacuum" endterm="autovacuum-title">.

I think we mostly don't use endterm on cross-references to sections.
Not sure if that's a project standard, or just laziness, though.
(Peter?)

> +   <sect2 id="autovacuum">
> +    <title id="autovacuum-title">The Auto-Vacuum Daemon</title>

The other sect2 titles in this chapter capitalize only the first word.
Again, I'm not sure how fully that convention is followed, but I think
this would look better as "The auto-vacuum daemon".

> +     for more details on the global settings.  Note that the autovacuum
> +     daemon can be instructed to skip particular tables, by setting the
> +     <structname>pg_autovacuum</>.<structfield>enabled</> field to <literal>false</literal>.
> +    </para>

This "note" seems a bit awkwardly placed.  I'd drop it and instead add
"enabled" to the list of additional pg_autovacuum parameters here:

> +     Additionally to the base threshold values and scale factors, there are
> +     two parameters that can be set for each table in <structname>pg_autovacuum</structname>:

"Additionally to" is not good style ... maybe "Besides"?

>       <variablelist>
> ***************
> *** 3470,3477 ****
>           <command>VACUUM</> operations.  If -1 is specified (which is the
>           default), the regular
>           <xref linkend="guc-vacuum-cost-delay"> value will be used.
> -         This setting can be overridden for individual tables by entries in
> -         <structname>pg_autovacuum</>.
>          </para>
>         </listitem>
>        </varlistentry>
> --- 3467,3472 ----
> ***************
> *** 3487,3494 ****
>           <command>VACUUM</> operations.  If -1 is specified (which is the
>           default), the regular
>           <xref linkend="guc-vacuum-cost-limit"> value will be used.
> -         This setting can be overridden for individual tables by entries in
> -         <structname>pg_autovacuum</>.
>          </para>
>         </listitem>
>        </varlistentry>
> --- 3482,3487 ----

I don't think you should remove those sentences.  The information about
GUC variables is intentionally somewhat redundant with discussions
elsewhere, and in this case it's important as a cross-reference.

Otherwise looks great.

            regards, tom lane