Merge pull request #5200 from EnterpriseDB/pgd/BDR-4555-bdr_join_node…

…_group-fix

pgd: fixes for bdr.join_node_group() reference documentation

product_docs/docs/pgd/5/reference/nodes-management-interfaces.mdx

@@ -362,7 +362,7 @@ This function joins the local node to an already existing PGD group.
 bdr.join_node_group (
     join_target_dsn text,
     node_group_name text DEFAULT NULL,
-    pause_in_standby boolean DEFAULT false,
+    pause_in_standby boolean DEFAULT NULL,
     wait_for_completion boolean DEFAULT true,
     synchronize_structure text DEFAULT 'all'
 )
@@ -373,22 +373,30 @@ bdr.join_node_group (
 -   `join_target_dsn` — Specifies the connection string to an existing (source) node
      in the PGD group you want to add the local node to.
 -   `node_group_name` — Optional name of the PGD group. Defaults to NULL, which
-    tries to detect the group name from information present on the source
-    node.
--   `pause_in_standby` — Optionally tells the join process to join only as a
-    logical standby node, which can be later promoted to a full member.
+     tries to detect the group name from information present on the source
+     node.
 -   `wait_for_completion` — Wait for the join process to complete before
-    returning. Defaults to `true`.
+     returning. Defaults to `true`.
 -   `synchronize_structure` — Set the kind of structure (schema) synchronization
-    to do during the join. Valid options are `all`, which synchronizes
-    the complete database structure, and `none`, which doesn't synchronize any
-    structure. However, it still synchronizes data.
+     to do during the join. Valid options are `all`, which synchronizes
+     the complete database structure, and `none`, which doesn't synchronize any
+     structure. However, it still synchronizes data.
+-   `pause_in_standby` — Optionally tells the join process to join only as a
+     logical standby node, which can be later promoted to a full member.
+     This option is deprecated and will be disabled or removed in future
+     versions of PGD.
 
-If `wait_for_completion` is specified as `false`,
-this is an asynchronous call that returns as soon as the joining procedure starts.
-You can see progress of the join in logs and the
-`bdr.event_summary` information view or by calling the
-`bdr.wait_for_join_completion()` function after `bdr.join_node_group()` returns.
+!!! Warning
+    `pause_in_standby` is deprecated since BDR 5.0. The recommended way to create
+    a logical standby is to set `node_kind` to `standby` when creating the node
+    with `[bdr.create_node](#bdrcreate_node)`.
+
+If `wait_for_completion` is specified as `false`, the function call will return
+as soon as the joining procedure starts. Progress of the join can be viewed in
+the log files and the `[bdr.event_summary](catalogs-internal.mdx#bdrevent_summary)`
+information view. The function `[bdr.wait_for_join_completion()](#bdrwait_for_join_completion)`
+can be called after `bdr.join_node_group()` to wait for the join operation to complete,
+and can emit progress information if called with `verbose_progress` set to `true`.
 
 ### Notes