Re: Autovacuum docs

From: Tom Lane <tgl(at)sss(dot)pgh(dot)pa(dot)us>
To: Alvaro Herrera <alvherre(at)alvh(dot)no-ip(dot)org>
Cc: Patches <pgsql-patches(at)postgresql(dot)org>
Subject: Re: Autovacuum docs
Date: 2005-09-12 20:17:29
Message-ID: 24314.1126556249@sss.pgh.pa.us
Views: Raw Message | Whole Thread | Download mbox | Resend email
Thread:
Lists: pgsql-patches

Alvaro Herrera <alvherre(at)alvh(dot)no-ip(dot)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

In response to

Responses

Browse pgsql-patches by date

  From Date Subject
Next Message Neil Conway 2005-09-12 22:12:57 Re: docs: config chapter
Previous Message Tom Lane 2005-09-12 20:02:21 Re: pg_dump feature patch to allow selection of rows to