Thread: Moving the vacuum GUCs' docs out of the Client Connection Defaults section

I was reviewing all the vacuum related GUCs, and I noticed that they
fall into three main subsections of Chapter 19 (Server Configuration)
in the docs [1]: Automatic Vacuuming [2], Resource Consumption [3],
and Client Connection Defaults [4]. The last one I find pretty
confusing.

vacuum_freeze_min_age, vacuum_freeze_table_age, vacuum_failsafe_age
and their multixact equivalents are all in the Statement Behavior
subsection of the Client Connection Defaults subsection. I could maybe
see a justification for this if these GUCs only affected VACUUM
statements -- but that's not the case. All of these GUCs affect the
behavior of both manually invoked vacuums and autovacuums (with some
caveats about precedence when equivalent table storage parameters are
specified).
But maybe there is some other reason they are documented there that I
am missing.
If not, maybe we should fix it?

I'm not totally sure what the solution should be. Perhaps we rename
the "Automatic Vacuuming" subsection "Vacuuming" and then make
"Automatic Vacuuming" a sub-subsection? And move the vacuum-related
GUCs from client connection defaults to "Vacuuming"?

- Melanie

[1] https://www.postgresql.org/docs/17/runtime-config.html
[2] https://www.postgresql.org/docs/17/runtime-config-autovacuum.html
[3] https://www.postgresql.org/docs/17/runtime-config-resource.html
[4] https://www.postgresql.org/docs/17/runtime-config-client.html

Melanie Plageman <melanieplageman@gmail.com> writes:
> I was reviewing all the vacuum related GUCs, and I noticed that they
> fall into three main subsections of Chapter 19 (Server Configuration)
> in the docs [1]: Automatic Vacuuming [2], Resource Consumption [3],
> and Client Connection Defaults [4]. The last one I find pretty
> confusing.

Yeah, it's a mess.  It sounds good to consolidate all of those under
a top-level Vacuuming section.

            regards, tom lane

On Tue, Jan 7, 2025 at 12:15 PM Melanie Plageman
<melanieplageman@gmail.com> wrote:
>
> Cool, I've attached a patch to do this. I left a few of the GUCs under
> Resource Consumption (like autovacuum_work_mem and
> vacuum_buffer_usage_limit) where they are because it seemed
> appropriate.
>
> 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).

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.

- Melanie

On Tue, Jan 07, 2025 at 12:15:17PM -0500, Melanie Plageman wrote:
> 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).

I haven't reviewed the patch in depth, but I think it's worth considering
whether this change will break any links that work in one version but break
if you change the version number.  I believe appendix-obsolete.sgml is
designed to help with that a bit, but I've had mixed results when I've
tried to use it.  Of course, it's also possible that we don't care too
much...

But overall, consolidating the docs for the vacuum GUCs seems like a good
idea.

-- 
nathan

Melanie Plageman <melanieplageman@gmail.com> 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

Nathan Bossart <nathandbossart@gmail.com> writes:
> I haven't reviewed the patch in depth, but I think it's worth considering
> whether this change will break any links that work in one version but break
> if you change the version number.  I believe appendix-obsolete.sgml is
> designed to help with that a bit, but I've had mixed results when I've
> tried to use it.  Of course, it's also possible that we don't care too
> much...

Yeah, this change:

-   <sect1 id="runtime-config-autovacuum">
+   <sect1 id="runtime-config-vacuum">

will change the doc page's URL and thus break any external links or
bookmarks for the whole page or anything on it.  That's not the
end of the world, but it's slightly annoying.  appendix-obsolete.sgml
seems to be designed for slightly more heavyweight changes, where
it's worth having an intermediate page that explains what changed.
Here I think we'd just like a redirect.

I might be wrong, but I had the idea that our docs website has a
capability to provide such redirects.  You'd probably need to ask
about that on the pgsql-www list, unless somebody who knows the
answer notices this thread.

            regards, tom lane

