Re: Minor documentation fixes related to v18

[Fujii Masao]

On 2025/06/19 19:34, Fujii Masao wrote:

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.


These patches are straightforward fixes. Unless there are any objections,
I'll go ahead and commit them.

Regards,

--
Fujii Masao
NTT DATA Japan Corporation

Re: Minor documentation fixes related to v18

[Fujii Masao]

On 2025/06/25 0:28, Fujii Masao wrote:



On 2025/06/19 19:34, Fujii Masao wrote:

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.


These patches are straightforward fixes. Unless there are any objections,
I'll go ahead and commit them.


Pushed.

Regards,

--
Fujii Masao
NTT DATA Japan Corporation

Re: "NewbieDoc Docbook Guide" link broken

[Daniel Gustafsson]

> On 24 Jun 2025, at 07:04, Michael Paquier  wrote:
> 
> On Tue, Jun 24, 2025 at 12:17:46PM +0800, jian he wrote:
>> in https://www.postgresql.org/docs/current/docguide-docbook.html
>> the link (https://newbiedoc.sourceforge.net/metadoc/docbook-guide.html)
>> for (NewbieDoc Docbook Guide) is broken.
>> 
>> google around I found this [2]
>> [2]: 
>> https://ftp.sun.ac.za/ftp/pub/documentation/newbiedoc/newbiedoc-html/docbook-guide.en/index-docbook-guide.html
> 
> Not sure that it is a good idea to point to an external site while the
> original site of the project is still around:
> https://sourceforge.net/projects/newbiedoc/.
> 
> At the same time, perhaps there are better resources than a project
> that had no updates since 2011, or we could consider removing this
> reference.  I have never used it, but perhaps some find it useful.

Downloading what newbiedoc still ships shows no trace of docbook introdoctions,
so whatever we decided valuable back in the 8.1 days when this was added seems
gone now.  I propose to apply the below and simply remove it.

--- a/doc/src/sgml/docguide.sgml
+++ b/doc/src/sgml/docguide.sgml
@@ -60,9 +60,7 @@
maintained by the https://www.oasis-open.org";>
OASIS group.  The https://www.oasis-open.org/docbook/";>
official DocBook site has good introductory and reference 
documentation and
-   a complete O'Reilly book for your online reading pleasure.  The
-   http://newbiedoc.sourceforge.net/metadoc/docbook-guide.html";>
-   NewbieDoc Docbook Guide is very helpful for beginners.
+   a complete O'Reilly book for your online reading pleasure.
The https://www.freebsd.org/docproj/";>
FreeBSD Documentation Project also uses DocBook and has some good
information, including a number of style guidelines that might be

--
Daniel Gustafsson

Re: Fix incorrect UUID index entry in function documentation

[Daniel Gustafsson]

> On 24 Jun 2025, at 07:37, Fujii Masao  wrote:

> I've committed the proposed patch first. If we later agree to change
> this part as well, we can commit that separately.

What you committed is perfectly fine, thanks!

--
Daniel Gustafsson

Re: "NewbieDoc Docbook Guide" link broken

[Michael Paquier]

On Tue, Jun 24, 2025 at 12:17:46PM +0800, jian he wrote:
> in https://www.postgresql.org/docs/current/docguide-docbook.html
> the link (https://newbiedoc.sourceforge.net/metadoc/docbook-guide.html)
> for (NewbieDoc Docbook Guide) is broken.
> 
> google around I found this [2]
> [2]: 
> https://ftp.sun.ac.za/ftp/pub/documentation/newbiedoc/newbiedoc-html/docbook-guide.en/index-docbook-guide.html

Not sure that it is a good idea to point to an external site while the
original site of the project is still around:
https://sourceforge.net/projects/newbiedoc/.

At the same time, perhaps there are better resources than a project
that had no updates since 2011, or we could consider removing this
reference.  I have never used it, but perhaps some find it useful.
--
Michael


signature.asc
Description: PGP signature

Re: "NewbieDoc Docbook Guide" link broken

[Magnus Hagander]

On Tue, Jun 24, 2025 at 9:20 AM Daniel Gustafsson  wrote:

> > On 24 Jun 2025, at 07:04, Michael Paquier  wrote:
> >
> > On Tue, Jun 24, 2025 at 12:17:46PM +0800, jian he wrote:
> >> in https://www.postgresql.org/docs/current/docguide-docbook.html
> >> the link (https://newbiedoc.sourceforge.net/metadoc/docbook-guide.html)
> >> for (NewbieDoc Docbook Guide) is broken.
> >>
> >> google around I found this [2]
> >> [2]:
> https://ftp.sun.ac.za/ftp/pub/documentation/newbiedoc/newbiedoc-html/docbook-guide.en/index-docbook-guide.html
> >
> > Not sure that it is a good idea to point to an external site while the
> > original site of the project is still around:
> > https://sourceforge.net/projects/newbiedoc/.
> >
> > At the same time, perhaps there are better resources than a project
> > that had no updates since 2011, or we could consider removing this
> > reference.  I have never used it, but perhaps some find it useful.
>
> Downloading what newbiedoc still ships shows no trace of docbook
> introdoctions,
> so whatever we decided valuable back in the 8.1 days when this was added
> seems
> gone now.  I propose to apply the below and simply remove it.
>
> --- a/doc/src/sgml/docguide.sgml
> +++ b/doc/src/sgml/docguide.sgml
> @@ -60,9 +60,7 @@
> maintained by the https://www.oasis-open.org";>
> OASIS group.  The https://www.oasis-open.org/docbook/";>
> official DocBook site has good introductory and reference
> documentation and
> -   a complete O'Reilly book for your online reading pleasure.  The
> -   http://newbiedoc.sourceforge.net/metadoc/docbook-guide.html";>
> -   NewbieDoc Docbook Guide is very helpful for beginners.
> +   a complete O'Reilly book for your online reading pleasure.
> The https://www.freebsd.org/docproj/";>
> FreeBSD Documentation Project also uses DocBook and has some
> good
> information, including a number of style guidelines that might be
>


+1.

-- 
 Magnus Hagander
 Me: https://www.hagander.net/ 
 Work: https://www.redpill-linpro.com/ 

Re: "NewbieDoc Docbook Guide" link broken

[Michael Paquier]

On Tue, Jun 24, 2025 at 09:36:20AM +0200, Magnus Hagander wrote:
> On Tue, Jun 24, 2025 at 9:20 AM Daniel Gustafsson  wrote:
>> Downloading what newbiedoc still ships shows no trace of docbook
>> introdoctions,
>> so whatever we decided valuable back in the 8.1 days when this was added
>> seems
>> gone now.  I propose to apply the below and simply remove it.
> 
> +1.

+1.
--
Michael


signature.asc
Description: PGP signature

Re: "NewbieDoc Docbook Guide" link broken

[Daniel Gustafsson]

> On 24 Jun 2025, at 09:44, Michael Paquier  wrote:
> 
> On Tue, Jun 24, 2025 at 09:36:20AM +0200, Magnus Hagander wrote:
>> On Tue, Jun 24, 2025 at 9:20 AM Daniel Gustafsson  wrote:
>>> Downloading what newbiedoc still ships shows no trace of docbook
>>> introdoctions,
>>> so whatever we decided valuable back in the 8.1 days when this was added
>>> seems
>>> gone now.  I propose to apply the below and simply remove it.
>> 
>> +1.
> 
> +1.

Done, backpatched down to 13.

--
Daniel Gustafsson