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