> On 7 Jan 2025, at 21:14, Tom Lane <tgl@sss.pgh.pa.us> wrote:

> I might be wrong, but I had the idea that our docs website has a
> capability to provide such redirects.  You'd probably need to ask
> about that on the pgsql-www list, unless somebody who knows the
> answer notices this thread.

There is functionality in pgweb to provide a page alias for whenever a page is
renamed to keep the links to other versions working.  One example is:

  https://www.postgresql.org/docs/9.4/catalog-pg-replication-slots.html
  https://www.postgresql.org/docs/17/view-pg-replication-slots.html

There is also a redirect functionality, which isn't used anywhere right now,
but ideally could be used to redirect bookmarks for /current/<oldname> to
/current/<newname>.

--
Daniel Gustafsson

On 07.01.25 18:31, Melanie Plageman wrote:
> On Tue, Jan 7, 2025 at 12:15 PM Melanie Plageman
> <melanieplageman@gmail.com> wrote:
>>
>> Cool, I've attached a patch to do this. I left a few of the GUCs under
>> Resource Consumption (like autovacuum_work_mem and
>> vacuum_buffer_usage_limit) where they are because it seemed
>> appropriate.
>>
>> 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).
> 
> 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.

For a patch that moves things around like this, I would leave everything 
as is and not rewrap.  That makes it easier to follow what's going on 
with "git diff -w", "git show -w" etc.

In .dir-locals.el, there is this configuration for Emacs:

  (nxml-mode . ((fill-column . 78)
                (indent-tabs-mode . nil)))

So that's one data point about what the line length should be.

On Wed, Jan 8, 2025 at 6:35 AM Daniel Gustafsson <daniel@yesql.se> wrote:
>
> > On 7 Jan 2025, at 21:14, Tom Lane <tgl@sss.pgh.pa.us> wrote:
>
> > I might be wrong, but I had the idea that our docs website has a
> > capability to provide such redirects.  You'd probably need to ask
> > about that on the pgsql-www list, unless somebody who knows the
> > answer notices this thread.
>
> There is functionality in pgweb to provide a page alias for whenever a page is
> renamed to keep the links to other versions working.  One example is:
>
>   https://www.postgresql.org/docs/9.4/catalog-pg-replication-slots.html
>   https://www.postgresql.org/docs/17/view-pg-replication-slots.html
>
> There is also a redirect functionality, which isn't used anywhere right now,
> but ideally could be used to redirect bookmarks for /current/<oldname> to
> /current/<newname>.

Thanks to Nathan and Tom for noticing and Daniel for replying. So, if
I understand correctly, pgweb will do this for me without me needing
to do anything in my patch?

- Melanie

> On 9 Jan 2025, at 02:30, Melanie Plageman <melanieplageman@gmail.com> wrote:
>
> On Wed, Jan 8, 2025 at 6:35 AM Daniel Gustafsson <daniel@yesql.se> wrote:
>>
>>> On 7 Jan 2025, at 21:14, Tom Lane <tgl@sss.pgh.pa.us> wrote:
>>
>>> I might be wrong, but I had the idea that our docs website has a
>>> capability to provide such redirects.  You'd probably need to ask
>>> about that on the pgsql-www list, unless somebody who knows the
>>> answer notices this thread.
>>
>> There is functionality in pgweb to provide a page alias for whenever a page is
>> renamed to keep the links to other versions working.  One example is:
>>
>>  https://www.postgresql.org/docs/9.4/catalog-pg-replication-slots.html
>>  https://www.postgresql.org/docs/17/view-pg-replication-slots.html
>>
>> There is also a redirect functionality, which isn't used anywhere right now,
>> but ideally could be used to redirect bookmarks for /current/<oldname> to
>> /current/<newname>.
>
> Thanks to Nathan and Tom for noticing and Daniel for replying. So, if
> I understand correctly, pgweb will do this for me without me needing
> to do anything in my patch?

Correct, it's a setting in the database on the postgresql.org website.

--
Daniel Gustafsson