Re: [PATCHES] Autovacuum docs
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/ ---(end of broadcast)--- TIP 5: don't forget to increase your free space map settings
Re: [PATCHES] Autovacuum docs
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 ---(end of broadcast)--- TIP 3: Have you checked our extensive FAQ? http://www.postgresql.org/docs/faq
Re: [PATCHES] Autovacuum docs
On Mon, Sep 12, 2005 at 04:17:29PM -0400, Tom Lane wrote: > Alvaro Herrera <[EMAIL PROTECTED]> 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) ---(end of broadcast)--- TIP 2: Don't 'kill -9' the postmaster
Re: [PATCHES] Autovacuum docs
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 ---(end of broadcast)--- TIP 5: don't forget to increase your free space map settings
Re: [PATCHES] Autovacuum docs
Alvaro Herrera <[EMAIL PROTECTED]> 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 ---(end of broadcast)--- TIP 4: Have you searched our list archives? http://archives.postgresql.org
Re: [PATCHES] Autovacuum docs
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/ ---(end of broadcast)--- TIP 9: In versions below 8.0, the planner will ignore your desire to choose an index scan if your joining column's datatypes do not match
