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)