public inbox for [email protected]
help / color / mirror / Atom feedFrom: Tom Lane <[email protected]>
To: Melanie Plageman <[email protected]>
Cc: Pg Hackers <[email protected]>
Subject: Re: Moving the vacuum GUCs' docs out of the Client Connection Defaults section
Date: Tue, 07 Jan 2025 14:20:09 -0500
Message-ID: <[email protected]> (raw)
In-Reply-To: <CAAKRu_Ymux_RBzp5faSR5-qx1JdM6qS3POVjcWyHbnQjzgmo8g@mail.gmail.com>
References: <CAAKRu_aQUOaMYrcjNuXeSkJtaX9oRUzKP57bsYbC0gVVWS+cbA@mail.gmail.com>
<[email protected]>
<CAAKRu_bz3BD4w0jmjfQkckAQE5eb-Ge2a=9Q-HG_rWSTeG_PzA@mail.gmail.com>
<CAAKRu_Ymux_RBzp5faSR5-qx1JdM6qS3POVjcWyHbnQjzgmo8g@mail.gmail.com>
Melanie Plageman <[email protected]> writes:
>> This is my first docs patch that introduces new sections and such, so
>> I'm not sure I got the indentation 100% correct (I, of course, tried
>> to follow conventions).
There really isn't much convention there :-(. The amount of
indentation used varies wildly across different chunks of our docs.
I'd try to make it look like nearby sections, but those might
themselves be inconsistent.
> Oh, one thing I forgot to say. Though I increased the indentation of
> some of the subsections that I moved, I didn't rewrap the lines
> because they were already not wrapped to 78. I can do this, but I
> can't tell from the existing docs what text width the paragraphs of
> text are supposed to be wrapped to.
If you're moving the text anyway, I'd rewrap it to something less than
80 columns. Again, there's not a lot of uniformity about exactly how
much less. I frequently use 74-column width for new docs text, to
leave some room for minor adjustments without having to rewrap;
but I don't think other people follow that rule.
A lot of the existing violations of 80-column right margin come from
when we switched to XML rules and had to fill out abbreviated closing
tags ("</>") to full tags ("</foo>"). That was done with some more or
less automated conversion that didn't do anything about rewrapping
lines that it made too long. I think that choice was fine, because
it reduced the size of the diff. But if you're rewriting or moving a
para, that's a good time to clean things up by rewrapping it; it'll
all be new according to "git blame" anyway.
regards, tom lane
view thread (21+ messages) latest in thread
reply
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Reply to all the recipients using the --to and --cc options:
reply via email
To: [email protected]
Cc: [email protected], [email protected], [email protected]
Subject: Re: Moving the vacuum GUCs' docs out of the Client Connection Defaults section
In-Reply-To: <[email protected]>
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
This inbox is served by agora; see mirroring instructions
for how to clone and mirror all data and code used for this inbox