* doc/ref/i18n.xml: New file.

* doc/ref/init.xml, doc/ref/neon.xml: More process-global 
initialization stuff.


git-svn-id: http://svn.webdav.org/repos/projects/neon/trunk@964 61a7d7f5-40b7-0310-9c16-bb0ea8cb1845

3 files changed, 93 insertions, 3 deletions

diff --git a/doc/ref/i18n.xml b/doc/ref/i18n.xml
new file mode 100644
index 0000000..9f1f2e4
--- /dev/null
+++ b/doc/ref/i18n.xml
@@ -0,0 +1,71 @@
+<refentry id="refi18n">
+
+  <refmeta>
+    <refentrytitle>ne_i18n_init</refentrytitle>
+    <manvolnum>3</manvolnum>
+  </refmeta>
+
+  <refnamediv>
+    <refname id="ne_i18n_init">ne_i18n_init</refname>
+    <refpurpose>functions to initialize internationalization support</refpurpose>
+  </refnamediv>
+  
+  <refsynopsisdiv>
+
+    <funcsynopsis>
+
+      <funcsynopsisinfo>#include &lt;ne_i18n.h&gt;</funcsynopsisinfo>
+
+      <funcprototype>
+        <funcdef>void <function>ne_i18n_init</function></funcdef>
+        <paramdef>const char *<parameter>encoding</parameter></paramdef>
+      </funcprototype>
+
+    </funcsynopsis>
+
+  </refsynopsisdiv>
+
+  <refsect1>
+    <title>Description</title>
+
+    <para>The <function>ne_i18n_init</function> function can be used
+    to enable support for translated messages in the &neon; library.
+    The <parameter>encoding</parameter> parameter, if non-&null;,
+    specifies the character encoding required for generated translated
+    string.  If it is &null;, the appropriate character encoding for
+    the process locale will be used.</para>
+
+    <para>This call is only strictly necessary if either:
+
+    <orderedlist numeration="loweralpha">
+        
+      <listitem><simpara>&neon; has been installed into a different
+      prefix than the <literal>gettext</literal> implementation on
+      which it depends for i18n purposes, or</simpara></listitem>
+
+      <listitem><simpara>the caller requires that translated messages
+      are in a particular character encoding.</simpara></listitem>
+
+    </orderedlist></para>
+
+    <para>If <function>ne_i18n_init</function> is never called, the
+    message catalogs will not be found if case (a) applies (and so
+    English error messages will be used), and will use the default
+    character encoding specified by the process locale.  The library
+    will otherwise operate correctly.</para>
+
+    <para>Note that the encoding used is a process-global setting and
+    so results may be unexpected if other users of &neon; within the
+    process call <function>ne_i18n_init</function> with a different
+    encoding parameter.</para>
+
+  </refsect1>
+
+  <refsect1>
+    <title>See also</title>
+
+    <para><xref linkend="ne_sock_init"/></para>
+  </refsect1>
+
+</refentry>
+
diff --git a/doc/ref/init.xml b/doc/ref/init.xml
index 234b48a..3a70fc2 100644
--- a/doc/ref/init.xml
+++ b/doc/ref/init.xml
@@ -48,6 +48,12 @@
     calls to <function>ne_sock_init</function> are made, only the Nth
     call to <function>ne_sock_exit</function> will have effect.</para>
 
+    <para><function>ne_sock_init</function> will set the disposition
+    of the <literal>SIGPIPE</literal> signal to
+    <emphasis>ignored</emphasis>.  No change is made to the
+    <literal>SIGPIPE</literal> disposition by
+    <function>ne_sock_exit</function>.</para>
+
     <para>Both the SSL libraries supported by &neon; &mdash; OpenSSL
     and GnuTLS &mdash; require callbacks to be registered to allow
     thread-safe use of SSL.  These callbacks are stored as global
@@ -55,10 +61,15 @@
     in question is loaded into the process.  If multiple users of the
     SSL library exist within the process, this can be problematic,
     particularly if one is dynamically loaded (and may subsequently be
-    unloaded).  If &neon; is configured using the
+    unloaded).</para>
+
+    <para>If &neon; is configured using the
     <literal>--enable-threadsafe-ssl</literal> flag, thread-safe SSL
     support will be enabled automatically, as covered in the following
-    section.</para>
+    section.  Otherwise, it is not safe to use &neon; with SSL in a
+    multi-threaded process.  The <xref linkend="ne_has_support"/>
+    function can be used to determine whether &neon; is built to
+    enable thread-safety support in the SSL library.</para>
     
     <refsect2>
       <title>Thread-safe SSL with OpenSSL</title>
@@ -115,7 +126,7 @@
   <refsect1>
     <title>See also</title>
 
-    <para><xref linkend="refneon"/></para>
+    <para><xref linkend="refneon"/>, <xref linkend="reffeat"/></para>
   </refsect1>
 
 </refentry>
diff --git a/doc/ref/neon.xml b/doc/ref/neon.xml
index deef4af..fee7375 100644
--- a/doc/ref/neon.xml
+++ b/doc/ref/neon.xml
@@ -54,6 +54,10 @@
     initialization before use; notably:
 
     <itemizedlist>
+      <listitem><simpara>The <literal>SIGPIPE</literal> signal
+      disposition must be set to
+      <emphasis>ignored</emphasis>.</simpara></listitem>
+
       <listitem><simpara>OpenSSL requires global initialization to
       load shared lookup tables.</simpara></listitem>
 
@@ -68,6 +72,10 @@
     before any other use of &neon; to perform any necessary
     initialization needed for the particular platform.</para>
 
+    <para>For some applications it may be necessary to call <xref
+    linkend="ne_i18n_init"/> to initialize the internationalization
+    support &neon;.</para>
+
   </refsect2>
 
   <refsect2>