doc patch: missing tags in protocol.sgml

Started by Hayato Kuroda (Fujitsu)5 months ago5 messages

kuroda.hayato@fujitsu.com

5 months ago

1 attachment(s)

Dear hackers,

I found that in protocol.sgml, the parameter "streaming" is mentioned twice [1]``` The LSN of the abort operation, present only when streaming is set to parallel. ... Abort timestamp of the transaction, present only when streaming is set to parallel. The value is in number of microseconds since PostgreSQL epoch (2000-01-01). ``` but
both are not tagged. IIUC, "streaming" can be <varname> and "parallel" can be <literal>.
Also, the first "streaming" can have a link to the pgoutput's manual. Attached patch fixes like that.

Thanks Peter Smith and Noboru Saito to confirm the point.

[1]: ``` The LSN of the abort operation, present only when streaming is set to parallel. ... Abort timestamp of the transaction, present only when streaming is set to parallel. The value is in number of microseconds since PostgreSQL epoch (2000-01-01). ```
```
The LSN of the abort operation, present only when streaming is set to parallel.
...
Abort timestamp of the transaction, present only when streaming is set to
parallel. The value is in number of microseconds since PostgreSQL epoch (2000-01-01).
```

Best regards,
Hayato Kuroda
FUJITSU LIMITED

Attachments:

0001-doc-Add-missing-tags.patchapplication/octet-stream; name=0001-doc-Add-missing-tags.patchDownload

From 4fc058e33e7c4505d7ef5b35eba5fc7f9ad2e1c8 Mon Sep 17 00:00:00 2001
From: Hayato Kuroda <kuroda.hayato@fujitsu.com>
Date: Thu, 28 Aug 2025 15:39:19 +0900
Subject: [PATCH] doc: Add missing tags

---
 doc/src/sgml/protocol.sgml | 8 +++++---
 1 file changed, 5 insertions(+), 3 deletions(-)

diff --git a/doc/src/sgml/protocol.sgml b/doc/src/sgml/protocol.sgml
index b5395604fb8..b16e4ca17a8 100644
--- a/doc/src/sgml/protocol.sgml
+++ b/doc/src/sgml/protocol.sgml
@@ -7283,7 +7283,8 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;"
        <term>Int64 (XLogRecPtr)</term>
        <listitem>
         <para>
-         The LSN of the abort operation, present only when streaming is set to parallel.
+         The LSN of the abort operation, present only when <link linkend="pgoutput-options-streaming"><varname>streaming</varname></link>
+         is set to <literal>parallel</literal>.
          This field is available since protocol version 4.
         </para>
        </listitem>
@@ -7293,8 +7294,9 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;"
        <term>Int64 (TimestampTz)</term>
        <listitem>
         <para>
-         Abort timestamp of the transaction, present only when streaming is set to
-         parallel. The value is in number of microseconds since PostgreSQL epoch (2000-01-01).
+         Abort timestamp of the transaction, present only when <varname>streaming</varname>
+         is set to <literal>parallel</literal>. The value is in number of
+         microseconds since PostgreSQL epoch (2000-01-01).
          This field is available since protocol version 4.
         </para>
        </listitem>
-- 
2.47.1

Masahiko Sawada

sawada.mshk@gmail.com

5 months ago

