Re: Lack of docs for libpq C Library

Tom Lane wrote:
> Alvaro Herrera <alvherre@commandprompt.com> writes:
> > I disagree.  I think PQinitSSL is meant to be called from the
> > application, for example.  Same with PQsetClientEncoding.  And the
> > PQExpBuffer stuff is all very useful, and years ago when I wrote an app
> > to use it it annoyed me that there were no docs on it.  (Back then, I
> > didn't realize I could have complained about it or written the docs
> > myself).
>
> PQsetClientEncoding seems to be documented in the wrong place.

I have moved the libpq client encoding documentation into the libpq doc
section, and just referenced it from the localization docs.  Backpatched
to 8.3.X.

--
  Bruce Momjian  <bruce@momjian.us>        http://momjian.us
  EnterpriseDB                             http://postgres.enterprisedb.com

  + If your life is a hard drive, Christ can be your backup. +
Index: doc/src/sgml/charset.sgml
===================================================================
RCS file: /cvsroot/pgsql/doc/src/sgml/charset.sgml,v
retrieving revision 2.84
diff -c -c -r2.84 charset.sgml
*** doc/src/sgml/charset.sgml    28 Sep 2007 22:25:49 -0000    2.84
--- doc/src/sgml/charset.sgml    6 Mar 2008 15:32:28 -0000
***************
*** 1110,1140 ****

        <listitem>
         <para>
!         Using <application>libpq</> functions.
!         <command>\encoding</command> actually calls
!         <function>PQsetClientEncoding()</function> for its purpose.
!
! <synopsis>
! int PQsetClientEncoding(PGconn *<replaceable>conn</replaceable>, const char *<replaceable>encoding</replaceable>);
! </synopsis>
!
!         where <replaceable>conn</replaceable> is a connection to the server,
!         and <replaceable>encoding</replaceable> is the encoding you
!         want to use. If the function successfully sets the encoding, it returns 0,
!         otherwise -1. The current encoding for this connection can be determined by
!         using:
!
! <synopsis>
! int PQclientEncoding(const PGconn *<replaceable>conn</replaceable>);
! </synopsis>
!
!         Note that it returns the encoding ID, not a symbolic string
!         such as <literal>EUC_JP</literal>. To convert an encoding ID to an encoding name, you
!         can use:
!
! <synopsis>
! char *pg_encoding_to_char(int <replaceable>encoding_id</replaceable>);
! </synopsis>
         </para>
        </listitem>

--- 1110,1116 ----

        <listitem>
         <para>
!         <application>libpq</> (<xref linkend="libpq-control">) has functions to control the client encoding.
         </para>
        </listitem>

Index: doc/src/sgml/libpq.sgml
===================================================================
RCS file: /cvsroot/pgsql/doc/src/sgml/libpq.sgml,v
retrieving revision 1.255
diff -c -c -r1.255 libpq.sgml
*** doc/src/sgml/libpq.sgml    31 Jan 2008 23:31:33 -0000    1.255
--- doc/src/sgml/libpq.sgml    6 Mar 2008 15:32:32 -0000
***************
*** 4417,4422 ****
--- 4417,4472 ----
    <variablelist>
     <varlistentry>
      <term>
+      <function>PQclientEncoding</function>
+      <indexterm>
+       <primary>PQclientEncoding</primary>
+      </indexterm>
+     </term>
+
+     <listitem>
+      <para>
+       Returns the client encoding.
+       <synopsis>
+       int PQclientEncoding(const PGconn *<replaceable>conn</replaceable>);
+       </synopsis>
+
+       Note that it returns the encoding ID, not a symbolic string
+       such as <literal>EUC_JP</literal>. To convert an encoding ID to an encoding name, you
+       can use:
+
+ <synopsis>
+ char *pg_encoding_to_char(int <replaceable>encoding_id</replaceable>);
+ </synopsis>
+      </para>
+     </listitem>
+    </varlistentry>
+
+    <varlistentry>
+     <term>
+      <function>PQsetClientEncoding</function>
+      <indexterm>
+       <primary>PQsetClientEncoding</primary>
+      </indexterm>
+     </term>
+
+     <listitem>
+      <para>
+       Sets the client encoding.
+       <synopsis>
+       int PQsetClientEncoding(PGconn *<replaceable>conn</replaceable>, const char
*<replaceable>encoding</replaceable>);
+       </synopsis>
+
+       <replaceable>conn</replaceable> is a connection to the server,
+       and <replaceable>encoding</replaceable> is the encoding you want to
+       use. If the function successfully sets the encoding, it returns 0,
+       otherwise -1. The current encoding for this connection can be
+       determined by using <function>PQclientEncoding</>.
+      </para>
+     </listitem>
+    </varlistentry>
+
+    <varlistentry>
+     <term>
       <function>PQsetErrorVerbosity</function>
       <indexterm>
        <primary>PQsetErrorVerbosity</primary>