Re: Document if width_bucket's low and high are inclusive/exclusive

[Tom Lane]

Robert Treat  writes:
> Since they are all lower bounds, they all operate the same way, so it
> isn't quite as clear that it needs documenting. Are you thinking
> something like this?

> Returns the number of the bucket in which operand falls given an array
> listing the lower bounds (inclusive) of the buckets

Yeah, though I might write "inclusive lower bounds" rather than use
parens.  What's bugging me though is the lack of any mention of the
bucket upper bounds: you have to deduce that the upper bounds must
be exclusive if the lower bounds are inclusive.  If that's obvious
here, why is it non-obvious for the other case?  Maybe instead of
the parenthetical form you suggested, add a sentence like

Buckets have inclusive lower bounds, and therefore exclusive
upper bounds.

and then we could either rely on the reader remembering that,
or else repeat it, for the second form of width_bucket.

Another thing I just remembered (think I knew it once) is the
behavior of the first form when low > high.  It's not an error!
I think we need to document that, perhaps along the lines of

If low > high, the behavior is mirror-reversed, with bucket 1
now being the one just below low, and the inclusive bounds
now being on the upper side.

plus an example.

regards, tom lane

Minor documentation fixes related to v18

[Fujii Masao]

Hi,

I'd like to propose three minor documentation fixes related to parameters
introduced in v18. Since they align with new content in that version,
I'm thinking to apply them to v18. Thoughts?

0001:
For parameters that exist as both configuration and storage options,
the documentation usually includes secondary index entries to help users
find them easily. However, such entries were missing for vacuum_truncate
and vacuum_max_eager_freeze_failure_rate. This patch adds the appropriate
index terms.

0002:
The description of track_cost_delay_timing lists where cost-based vacuum
delay timing information is shown when the setting is enabled. Although
this information also appears in ANALYZE VERBOSE output, that wasn't
mentioned. This patch adds it to the list.

0003:
The io_workers parameter was documented with the type "int", but
the standard format in our docs is "integer". This patch updates it
for consistency with other GUC parameter descriptions.

Regards,

--
Fujii Masao
NTT DATA Japan Corporation
From eee26a3c056e5c9951cc9c304c8a5b6ce4c44d9c Mon Sep 17 00:00:00 2001
From: Fujii Masao 
Date: Thu, 19 Jun 2025 17:52:58 +0900
Subject: [PATCH v1 1/3] doc: Add secondary index entries for vacuum-related
 parameters.

For parameters that exist as both configuration and storage options,
the documentation typically includes secondary index entries to
help users distinguish and locate the relevant references easily.

However, such index entries were missing for vacuum_truncate and
vacuum_max_eager_freeze_failure_rate, both introduced in v18.

This commit adds appropriate secondary index terms for these parameters
to ensure consistency with other parameters and improve usability of
the documentation index.
---
 doc/src/sgml/config.sgml   | 6 --
 doc/src/sgml/ref/create_table.sgml | 3 ++-
 2 files changed, 6 insertions(+), 3 deletions(-)

diff --git a/doc/src/sgml/config.sgml b/doc/src/sgml/config.sgml
index b265cc89c9d..0ac519706a4 100644
--- a/doc/src/sgml/config.sgml
+++ b/doc/src/sgml/config.sgml
@@ -9340,7 +9340,8 @@ COPY postgres_log FROM '/full/path/to/logfile.csv' WITH 
csv;
   
vacuum_truncate (boolean)

-vacuum_truncate configuration 
parameter
+vacuum_truncate
+configuration parameter



@@ -9544,7 +9545,8 @@ COPY postgres_log FROM '/full/path/to/logfile.csv' WITH 
csv;
  
   vacuum_max_eager_freeze_failure_rate 
(floating point)
   
-   vacuum_max_eager_freeze_failure_rate 
configuration parameter
+   
vacuum_max_eager_freeze_failure_rate
+   configuration parameter
   
   
   
diff --git a/doc/src/sgml/ref/create_table.sgml 
b/doc/src/sgml/ref/create_table.sgml
index 4a41b2f5530..ca1121318c2 100644
--- a/doc/src/sgml/ref/create_table.sgml
+++ b/doc/src/sgml/ref/create_table.sgml
@@ -1687,7 +1687,8 @@ WITH ( MODULUS numeric_literal, REM

 vacuum_truncate, 
toast.vacuum_truncate (boolean)
 
- vacuum_truncate storage parameter
+ vacuum_truncate
+ storage parameter
 
 
 
-- 
2.49.0

From 2e793bae571c83334e2886574dbff0dc34e66a8a Mon Sep 17 00:00:00 2001
From: Fujii Masao 
Date: Thu, 19 Jun 2025 18:27:52 +0900
Subject: [PATCH v1 2/3] doc: Mention ANALYZE VERBOSE in
 track_cost_delay_timing description.

The documentation for track_cost_delay_timing describes where cost-based
vacuum delay timing information is displayed when the setting is enabled.
While this information is also shown in the output of ANALYZE VERBOSE,
that was previously omitted from the list.

This commit updates the documentation to include ANALYZE VERBOSE in the list,
clarifying that it also reports cost-based delay timing information.
---
 doc/src/sgml/config.sgml | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

diff --git a/doc/src/sgml/config.sgml b/doc/src/sgml/config.sgml
index 0ac519706a4..f4ba58bb5c3 100644
--- a/doc/src/sgml/config.sgml
+++ b/doc/src/sgml/config.sgml
@@ -8602,7 +8602,8 @@ COPY postgres_log FROM '/full/path/to/logfile.csv' WITH 
csv;
 timing information is displayed in
 pg_stat_progress_vacuum,
 pg_stat_progress_analyze,
-in the output of  when the
+in the output of  and
+ when the
 VERBOSE option is used, and by autovacuum for
 auto-vacuums and auto-analyzes when
  is set.
-- 
2.49.0

From 08243545f466ad12170d4abadd44dad9d7105d80 Mon Sep 17 00:00:00 2001
From: Fujii Masao 
Date: Thu, 19 Jun 2025 19:08:08 +0900
Subject: [PATCH v1 3/3] doc: Fix type description of io_workers GUC for
 consistency.

The documentation previously described the type of the io_workers GUC
parameter as "int". However, the documentation consistently uses "integer"
for parameters of this type.

This commit updates the type description of io_workers to "integer"
for consistency with other GUC parameter descriptions.
---
 doc/src/sgml/config.sgml | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/doc