pg.ddx.io  pgsql-docs@postgresql.org mailing list archive  

help / color / mirror / Atom feed

From: Ekaterina Kiryanova <e.kiryanova@postgrespro.ru>
To: pgsql-docs@lists.postgresql.org
Subject: PostgreSQL 15 minor fixes in protocol.sgml
Date: Mon, 1 Aug 2022 23:00:20 +0300
Message-ID: <745414e7-efb2-a6ae-5b83-fcbdf35aabc8@postgrespro.ru> (raw)
In-Reply-To: <165931062346.271448.12881330344096283605@wrigleys.postgresql.org>
References: <165931062346.271448.12881330344096283605@wrigleys.postgresql.org>

Hello!

I've come across some typos in protocol.sgml for PostgreSQL 15 so please 
have a look at the attached patch.

I didn't include it in the patch but I also suggest removing single 
quotes around 'method' for the COMPRESSION option to help avoid 
confusion. (All the supported compression methods consist of a single 
word so in my opinion there is no need to use quotes in this case.)
-- <term><literal>COMPRESSION</literal> 
<replaceable>'method'</replaceable></term>

I've also noticed that there are two ways to describe an option: "If set 
to true" / "If true". As far as I know, the option here is specified by 
its name rather than being explicitly set to true so "if true" seems to 
be more correct, and this could be a slight improvement for this page. 
Please correct me if I'm wrong.

Another point worth mentioning is that only this file contains the 
phrase "two-phase transaction". I believe that "two-phase commit 
transaction" or "transaction prepared for two-phase commit" depending on 
the situation would be better wording.

And finally, could you please clarify this part?
-- The end LSN of the prepare transaction.
Is it a typo of "prepared transaction"? Or is it the LSN of the 
transaction for Prepare?
If it's the latter, perhaps it'd make more sense to capitalize it.

-- 
Best regards,
Ekaterina Kiryanova
Technical Writer
Postgres Professional
the Russian PostgreSQL Company

Attachments:

  [text/x-patch] protocol.patch (11.8K, ../745414e7-efb2-a6ae-5b83-fcbdf35aabc8@postgrespro.ru/2-protocol.patch)
  download | inline diff:
diff --git a/doc/src/sgml/protocol.sgml b/doc/src/sgml/protocol.sgml
index 393311d304..f832aebfa6 100644
--- a/doc/src/sgml/protocol.sgml
+++ b/doc/src/sgml/protocol.sgml
@@ -2727,42 +2727,42 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;"
 
         <varlistentry>
          <term><literal>COMPRESSION</literal> <replaceable>'method'</replaceable></term>
          <listitem>
           <para>
            Instructs the server to compress the backup using the specified
            method. Currently, the supported methods are <literal>gzip</literal>,
            <literal>lz4</literal>, and <literal>zstd</literal>.
           </para>
          </listitem>
         </varlistentry>
 
         <varlistentry>
          <term><literal>COMPRESSION_DETAIL</literal> <replaceable>detail</replaceable></term>
          <listitem>
           <para>
            Specifies details for the chosen compression method. This should only
            be used in conjunction with the <literal>COMPRESSION</literal>
            option.  If the value is an integer, it specifies the compression
            level.  Otherwise, it should be a comma-separated list of items,
-           each of the form <literal>keyword</literal> or
-           <literal>keyword=value</literal>. Currently, the supported keywords
+           each of the form <replaceable>keyword</replaceable> or
+           <replaceable>keyword=value</replaceable>. Currently, the supported keywords
            are <literal>level</literal> and <literal>workers</literal>.
           </para>
 
           <para>
            The <literal>level</literal> keyword sets the compression level.
            For <literal>gzip</literal> the compression level should be an
            integer between 1 and 9, for <literal>lz4</literal> an integer
            between 1 and 12, and for <literal>zstd</literal> an integer
            between 1 and 22.
           </para>
 
           <para>
            The <literal>workers</literal> keyword sets the number of threads
            that should be used for parallel compression. Parallel compression
            is supported only for <literal>zstd</literal>.
           </para>
          </listitem>
         </varlistentry>
 
         <varlistentry>
@@ -2887,111 +2887,111 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;"
           </para>
          </listitem>
         </varlistentry>
        </variablelist>
       </para>
 
       <para>
        After the second regular result set, a CopyOutResponse will be sent.
        The payload of each CopyData message will contain a message in one of
        the following formats:
       </para>
 
       <variablelist>
        <varlistentry>
         <term>new archive (B)</term>
         <listitem>
          <variablelist>
           <varlistentry>
            <term>Byte1('n')</term>
            <listitem><para>
