Reformat documentation of libpq escaping functions.

Modify the "Escaping Strings for Inclusion in SQL Commands" section
to use a  as the preceding and following sections do,
and merge the "Escaping Binary Strings for Inclusion in SQL Commands"
section into it.

This changes only the formatting of these sections, not the content.
It is intended to lay the groundwork for a follow-on patch to add
some new escaping functions, but it makes sense to commit this first,
for clarity.

diff --git a/doc/src/sgml/libpq.sgml b/doc/src/sgml/libpq.sgml
index 5dce33fbd248471da83ec7da0be2ac48deeea34f..cfa87d0adaec3f77c13e2fbd1085ff75cf9d5540 100644 (file)
--- a/doc/src/sgml/libpq.sgml
+++ b/doc/src/sgml/libpq.sgml
@@ -1,4 +1,4 @@
-
+
 
 
  <application>libpq</application> - C Library
@@ -2925,118 +2925,126 @@ typedef struct {
   
    Escaping Strings for Inclusion in SQL Commands
 
-   
-    PQescapeStringConn
-   
-   
-    PQescapeString
-   
    
     escaping strings
     in libpq
    
 
-   
-    PQescapeStringConn escapes a string for use within an SQL
-    command.  This is useful when inserting data values as literal constants
-    in SQL commands.  Certain characters (such as quotes and backslashes) must
-    be escaped to prevent them from being interpreted specially by the SQL parser.
-    PQescapeStringConn performs this operation.
-   
+   
+    
+     
+      PQescapeStringConn
+      
+       PQescapeStringConn
+      
+     
 
-   
-    
-     It is especially important to do proper escaping when handling strings that
-     were received from an untrustworthy source.  Otherwise there is a security
-     risk: you are vulnerable to SQL injection attacks wherein unwanted
-     SQL commands are fed to your database.
-    
-   
+     
+     
+      PQescapeStringConn escapes a string for
+      use within an SQL command.  This is useful when inserting data
+      values as literal constants in SQL commands.  Certain characters
+      (such as quotes and backslashes) must be escaped to prevent them
+      from being interpreted specially by the SQL parser.
+      PQescapeStringConn performs this operation.
+     
 
-   
-    Note that it is not necessary nor correct to do escaping when a data
-    value is passed as a separate parameter in PQexecParams or
-    its sibling routines.
-
-    
-     size_t PQescapeStringConn (PGconn *conn,
-                                char *to, const char *from, size_t length,
-                                int *error);
-    
-   
+     
+      
+       It is especially important to do proper escaping when handling
+       strings that were received from an untrustworthy source.
+       Otherwise there is a security risk: you are vulnerable to
+       SQL injection attacks wherein unwanted SQL commands are
+       fed to your database.
+      
+     
 
-   
-    PQescapeStringConn writes an escaped version of the
-    from string to the to buffer, escaping
-    special characters so that they cannot cause any harm, and adding a
-    terminating zero byte.  The single quotes that must surround
-    PostgreSQL string literals are not included in the
-    result string; they should be provided in the SQL command that the
-    result is inserted into.  The parameter from points to
-    the first character of the string that is to be escaped, and the
-    length parameter gives the number of bytes in this
-    string.  A terminating zero byte is not required, and should not be
-    counted in length.  (If a terminating zero byte is found
-    before length bytes are processed,
-    PQescapeStringConn stops at the zero; the behavior is
-    thus rather like strncpy.) to shall point
-    to a buffer that is able to hold at least one more byte than twice
-    the value of length, otherwise the behavior is undefined.
-    Behavior is likewise undefined if the to and
-    from strings overlap.
-   
+     
+      Note that it is not necessary nor correct to do escaping when a data
+      value is passed as a separate parameter in PQexecParams or
+      its sibling routines.
 
-   
-    If the error parameter is not NULL, then
-    *error is set to zero on success, nonzero on error.
-    Presently the only possible error conditions involve invalid multibyte
-    encoding in the source string.  The output string is still generated
-    on error, but it can be expected that the server will reject it as
-    malformed.  On error, a suitable message is stored in the
-    conn object, whether or not error is NULL.
-   
+      
+       size_t PQescapeStringConn (PGconn *conn,
+                                  char *to, const char *from, size_t length,
+                                  int *error);
+      
+     
 
-   
-    PQescapeStringConn returns the number of bytes written
-    to to, not including the terminating zero byte.
-   
+     
+      PQescapeStringConn writes an escaped version of the
+      from string to the to buffer, escaping
+      special characters so that they cannot cause any harm, and adding a
+      terminating zero byte.  The single quotes that must surround
+      PostgreSQL string literals are not included in the
+      result string; they should be provided in the SQL command that the
+      result is inserted into.  The parameter from points to
+      the first character of the string that is to be escaped, and the
+      length parameter gives the number of bytes in this
+      string.  A terminating zero byte is not required, and should not be
+      counted in length.  (If a terminating zero byte is found
+      before length bytes are processed,
+      PQescapeStringConn stops at the zero; the behavior is
+      thus rather like strncpy.) to shall point
+      to a buffer that is able to hold at least one more byte than twice
+      the value of length, otherwise the behavior is undefined.
+      Behavior is likewise undefined if the to and
+      from strings overlap.
+     
 
-   
-    
-     size_t PQescapeString (char *to, const char *from, size_t length);
-    
-   
+     
+      If the error parameter is not NULL, then
+      *error is set to zero on success, nonzero on error.
+      Presently the only possible error conditions involve invalid multibyte
+      encoding in the source string.  The output string is still generated
+      on error, but it can be expected that the server will reject it as
+      malformed.  On error, a suitable message is stored in the
+      conn object, whether or not error is NULL.
+     
 
-   
-    PQescapeString is an older, deprecated version of
-    PQescapeStringConn; the difference is that it does
-    not take conn or error parameters.
-    Because of this, it cannot adjust its behavior depending on the
-    connection properties (such as character encoding) and therefore
-    it might give the wrong results.  Also, it has no way
-    to report error conditions.
-   
+     
+      PQescapeStringConn returns the number of bytes written
+      to to, not including the terminating zero byte.
+     
+     
+    
 
-   
-    PQescapeString can be used safely in single-threaded
-    client programs that work with only one PostgreSQL
-    connection at a time (in this case it can find out what it needs to
-    know behind the scenes).  In other contexts it is a security
-    hazard and should be avoided in favor of
-    PQescapeStringConn.
-   
-  
+    
+     
+      PQescapeString
+      
+       PQescapeString
+      
+     
 
+     
+     
+      
+       size_t PQescapeString (char *to, const char *from, size_t length);
+      
+     
 
-  
-   Escaping Binary Strings for Inclusion in SQL Commands
+     
+      PQescapeString is an older, deprecated version of
+      PQescapeStringConn; the difference is that it does
+      not take conn or error parameters.
+      Because of this, it cannot adjust its behavior depending on the
+      connection properties (such as character encoding) and therefore
+      it might give the wrong results.  Also, it has no way
+      to report error conditions.
+     
 
-   
-    bytea
-    in libpq
-   
+     
+      PQescapeString can be used safely in single-threaded
+      client programs that work with only one PostgreSQL
+      connection at a time (in this case it can find out what it needs to
+      know behind the scenes).  In other contexts it is a security
+      hazard and should be avoided in favor of
+      PQescapeStringConn.
+     
+     
+    
 
-   
     
      
       PQescapeByteaConn