Typo in "43.9.1. Reporting Errors and Messages"?

Started by PG Doc comments formover 3 years ago14 messages

noreply@postgresql.org

over 3 years ago

The following documentation comment has been logged on the website:

Page: https://www.postgresql.org/docs/14/plpgsql-errors-and-messages.html
Description:

Towards the end of the "43.9.1. Reporting Errors and Messages" section (here
https://www.postgresql.org/docs/current/plpgsql-errors-and-messages.html#PLPGSQL-STATEMENTS-RAISE)
we have the following sentence:

If no condition name nor SQLSTATE is specified in a RAISE EXCEPTION

command, the default is to use ERRCODE_RAISE_EXCEPTION (P0001).

Looking at the list of error codes (here
https://www.postgresql.org/docs/current/errcodes-appendix.html) I think the
"ERRCODE_RAISE_EXCEPTION (P0001)" is a typo and should remove "ERRCODE_" and
simply read "RAISE_EXCEPTION (P0001)" or perhaps "ERRCODE =
'RAISE_EXCEPTION'" since that's how the default behaviour would be written
in a RAISE statement.

Many thanks,
Eric Mutta.

Ekaterina Kiryanova

e.kiryanova@postgrespro.ru

over 3 years ago

In reply to: PG Doc comments form (#1)

1 attachment(s)

PostgreSQL 15 minor fixes in protocol.sgml

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:

protocol.patchtext/x-patch; charset=UTF-8; name=protocol.patchDownload

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>

Michael Paquier

michael@paquier.xyz

over 3 years ago

In reply to: Ekaterina Kiryanova (#2)

Re: PostgreSQL 15 minor fixes in protocol.sgml

On Mon, Aug 01, 2022 at 11:00:20PM +0300, Ekaterina Kiryanova wrote:

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>

Other options use quotes as well in their description in this area.

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.

Both sound pretty much the same to me.

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.

"Prepare for two-phase commit" may be clearer?

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.

Hmm. The internals of 63cf61c refer to a "STREAM PREPARE", still the
protocol docs are quite messy ("prepare", "prepare timestamp", etc.)
so more consistency would be appropriate, it seems. Amit?

The part for the protocol messages with 2PC and logical replication
could use a larger rework. I have left these for now, and fixed the
rest of the typos you have found.
--
Michael