-            Identifes the messaage as indicating the start of a new archive.
+            Identifies the message as indicating the start of a new archive.
             There will be one archive for the main data directory and one
             for each additional tablespace; each will use tar format
             (following the <quote>ustar interchange format</quote> specified
             in the POSIX 1003.1-2008 standard).
            </para></listitem>
           </varlistentry>
 
           <varlistentry>
            <term>String</term>
            <listitem><para>
             The file name for this archive.
            </para></listitem>
           </varlistentry>
 
           <varlistentry>
            <term>String</term>
            <listitem><para>
             For the main data directory, an empty string. For other
             tablespaces, the full path to the directory from which this
             archive was created.
            </para></listitem>
           </varlistentry>
          </variablelist>
         </listitem>
        </varlistentry>
 
        <varlistentry>
         <term>manifest (B)</term>
         <listitem>
          <variablelist>
           <varlistentry>
            <term>Byte1('m')</term>
            <listitem><para>
-            Identifes the message as indicating the start of the backup
+            Identifies the message as indicating the start of the backup
             manifest.
            </para></listitem>
           </varlistentry>
          </variablelist>
         </listitem>
        </varlistentry>
 
        <varlistentry>
         <term>archive or manifest data (B)</term>
         <listitem>
          <variablelist>
           <varlistentry>
            <term>Byte1('d')</term>
            <listitem><para>
-            Identifes the message as containing archive or manifest data.
+            Identifies the message as containing archive or manifest data.
            </para></listitem>
           </varlistentry>
 
           <varlistentry>
            <term>Byte<replaceable>n</replaceable></term>
            <listitem><para>
             Data bytes.
            </para></listitem>
           </varlistentry>
          </variablelist>
         </listitem>
        </varlistentry>
 
        <varlistentry>
         <term>progress report (B)</term>
         <listitem>
          <variablelist>
           <varlistentry>
            <term>Byte1('p')</term>
            <listitem><para>
-            Identifes the message as a progress report.
+            Identifies the message as a progress report.
            </para></listitem>
           </varlistentry>
 
           <varlistentry>
            <term>Int64</term>
            <listitem><para>
             The number of bytes from the current tablespace for which
             processing has been completed.
            </para></listitem>
           </varlistentry>
          </variablelist>
         </listitem>
        </varlistentry>
       </variablelist>
 
       <para>
        After the CopyOutResponse, or all such responses, have been sent, a
        final ordinary result set will be sent, containing the WAL end position
        of the backup, in the same format as the start position.
       </para>
@@ -6924,41 +6924,41 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;"
         <para>
          Prepare timestamp of the transaction. The value is in number
          of microseconds since PostgreSQL epoch (2000-01-01).
         </para>
        </listitem>
       </varlistentry>
 
       <varlistentry>
        <term>Int32 (TransactionId)</term>
        <listitem>
         <para>
          Xid of the transaction.
         </para>
        </listitem>
       </varlistentry>
 
       <varlistentry>
        <term>String</term>
        <listitem>
         <para>
-         The user defined GID of the two-phase transaction.
+         The user-defined GID of the two-phase transaction.
         </para>
        </listitem>
       </varlistentry>
      </variablelist>
     </listitem>
    </varlistentry>
 
    <varlistentry id="protocol-logicalrep-message-formats-Prepare">
     <term>Prepare</term>
     <listitem>
      <variablelist>
       <varlistentry>
        <term>Byte1('P')</term>
        <listitem>
         <para>
          Identifies the message as a two-phase prepared transaction message.
         </para>
        </listitem>
       </varlistentry>
 
@@ -6995,41 +6995,41 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;"
         <para>
          Prepare timestamp of the transaction. The value is in number
          of microseconds since PostgreSQL epoch (2000-01-01).
         </para>
        </listitem>
       </varlistentry>
 
       <varlistentry>
        <term>Int32 (TransactionId)</term>
        <listitem>
         <para>
          Xid of the transaction.
         </para>
        </listitem>
       </varlistentry>
 
       <varlistentry>
        <term>String</term>
        <listitem>
         <para>
-         The user defined GID of the two-phase transaction.
+         The user-defined GID of the two-phase transaction.
         </para>
        </listitem>
       </varlistentry>
      </variablelist>
     </listitem>
    </varlistentry>
 
    <varlistentry id="protocol-logicalrep-message-formats-Commit-Prepared">
     <term>Commit Prepared</term>
     <listitem>
      <variablelist>
       <varlistentry>
        <term>Byte1('K')</term>
        <listitem>
         <para>
          Identifies the message as the commit of a two-phase transaction message.
         </para>
        </listitem>
       </varlistentry>
 
