Improve formatting of PQexecParams argument descriptions, per

Theo Kramer.

diff --git a/doc/src/sgml/libpq.sgml b/doc/src/sgml/libpq.sgml
index f648843689f4e80c38ab51584e032fe2883f4dbd..40d0bcb1fbdcd67a36ef3397bf0fbc1fcf213d5a 100644 (file)
--- a/doc/src/sgml/libpq.sgml
+++ b/doc/src/sgml/libpq.sgml
@@ -1,4 +1,4 @@
-
+
 
  
   <application>libpq</application> - C Library
@@ -956,7 +956,7 @@ Applications may use this to determine the version of the database server they
 are connected to. The number is formed by converting the major, minor, and
 revision numbers into two-decimal-digit numbers and appending them
 together. For example, version 8.1.5 will be returned as 80105, and version
-8.1 will be returned as 80100 (leading zeroes are not shown).  Zero is
+8.2 will be returned as 80200 (leading zeroes are not shown).  Zero is
 returned if the connection is bad.
 
 
@@ -1138,41 +1138,116 @@ connections; it will fail when using protocol 2.0.
 
 
 
-If parameters are used, they are referred to in the command string
-as $1, $2, etc.
-nParams is the number of parameters supplied; it is the length
-of the arrays paramTypes[], paramValues[],
-paramLengths[], and paramFormats[].  (The
-array pointers may be NULL when nParams is zero.)
-paramTypes[] specifies, by OID, the data types to be assigned to
-the parameter symbols.  If paramTypes is NULL, or any particular
-element in the array is zero, the server assigns a data type to the parameter
-symbol in the same way it would do for an untyped literal string.
-paramValues[] specifies the actual values of the parameters.
-A null pointer in this array means the corresponding parameter is null;
-otherwise the pointer points to a zero-terminated text string (for text
-format) or binary data in the format expected by the server (for binary
-format).
-paramLengths[] specifies the actual data lengths of
-binary-format parameters.  It is ignored for null parameters and text-format
-parameters.  The array pointer may be null when there are no binary
-parameters.
-paramFormats[] specifies whether parameters are text (put a zero
-in the array) or binary (put a one in the array).  If the array pointer is
-null then all parameters are presumed to be text.
-resultFormat is zero to obtain results in text format, or one to
-obtain results in binary format.  (There is not currently a provision to
-obtain different result columns in different formats, although that is
-possible in the underlying protocol.)
+The function arguments are:
+
+
+  
+    conn
+    
+      
+       The connection object to send the command through.
+      
+    
+  
+
+  
+    command
+    
+      
+       The SQL command string to be executed. If parameters are used, they are
+       referred to in the command string as $1, $2,
+       etc.
+      
+    
+  
+
+  
+    nParams
+    
+      
+       The number of parameters supplied; it is the length of the arrays
+       paramTypes[], paramValues[],
+       paramLengths[], and paramFormats[]. (The
+       array pointers may be NULL when nParams
+       is zero.)
+      
+    
+  
+
+  
+    paramTypes[]
+    
+      
+       Specifies, by OID, the data types to be assigned to the parameter
+       symbols.  If paramTypes is NULL, or any
+       particular element in the array is zero, the server infers a data type
+       for the parameter symbol in the same way it would do for an untyped
+       literal string.
+      
+    
+  
+
+  
+    paramValues[]
+    
+      
+       Specifies the actual values of the parameters.
+       A null pointer in this array means the corresponding parameter is null;
+       otherwise the pointer points to a zero-terminated text string (for text
+       format) or binary data in the format expected by the server (for binary
+       format).
+      
+    
+  
+
+  
+    paramLengths[]
+    
+      
+       Specifies the actual data lengths of binary-format parameters.
+       It is ignored for null parameters and text-format parameters.
+       The array pointer may be null when there are no binary parameters.
+      
+    
+  
+
+  
+    paramFormats[]
+    
+      
+       Specifies whether parameters are text (put a zero in the array entry for
+       the corresponding parameter) or binary (put a one in the array entry for
+       the corresponding parameter). If the array pointer is null then all
+       parameters are presumed to be text strings.
+      
+    
+  
+
+  
+    resultFormat
+    
+      
+       Specify zero to obtain results in text format, or one to obtain results
+       in binary format.  (There is not currently a provision to obtain
+       different result columns in different formats, although that is
+       possible in the underlying protocol.)
+      
+    
+  
+
 
 
 
 
+
 
+
 The primary advantage of PQexecParams over PQexec
 is that parameter values may be separated from the command string, thus
 avoiding the need for tedious and error-prone quoting and escaping.
+
 
+
 Unlike PQexec, PQexecParams allows at most one SQL
 command in the given string.  (There can be semicolons in it, but not more
 than one nonempty command.)  This is a limitation of the underlying protocol,