Thread: Can we delete the vacuumdb.sgml notes about which version each option was added in?

I was just looking at the vacuumdb docs and noticed that I had
neglected to follow the tradition of adding a note to mention which
version we added the new option in when I committed the
--buffer-usage-limit patch.

There are 3 notes there that read "This option is only available for
servers running PostgreSQL 9.6 and later.".  Since 9.6 is a few years
out of support, can we get rid of these 3?

Or better yet, can we just delete them all?  Is it really worth doing
this in case someone is using a new vacuumdb on an older server?

I just tried compiling the HTML with all the notes removed, I see from
looking at a print preview that it's now ~1 full A4 page shorter than
it was previously.  5 pages down to 4.

Does anyone think we should keep these?

David

On Sun, Apr 16, 2023 at 10:14:35PM +1200, David Rowley wrote:
> There are 3 notes there that read "This option is only available for
> servers running PostgreSQL 9.6 and later.".  Since 9.6 is a few years
> out of support, can we get rid of these 3?

+1

> Or better yet, can we just delete them all?  Is it really worth doing
> this in case someone is using a new vacuumdb on an older server?
> 
> I just tried compiling the HTML with all the notes removed, I see from
> looking at a print preview that it's now ~1 full A4 page shorter than
> it was previously.  5 pages down to 4.
> 
> Does anyone think we should keep these?

I'm +0.5 for removing all of them.  While they are still relevant and could
potentially help users, these notes are taking up a rather big portion of
the vacuumdb page, and it should print a nice error message if you try to
use an option on and older server, anyway.

-- 
Nathan Bossart
Amazon Web Services: https://aws.amazon.com

On Sun, Apr 16, 2023 at 10:14:35PM +1200, David Rowley wrote:
> I was just looking at the vacuumdb docs and noticed that I had
> neglected to follow the tradition of adding a note to mention which
> version we added the new option in when I committed the
> --buffer-usage-limit patch.
> 
> There are 3 notes there that read "This option is only available for
> servers running PostgreSQL 9.6 and later.".  Since 9.6 is a few years
> out of support, can we get rid of these 3?
> 
> Or better yet, can we just delete them all?  Is it really worth doing
> this in case someone is using a new vacuumdb on an older server?
> 
> I just tried compiling the HTML with all the notes removed, I see from
> looking at a print preview that it's now ~1 full A4 page shorter than
> it was previously.  5 pages down to 4.
> 
> Does anyone think we should keep these?

I don't know if I'd support removing the notes, but I agree that they
don't need to take up anywhere near as much space as they do (especially
since the note is now repeated 10 times).

https://www.postgresql.org/docs/devel/app-vacuumdb.html

I suggest to remove the <note> markup and preserve the annotation about
version compatibility.  It's normal, technical writing to repeat the
same language like that.

Another, related improvement I suggested would be to group the
client-side options separately from the server-side options.
https://www.postgresql.org/message-id/ZBYDTrD1kyGg+HkS@telsasoft.com

-- 
Justin

Justin Pryzby <pryzby@telsasoft.com> writes:
> On Sun, Apr 16, 2023 at 10:14:35PM +1200, David Rowley wrote:
>> Does anyone think we should keep these?

> I don't know if I'd support removing the notes, but I agree that they
> don't need to take up anywhere near as much space as they do (especially
> since the note is now repeated 10 times).

I agree with removing the notes.  It has always been our policy that
you should read the version of the manual that applies to the version
you're running.  I can see leaving a compatibility note around for a
long time when it's warning you that some behavior changed compared
to what the same syntax used to do.  But if a switch simply isn't
there in some older version, that's not terribly dangerous or hard to
figure out.

> I suggest to remove the <note> markup and preserve the annotation about
> version compatibility.  It's normal, technical writing to repeat the
> same language like that.

Another way could be to move them all into a "Compatibility" section.
But +1 for just dropping them.

            regards, tom lane

On Mon, 17 Apr 2023 at 02:29, Tom Lane <tgl@sss.pgh.pa.us> wrote:
> But +1 for just dropping them.

Thanks. I just pushed the patch to drop them all.

David