Re: Document How Commit Handles Aborted Transactions

On Wed, Jan 1, 2025 at 11:16 PM Gurjeet Singh <gurjeet(at)singh(dot)im> wrote:

> > On Fri, Dec 20, 2024 at 9:02 AM David G. Johnston <
> david(dot)g(dot)johnston(at)gmail(dot)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.