Re: Autovacuum docs
Re: Autovacuum docs
От:
"Michael Paesold" <mpaesold@gmx.at>
Дата:
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
Autovacuum docs
От:
Alvaro Herrera <alvherre@alvh.no-ip.org>
Дата:
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.
Re: Autovacuum docs
От:
Peter Eisentraut <peter_e@gmx.net>
Дата:
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/
Re: Autovacuum docs
От:
Alvaro Herrera <alvherre@alvh.no-ip.org>
Дата:
On Mon, Sep 12, 2005 at 04:17:29PM -0400, Tom Lane wrote: > Alvaro Herrera 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 . > > 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)
Re: Autovacuum docs
От:
Peter Eisentraut <peter_e@gmx.net>
Дата:
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/
Re: Autovacuum docs
От:
Tom Lane <tgl@sss.pgh.pa.us>
Дата:
Alvaro Herrera writes: > I have prepared some docs for autovacuum. I attach the patch. Comments > on grammar, style etc. are welcome. A few piddling suggestions: > + See . 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?) > + > + The Auto-Vacuum Daemon 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 > + pg_autovacuum</>.enabled</> field to false. > + 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 pg_autovacuum: "Additionally to" is not good style ... maybe "Besides"? > > *************** > *** 3470,3477 **** > VACUUM</> operations. If -1 is specified (which is the > default), the regular > value will be used. > - This setting can be overridden for individual tables by entries in > - pg_autovacuum</>. > > > > --- 3467,3472 ---- > *************** > *** 3487,3494 **** > VACUUM</> operations. If -1 is specified (which is the > default), the regular > value will be used. > - This setting can be overridden for individual tables by entries in > - pg_autovacuum</>. > > > > --- 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
Re: Autovacuum docs
От:
"Matthew T. O'Connor" <matthew@zeut.net>
Дата:
Tom Lane wrote: >>+ Additionally to the base threshold values and scale factors, there are >>+ two parameters that can be set for each table in pg_autovacuum: >> >> > >"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
