Doc: further clarify libpq's description of connection string URIs.

Break the synopsis into named parts to make it less confusing.
Make more than zero effort at applying SGML markup.  Do a bit
of copy-editing of nearby text.

The synopsis revision is by Alvaro Herrera and Paul Förster,
the rest is my fault.  Back-patch to v10 where multi-host
connection strings appeared.

Discussion: https://postgr.es/m/6E752D6B-487C-463E-B6E2-C32E7FB007EA@gmail.com

diff --git a/doc/src/sgml/libpq.sgml b/doc/src/sgml/libpq.sgml
index 5e25f20843c1110bce65dd872a9751ef17f70975..c635b6570c134c9b67f762783356df3d7ab18752 100644 (file)
--- a/doc/src/sgml/libpq.sgml
+++ b/doc/src/sgml/libpq.sgml
@@ -866,7 +866,7 @@ PQsslKeyPassHook_OpenSSL_type PQgetSSLKeyPassHook_OpenSSL(void);
    
     Several libpq functions parse a user-specified string to obtain
     connection parameters.  There are two accepted formats for these strings:
-    plain keyword = value strings
+    plain keyword/value strings
     and URIs.  URIs generally follow
     RFC
     3986, except that multi-host connection strings are allowed
@@ -877,12 +877,14 @@ PQsslKeyPassHook_OpenSSL_type PQgetSSLKeyPassHook_OpenSSL(void);
     Keyword/Value Connection Strings
 
    
-    In the first format, each parameter setting is in the form
-    keyword = value.  Spaces around the equal sign are
+    In the keyword/value format, each parameter setting is in the form
+    keyword =
+    value, with space(s) between settings.
+    Spaces around a setting's equal sign are
     optional. To write an empty value, or a value containing spaces, surround it
-    with single quotes, e.g., keyword = 'a value'. Single
-    quotes and backslashes within
-    the value must be escaped with a backslash, i.e., \' and
+    with single quotes, for example keyword = 'a value'.
+    Single quotes and backslashes within
+    a value must be escaped with a backslash, i.e., \' and
     \\.
    
 
@@ -905,7 +907,19 @@ host=localhost port=5432 dbname=mydb connect_timeout=10
    
    The general form for a connection URI is:
 
-postgresql://[user[:password]@][host][:port][,...][/dbname][?param1=value1&...]
+postgresql://userspec@hostspec/dbname?paramspec
+
+where userspec is:
+
+user:password
+
+and hostspec is:
+
+host:port,...
+
+and paramspec is:
+
+name=value&...
 
    
 
@@ -978,7 +992,8 @@ postgresql://%2Fvar%2Flib%2Fpostgresql/dbname
     port component, in a single URI.  A URI of the form
     postgresql://host1:port1,host2:port2,host3:port3/
     is equivalent to a connection string of the form
-    host=host1,host2,host3 port=port1,port2,port3.  Each
+    host=host1,host2,host3 port=port1,port2,port3.
+    As further described below, each
     host will be tried in turn until a connection is successfully established.
    
    
@@ -989,8 +1004,8 @@ postgresql://%2Fvar%2Flib%2Fpostgresql/dbname
      
        It is possible to specify multiple hosts to connect to, so that they are
        tried in the given order. In the Keyword/Value format, the host,
-       hostaddr, and port options accept a comma-separated
-       list of values. The same number of elements must be given in each
+       hostaddr, and port options accept comma-separated
+       lists of values. The same number of elements must be given in each
        option that is specified, such
        that e.g., the first hostaddr corresponds to the first host name,
        the second hostaddr corresponds to the second host name, and so
@@ -1000,7 +1015,7 @@ postgresql://%2Fvar%2Flib%2Fpostgresql/dbname
 
      
        In the connection URI format, you can list multiple host:port pairs
-       separated by commas, in the host component of the URI.
+       separated by commas in the host component of the URI.