X-Git-Url: https://git.dlugolecki.net.pl/?a=blobdiff_plain;f=doc%2Fusage.html;h=0a8c7e85c5ece5d1352d099348de28d8366d81f0;hb=3cea0be54e7466a949a91904e5e8e8858fc1ee50;hp=dc2e70ad7d9f03ebde68f0f2b722ca9caf204076;hpb=cf04c144fa910f52d44ef33d2fa9a03f912efa2e;p=gedcom-parse.git

diff --git a/doc/usage.html b/doc/usage.html
index dc2e70a..0a8c7e8 100644
--- a/doc/usage.html
+++ b/doc/usage.html
@@ -102,8 +102,9 @@ the <code>-lgedcom</code> option
 on the linking of the program as the last option, so that its initialization
 code is run first. &nbsp;In the case of using the C object model, the linking
 options should be: <code>-lgedcom_gom -lgedcom</code><br>
-          <br>
-        The next sections will refine this piece of code to be able to have
+          <br>The function <code>gedcom_init()</code> also initializes locale handling by calling <code>setlocale(LC_ALL, "")</code>, in case the application would not do this (it doesn't hurt for the application to do the same).<br>
+&nbsp;<br>
+The next sections will refine this piece of code to be able to have
  meaningful errors   and the actual data that is in the file.<br>
                            
 <hr width="100%" size="2">                       
@@ -515,17 +516,29 @@ controls the <code>gettext</code>  mechanism in the application. &nbsp;<br>
                        <br>
                                                                         
                                         The source distribution of <code>
-gedcom-parse</code>   contains an example implementation (<code>utf8-locale.c</code>
- and <code>  utf8-locale.h</code>  in the "t" subdirectory of the top directory).&nbsp;
-&nbsp;Feel free to use  it in your source code (it is not part of the library,
-and it isn't installed  anywhere, so you need to take over the source and
-header file in your application).  &nbsp;<br>
+gedcom-parse</code>   contains an a library implementing help functions for UTF-8 encoding (<code></code>see
+the "utf8" subdirectory of the top directory).&nbsp; &nbsp;Feel free to use
+ it in your source code. &nbsp;It isn't installed  anywhere, so you need
+to take over the source and header files in your application. Note that on
+some systems it uses libcharset, which is also included in this subdirectory.
+ &nbsp;<br>
                        <br>
-    Its interface is:<br>
+    Its interface contains first of all the following two help functions:<br>
                          
 <blockquote>      
-  <pre><code>char *<b>convert_utf8_to_locale</b> (char *input, int *conv_failures);<br>char *<b>convert_locale_to_utf8</b> (char *input);<br></code></pre>
+  <pre><code>int   <b>is_utf8_string</b> (char *input);<br>int   <b>utf8_strlen</b> (char *input);<br></code></pre></blockquote>The
+first one returns 1 if the given input is a valid UTF-8 string, it returns
+0 otherwise, the second gives the number of UTF-8 characters in the given
+input. &nbsp;Note that the second function assumes that the input is valid
+UTF-8, and gives unpredictable results if it isn't.<br>
+<br>
+For conversion, the following functions are available:<br>
+<blockquote>
+  <pre><code></code><code>char *<b>convert_utf8_to_locale</b> (char *input, int *conv_failures);<br>char *<b>convert_locale_to_utf8</b> (char *input);<br></code></pre>
+</blockquote>
+<blockquote>
   </blockquote>
+
     Both functions return a pointer to a static buffer that is overwritten
  on each call. &nbsp;To function properly, the application must first set
 the locale using the <code>setlocale</code> function (the second step detailed
@@ -673,9 +686,9 @@ handle needs to be closed (when the program exits):<br>
   <blockquote>                                                     
     <pre><code>iconv_close(iconv_handle);<br></code></pre>
                                              </blockquote>
-                                             </blockquote>
-                                                  The example implementation 
- mentioned above grows the output buffer dynamically and outputs "?" for characters
+                                             </blockquote> 
+                                                  The example implementation
+mentioned above grows the output buffer dynamically and outputs "?" for characters 
  that can't be converted.<br>
                                                                         
                          
@@ -728,4 +741,6 @@ There are three preprocessor symbols defined for version checks in the
 <br>
 <br>
 <br>
+<br>
+<br>
 </body></html>
\ No newline at end of file