Re: Documentation improvement patch

Thank you for your kind feedback! I will take due note of the comments
in the next documentation patches as well.

I have made all the changes as per your feedback and also corrected
paragraph reflow.

The third version of the patch is attached for your consideration.

--
Oleg Sibiryakov

On 01.10.2024 11:59, Daniel Gustafsson wrote:
>> On 1 Oct 2024, at 10:04, Oleg Sibiryakov <o(dot)sibiryakov(at)postgrespro(dot)ru> wrote:
>> Here is a kind reminder of a small documentation improvement patch, which we started discussing a month ago.
>>
>> I removed all the controversial points touched upon in this thread. Please, take a look once again at your convenience.
> In general, when submitting a docs patch it's better to not reflow the
> paragraphs when a modified line becomes too long. Reading a 4 line diff where
> only one thing changed in the first becomes harder than reading a single line
> diff where the line is long. The committer can ensure the lines are reflowed
> prior to a commit, or it can be left as the final revision of a patch
> submission once all changes are discussed-
>
> A few comments on this version of the patch:
>
>
> - ICU<indexterm><primary>ICU</primary></indexterm>
> + <indexterm><primary>ICU</primary></indexterm>
>
> I don't think removing the name of the library changing the sentence from "The
> icu provider uses the external ICU library" to "The icu provider uses the
> external library" is an improvement.
>
>
> - by sequences. (See <xref linkend="sql-createsequence"/>.) The properties
> + by sequences (see <xref linkend="sql-createsequence"/>). The properties
>
> This is a common construction in our docs, if it's considered to be a bad
> practice the case should be argued (separately) for removing all of them
> instead.
>
>
> - Comma separated list of publication names for which to subscribe
> + Comma-separated list of publication names for which to subscribe
>
> There are two more cases of "comma separated" (config.sgml and copy.sgml),
> should they be changed too?
>
>
> - the failover if required, enable the subscription, and refresh the
> - subscription. See
> + the <literal>failover</literal> if required, enable the subscription,
> + and refresh the subscription. See
>
> This refers to the act of failing over, not the property value failover, and
> should not be in <literal>.
>
>
> - for not-null constraints at all, so they are not
> + for <literal>NOT NULL</literal> constraints at all, so they are not
>
> I'm still not convinced that this change makes the documentation more readable.
>
>
> - the <command>MERGE</command> command will perform a <literal>FULL</literal>
> - join between <replaceable class="parameter">data_source</replaceable>
> - and the target table. For this to work, at least one
> + the <command>MERGE</command> command will perform a
> + <literal>FULL JOIN</literal> between
> + <replaceable class="parameter">data_source</replaceable> and the target
> + table. For this to work, at least one
>
> This paragraph discuss various join types, keeping it lowercase "join" matches
> the remainder of the paragraph and makes it more readable IMHO. It's not
> discussing syntax the user is expected to type so need to make it so.
>
> --
> Daniel Gustafsson
>