@@ -7066,41 +7066,41 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;"
         <para>
          Commit timestamp of the transaction. The value is in number
          of microseconds since PostgreSQL epoch (2000-01-01).
         </para>
        </listitem>
       </varlistentry>
 
       <varlistentry>
        <term>Int32 (TransactionId)</term>
        <listitem>
         <para>
          Xid of the transaction.
         </para>
        </listitem>
       </varlistentry>
 
       <varlistentry>
        <term>String</term>
        <listitem>
         <para>
-         The user defined GID of the two-phase transaction.
+         The user-defined GID of the two-phase transaction.
         </para>
        </listitem>
       </varlistentry>
      </variablelist>
     </listitem>
    </varlistentry>
 
    <varlistentry id="protocol-logicalrep-message-formats-Rollback-Prepared">
     <term>Rollback Prepared</term>
     <listitem>
      <variablelist>
       <varlistentry>
        <term>Byte1('r')</term>
        <listitem>
         <para>
          Identifies the message as the rollback of a two-phase transaction message.
         </para>
        </listitem>
       </varlistentry>
 
@@ -7147,41 +7147,41 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;"
         <para>
          Rollback timestamp of the transaction. The value is in number
          of microseconds since PostgreSQL epoch (2000-01-01).
         </para>
        </listitem>
       </varlistentry>
 
       <varlistentry>
        <term>Int32 (TransactionId)</term>
        <listitem>
         <para>
          Xid of the transaction.
         </para>
        </listitem>
       </varlistentry>
 
       <varlistentry>
        <term>String</term>
        <listitem>
         <para>
-         The user defined GID of the two-phase transaction.
+         The user-defined GID of the two-phase transaction.
         </para>
        </listitem>
       </varlistentry>
      </variablelist>
     </listitem>
    </varlistentry>
 
    <varlistentry id="protocol-logicalrep-message-formats-Stream-Prepare">
     <term>Stream Prepare</term>
     <listitem>
      <variablelist>
       <varlistentry>
        <term>Byte1('p')</term>
        <listitem>
         <para>
          Identifies the message as a two-phase stream prepare message.
         </para>
        </listitem>
       </varlistentry>
 
@@ -7218,41 +7218,41 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;"
         <para>
          Prepare timestamp of the transaction. The value is in number
          of microseconds since PostgreSQL epoch (2000-01-01).
         </para>
        </listitem>
       </varlistentry>
 
       <varlistentry>
        <term>Int32 (TransactionId)</term>
        <listitem>
         <para>
          Xid of the transaction.
         </para>
        </listitem>
       </varlistentry>
 
       <varlistentry>
        <term>String</term>
        <listitem>
         <para>
-         The user defined GID of the two-phase transaction.
+         The user-defined GID of the two-phase transaction.
         </para>
        </listitem>
       </varlistentry>
      </variablelist>
     </listitem>
    </varlistentry>
   </variablelist>
 
   <para>
    The following message parts are shared by the above messages.
   </para>
 
   <variablelist>
    <varlistentry id="protocol-logicalrep-message-formats-TupleData">
     <term>TupleData</term>
     <listitem>
      <variablelist>
       <varlistentry>
        <term>Int16</term>
        <listitem>

view thread (8+ messages)  latest in thread

Message-ID: <745414e7-efb2-a6ae-5b83-fcbdf35aabc8@postgrespro.ru>
Permalink:  ../745414e7-efb2-a6ae-5b83-fcbdf35aabc8@postgrespro.ru/
Also on:    postgresql.org/message-id/745414e7-efb2-a6ae-5b83-fcbdf35aabc8@postgrespro.ru

copy link · copy postgr.es · copy git am

reply

Reply instructions:

You may reply publicly to this message via plain-text email
using any one of the following methods:

* Reply to all the recipients using the --to and --cc options:
  reply via email

  To: pgsql-docs@postgresql.org
  Cc: e.kiryanova@postgrespro.ru, pgsql-docs@lists.postgresql.org
  Subject: Re: PostgreSQL 15 minor fixes in protocol.sgml
  In-Reply-To: <745414e7-efb2-a6ae-5b83-fcbdf35aabc8@postgrespro.ru>

* Save the following mbox file, import it into your mail client,
  and reply-to-all from there: mbox

This inbox is served by DDX for PostgreSQL; see mirroring instructions
for how to clone and mirror all data and code used for this inbox