Re: Document How Commit Handles Aborted Transactions

On Wed, Jan 1, 2025 at 11:16 PM Gurjeet Singh <gurjeet@singh.im> wrote:

> > On Fri, Dec 20, 2024 at 9:02 AM David G. Johnston <
> david.g.johnston@gmail.com> wrote:
>
> >> The commit reference page lacks an "Outputs" section even though it is
> capable of outputting both "COMMIT" and "ROLLBACK".
>
> I generally agree with the improvements proposed. I currently don't
> have the infrastructure to build docs, so the following review is
> without the benefit of what the build output looks like.
>

Thank you for the review.  Version 2 Attached.


> This line in the patch has a trailing whitespace, which should be removed.
>
> +    <xref linkend="sql-begin"/> and
>

Done


> I believe this sentence can be improved slightly:
>
> +    When a failure does occur during a transaction it is not ended but
> instead
> +    goes into an aborted state.
>
> as: When an error occurs in a transaction block, the transaction goes
> into an aborted state.
>

Agreed, and changed the existing usage of failure to error to match.


> So this seems like a better statement: If the transaction is in an
> aborted state, say, because of an error, then the effect of the
> <command>COMMIT</> will be identical to that of <command>ROLLBACK</>,
> including the command tag output.
>

I went with:

+   If the transaction is in an aborted state then no changes will be made
+   and the effect of the <command>COMMIT</command> will be identical to
that
+   of <command>ROLLBACK</command>, including the command tag output.


> The following needs to be rephrased:
>
> +   However, if the transaction being affected is aborted, a
> <command>COMMIT</command>
> +   command returns a command tag of the form
>
> as: However, if the transaction is in an aborted state, the
> <command>COMMIT</> command ...
>

I went with this, keeping the phrasing "on an" consistent between this and
the previous text.

+   However, on an aborted transaction, a <command>COMMIT</command>
+   command returns a command tag of the form

The use of "a/an" instead of "the" is supported by existing phrasing for
Insert.

"On successful completion, an INSERT command returns a command tag of the
form"

David J.