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 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:
- ICUICU
+ ICU
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 .) The properties
+ by sequences (see ). 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 failover 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 .
-for not-null constraints at all, so they are not
+for NOT NULL constraints at all, so they are not
I'm still not convinced that this change makes the documentation more readable.
- the MERGE command will perform a
FULL
- join between data_source
- and the target table. For this to work, at least one
+ the MERGE command will perform a
+ FULL JOIN between
+ data_source 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
diff --git a/doc/src/sgml/catalogs.sgml b/doc/src/sgml/catalogs.sgml
index bfb97865e18..964c819a02d 100644
--- a/doc/src/sgml/catalogs.sgml
+++ b/doc/src/sgml/catalogs.sgml
@@ -8024,41 +8024,41 @@ SCRAM-SHA-256$:&l
for authentication
subrunasowner bool
If true, the subscription will be run with the permissions
of the subscription owner
subfailover bool
If true, the associated replication slots (i.e. the main slot and the
- table sync slots) in the upstream database are enabled to be
+ table synchronization slots) in the upstream database are enabled to be
synchronized to the standbys
subconninfo text
Connection string to the upstream database
subslotname name
Name of the replication slot in the upstream database (also used
for the local replication origin name);
diff --git a/doc/src/sgml/charset.sgml b/doc/src/sgml/charset.sgml
index 834cb30c85a..dbbf7fc3726 100644
--- a/doc/src/sgml/charset.sgml
+++ b/doc/src/sgml/charset.sgml
@@ -365,41 +365,41 @@ initdb --locale-provider=icu --icu-locale=en
Regardless of the locale provider, the operating system is still used to
provide some locale-aware behavior, such as messages (see ).
The available locale providers are listed below:
builtin
The builtin provider uses built-in operations. Only
the C and C.UTF-8 locales are
supported for this provider.
The C locale behavior is identical to the
- C locale in the libc provider. When using this
+ C locale in the libc provider. When using this
locale, the behavior may depend on the database encoding.
The C.UTF-8 locale is available only for when the
database encoding is UTF-8, and the behavior is
based on Unicode. The collation uses the code point valu
