Thread: Autovacuum docs
Hackers, I have prepared some docs for autovacuum. I attach the patch. Comments on grammar, style etc. are welcome. I will not apply it yet because it conflicts with Neil's runtime-config restructuring, so I'll wait until he applies his patch. -- Alvaro Herrera -- Valdivia, Chile Architect, www.EnterpriseDB.com www.google.com: interfaz de línea de comando para la web.
Attachment
Alvaro Herrera wrote: > I have prepared some docs for autovacuum. I attach the patch. > Comments on grammar, style etc. are welcome. Looks very good to me. -- Peter Eisentraut http://developer.postgresql.org/~petere/
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
Tom Lane wrote: >>+ 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"? > > I think "In addition to" was what Alvaro meant, which works. I just gave the patch a quick eye-balling and it looks good to me. Alvaro, thanks for doing this, I know I said I would get to it, but I just don't seem to be able to find time for Postgres work these days. If fact I can barely find enough time to keep up with the lists these days. Anyway, it looks good and thanks! Matt
On Mon, Sep 12, 2005 at 04:17:29PM -0400, Tom Lane wrote: > 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. Applied, updated per your comments. > > + 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?) I removed it, but personally I think it's better to put it where it makes the text read naturally. For example, that text reads "See _The auto-vacuum daemon_", instead of "See _Section 21.1.4_" -- I think the former is better. There are instances where it doesn't read so good, for example in the runtime configuration chapter, the text is "These settings control the default behavior for the autovacuum daemon. Please refer to _Section 22.1.4_ for more information." I don't see how to cleanly fit "The auto-vacuum daemon" in that sentence in a way that looks like a reference. So, in short, if there is a policy on this, I propose to update it to use endterm wherever the surrounding text allows it. Please check the new version. Bruce's site is already up to date: http://candle.pha.pa.us/main/writings/pgsql/sgml/maintenance.html#AUTOVACUUM -- Alvaro Herrera -- Valdivia, Chile Architect, www.EnterpriseDB.com One man's impedance mismatch is another man's layer of abstraction. (Lincoln Yeoh)
Alvaro Herrera wrote: > "These settings control the default behavior for the autovacuum daemon. > Please refer to _Section 22.1.4_ for more information." > > I don't see how to cleanly fit "The auto-vacuum daemon" in that sentence > in a way that looks like a reference. > > So, in short, if there is a policy on this, I propose to update it to > use endterm wherever the surrounding text allows it. IIRC the reasoning for not using endterm is that the docs should work well with output formats that don't have hyperlinks, e.g. print. There it is necessary to include the section number for easy navigation. Best Regards, Michael Paesold
Tom Lane wrote: > 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. Yes, please don't use those. > 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". More likely it's "The autovacuum daemon" without hyphen, which is the spelling the actual text uses. But I'd personally rather see consistent title capitalization on all section levels. -- Peter Eisentraut http://developer.postgresql.org/~petere/