In reply to: Hayato Kuroda (Fujitsu) (#1)

Re: doc patch: missing tags in protocol.sgml

On Wed, Aug 27, 2025 at 11:49 PM Hayato Kuroda (Fujitsu)
<kuroda.hayato@fujitsu.com> wrote:

Dear hackers,

I found that in protocol.sgml, the parameter "streaming" is mentioned twice [1] but
both are not tagged. IIUC, "streaming" can be <varname> and "parallel" can be <literal>.
Also, the first "streaming" can have a link to the pgoutput's manual. Attached patch fixes like that.

Looks good to me. I'm going to push the patch, barring any objections.

Regards,

--
Masahiko Sawada
Amazon Web Services: https://aws.amazon.com

Hayato Kuroda (Fujitsu)

kuroda.hayato@fujitsu.com

5 months ago

In reply to: Masahiko Sawada (#2)

2 attachment(s)

RE: doc patch: missing tags in protocol.sgml

Dear Sawada-san,

Thanks for looking the patch.
Actually PG16-18 has the same issue as this, but it does not have the page for
pgoutput. Attached patch sets a link to create_subscription.sgml instead. Thought?

Best regards,
Hayato Kuroda
FUJITSU LIMITED

Attachments:

PG16-18-0001-doc-Add-missing-tags.patchapplication/octet-stream; name=PG16-18-0001-doc-Add-missing-tags.patchDownload

From 4fe08adc9dffb21e225aa853ffe58be76797cdf4 Mon Sep 17 00:00:00 2001
From: Hayato Kuroda <kuroda.hayato@fujitsu.com>
Date: Thu, 28 Aug 2025 15:39:19 +0900
Subject: [PATCH vPG18] doc: Add missing tags

---
 doc/src/sgml/protocol.sgml | 8 +++++---
 1 file changed, 5 insertions(+), 3 deletions(-)

diff --git a/doc/src/sgml/protocol.sgml b/doc/src/sgml/protocol.sgml
index d336ee38f58..cb5958c90e9 100644
--- a/doc/src/sgml/protocol.sgml
+++ b/doc/src/sgml/protocol.sgml
@@ -7309,7 +7309,8 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;"
        <term>Int64 (XLogRecPtr)</term>
        <listitem>
         <para>
-         The LSN of the abort operation, present only when streaming is set to parallel.
+         The LSN of the abort operation, present only when <link linkend="sql-createsubscription-params-with-streaming"><varname>streaming</varname></link>
+         is set to <literal>parallel</literal>.
          This field is available since protocol version 4.
         </para>
        </listitem>
@@ -7319,8 +7320,9 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;"
        <term>Int64 (TimestampTz)</term>
        <listitem>
         <para>
-         Abort timestamp of the transaction, present only when streaming is set to
-         parallel. The value is in number of microseconds since PostgreSQL epoch (2000-01-01).
+         Abort timestamp of the transaction, present only when <varname>streaming</varname>
+         is set to <literal>parallel</literal>. The value is in number of
+         microseconds since PostgreSQL epoch (2000-01-01).
          This field is available since protocol version 4.
         </para>
        </listitem>
-- 
2.47.1

master-0001-doc-Add-missing-tags.patchapplication/octet-stream; name=master-0001-doc-Add-missing-tags.patchDownload

From 4fc058e33e7c4505d7ef5b35eba5fc7f9ad2e1c8 Mon Sep 17 00:00:00 2001
From: Hayato Kuroda <kuroda.hayato@fujitsu.com>
Date: Thu, 28 Aug 2025 15:39:19 +0900
Subject: [PATCH] doc: Add missing tags

---
 doc/src/sgml/protocol.sgml | 8 +++++---
 1 file changed, 5 insertions(+), 3 deletions(-)

diff --git a/doc/src/sgml/protocol.sgml b/doc/src/sgml/protocol.sgml
index b5395604fb8..b16e4ca17a8 100644
--- a/doc/src/sgml/protocol.sgml
+++ b/doc/src/sgml/protocol.sgml
@@ -7283,7 +7283,8 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;"
        <term>Int64 (XLogRecPtr)</term>
        <listitem>
         <para>
-         The LSN of the abort operation, present only when streaming is set to parallel.
+         The LSN of the abort operation, present only when <link linkend="pgoutput-options-streaming"><varname>streaming</varname></link>
+         is set to <literal>parallel</literal>.
          This field is available since protocol version 4.
         </para>
        </listitem>
@@ -7293,8 +7294,9 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;"
        <term>Int64 (TimestampTz)</term>
        <listitem>
         <para>
-         Abort timestamp of the transaction, present only when streaming is set to
-         parallel. The value is in number of microseconds since PostgreSQL epoch (2000-01-01).
+         Abort timestamp of the transaction, present only when <varname>streaming</varname>
+         is set to <literal>parallel</literal>. The value is in number of
+         microseconds since PostgreSQL epoch (2000-01-01).
          This field is available since protocol version 4.
         </para>
        </listitem>
-- 
2.47.1

Masahiko Sawada

sawada.mshk@gmail.com

5 months ago

In reply to: Hayato Kuroda (Fujitsu) (#3)

Re: doc patch: missing tags in protocol.sgml

On Thu, Aug 28, 2025 at 6:53 PM Hayato Kuroda (Fujitsu)
<kuroda.hayato@fujitsu.com> wrote:

Dear Sawada-san,

Thanks for looking the patch.
Actually PG16-18 has the same issue as this, but it does not have the page for
pgoutput. Attached patch sets a link to create_subscription.sgml instead. Thought?

I guess that it would be better to link to "Logical Streaming
Replication Parameters"[1]https://www.postgresql.org/docs/17/protocol-logical-replication.html#PROTOCOL-LOGICAL-REPLICATION-PARAMS since the pgoutput page is derived from
this section. We would have to link to the section instead of
"streaming" parameter but I think it would not be a big issue.

Regards,

[1]: https://www.postgresql.org/docs/17/protocol-logical-replication.html#PROTOCOL-LOGICAL-REPLICATION-PARAMS

--
Masahiko Sawada
Amazon Web Services: https://aws.amazon.com

Hayato Kuroda (Fujitsu)

kuroda.hayato@fujitsu.com

4 months ago

In reply to: Masahiko Sawada (#4)

1 attachment(s)

RE: doc patch: missing tags in protocol.sgml

Dear Sawada-san,

I guess that it would be better to link to "Logical Streaming
Replication Parameters"[1] since the pgoutput page is derived from
this section. We would have to link to the section instead of
"streaming" parameter but I think it would not be a big issue.

Seems better, PSA the fixed version. A patch for master is not changed thus
I did not attach here.

Best regards,
Hayato Kuroda
FUJITSU LIMITED

Attachments:

v2-PG16-18-0001-doc-Add-missing-tags.patchapplication/octet-stream; name=v2-PG16-18-0001-doc-Add-missing-tags.patchDownload

From 73b0bc9d1d57d9b6272eba2caa1655aa34031415 Mon Sep 17 00:00:00 2001
From: Hayato Kuroda <kuroda.hayato@fujitsu.com>
Date: Thu, 28 Aug 2025 15:39:19 +0900
Subject: [PATCH v2-PG18] doc: Add missing tags

---
 doc/src/sgml/protocol.sgml | 8 +++++---
 1 file changed, 5 insertions(+), 3 deletions(-)

diff --git a/doc/src/sgml/protocol.sgml b/doc/src/sgml/protocol.sgml
index d336ee38f58..05f189dad88 100644
--- a/doc/src/sgml/protocol.sgml
+++ b/doc/src/sgml/protocol.sgml
@@ -7309,7 +7309,8 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;"
        <term>Int64 (XLogRecPtr)</term>
        <listitem>
         <para>
-         The LSN of the abort operation, present only when streaming is set to parallel.
+         The LSN of the abort operation, present only when <link linkend="protocol-logical-replication-params"><varname>streaming</varname></link>
+         is set to <literal>parallel</literal>.
          This field is available since protocol version 4.
         </para>
        </listitem>
@@ -7319,8 +7320,9 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;"
        <term>Int64 (TimestampTz)</term>
        <listitem>
         <para>
-         Abort timestamp of the transaction, present only when streaming is set to
-         parallel. The value is in number of microseconds since PostgreSQL epoch (2000-01-01).
+         Abort timestamp of the transaction, present only when <varname>streaming</varname>
+         is set to <literal>parallel</literal>. The value is in number of
+         microseconds since PostgreSQL epoch (2000-01-01).
          This field is available since protocol version 4.
         </para>
        </listitem>
-- 
2.47.1