+<blockquote><code>void <b>gedcom_set_compat_handling</b> (int enable_compat)</code><br>
+ </blockquote>
+ The argument can be:<br>
+
+
+<ul>
+ <li>0: disable compatibility mode</li>
+ <li>1: allow compatibility mode (this is the
+default)<br>
+ </li>
+
+
+</ul>
+ Currently, there is a beginning for compatibility for ftree and Lifelines (3.0.2).<br>
+
+<hr width="100%" size="2">
+<h2><a name="Converting_character_sets"></a>Converting character sets</h2>
+ All strings passed by the GEDCOM parser to the application are in UTF-8
+ encoding. Typically, an application needs to convert this to something
+ else to be able to display it.<br>
+ <br>
+ The most common case is that the output character set is controlled by
+the <code>locale</code> mechanism (i.e. via the <code>LANG</code>, <code>
+ LC_ALL</code> or <code>LC_CTYPE</code> environment variables), which also
+controls the <code>gettext</code> mechanism in the application. <br>
+ <br>
+ <br>
+
+ The source distribution of <code>
+gedcom-parse</code> contains an a library implementing help functions for UTF-8 encoding (<code></code>see
+the "utf8" subdirectory of the top directory). Feel free to use
+ it in your source code. 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.
+ <br>
+ <br>
+ Its interface contains first of all the following two help functions:<br>
+
+<blockquote>
+ <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. 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. To function properly, the application must first set
+the locale using the <code>setlocale</code> function (the second step detailed
+ below). All other steps given below, including setting up and closing
+ down the conversion handles, are transparantly handled by the two functions.
+ <br>
+ <br>
+ If you pass a pointer to an integer to the first function, it will be
+set to the number of conversion failures, i.e. characters that couldn't
+be converted; you can also just pass <code>NULL</code> if you are not interested
+(note that usually, the interesting information is just whether there <i>
+were</i> conversion failures or not, which is then given by the integer
+being bigger than zero or not). The second function doesn't need this,
+because any locale can be converted to UTF-8.<br>
+ <br>
+ You can change the "?" that is output for characters that can't be converted
+ to any string you want, using the following function before the conversion
+ calls:<br>
+
+<blockquote>
+ <pre><code>void <b>convert_set_unknown</b> (const char *unknown);</code></pre>
+ </blockquote>
+ <br>
+ If you want to have your own functions for it instead of this example
+implementation, the following steps need to be taken by the application
+(more detailed info can be found in the info file of the GNU libc library
+in the "Generic Charset Conversion" section under "Character Set Handling"
+or online <a href="http://www.gnu.org/manual/glibc-2.2.3/html_chapter/libc_6.html#SEC99">
+ here</a>):<br>
+
+<ul>
+ <li>inclusion of some headers:</li>
+
+</ul>
+
+<blockquote>
+ <blockquote>
+ <pre><code>#include <locale.h> /* for setlocale */<br>#include <langinfo.h> /* for nl_langinfo */<br>#include <iconv.h> /* for iconv_* functions */<br></code></pre>
+ </blockquote>
+ </blockquote>
+
+<ul>
+ <li>set the program's current locale to what
+the user configured in the environment:</li>
+
+</ul>
+
+<blockquote>
+ <blockquote>
+ <pre><code>setlocale(LC_ALL, "");</code><br></pre>
+ </blockquote>
+ </blockquote>
+
+<ul>
+ <li>open a conversion handle for conversion
+ from UTF-8 to the character set of the current locale (once for the entire
+ program):</li>
+
+</ul>
+
+<blockquote>
+ <blockquote>
+ <pre><code>iconv_t iconv_handle;<br>...<br>iconv_handle = iconv_open(nl_langinfo(CODESET), "UTF-8");</code><br>if (iconv_handle == (iconv_t) -1)<br> /* signal an error */<br></pre>
+ </blockquote>
+ </blockquote>
+
+<ul>
+ <li>then, every string can be converted
+ using the following:</li>
+
+</ul>
+
+<blockquote>
+ <blockquote>
+ <pre><code>/* char* in_buf is the input buffer, size_t in_len is its length */<br>/* char* out_buf is the output buffer, size_t out_len is its length */<br><br>size_t nconv;<br>char *in_ptr = in_buf;<br>char *out_ptr = out_buf;<br>nconv = iconv(iconv_handle, &in_ptr, &in_len, &out_ptr, &out_len);</code></pre>
+ </blockquote>
+ </blockquote>
+
+<blockquote>If the output buffer is not big enough, <code>iconv</code> will
+ return -1 and set <code>errno</code> to <code>E2BIG</code>. Also,
+the <code>in_ptr</code> and <code>out_ptr</code> will point just after
+the last successfully converted character in the respective buffers, and
+the <code> in_len</code> and <code>out_len</code> will be updated to show
+the remaining lengths. There can be two strategies here:<br>
+
+ <ul>
+ <li>Make sure from the beginning
+ that the output buffer is big enough. However, it's difficult to find
+ an absolute maximum length in advance, even given the length of the input
+ string.<br>
+ <br>
+ </li>
+ <li>Do the conversion in several
+ steps, growing the output buffer each time to make more space, and calling
+ <code>iconv</code> consecutively until the conversion is complete.
+ This is the preferred way (a function could be written to encapsulate
+ all this).</li>
+
+ </ul>
+ Another error case is when the conversion was unsuccessful (if one of
+the characters can't be represented in the target character set). The
+ <code> iconv</code> function will then also return -1 and set <code>errno</code>
+ to <code>EILSEQ</code>; the <code>in_ptr</code> will point to the character
+ that couldn't be converted. In that case, again two strategies are
+possible:<br>
+
+ <ul>
+ <li>Just fail the conversion,
+and show an error. This is not very user friendly, of course.<br>
+ <br>
+ </li>
+ <li>Skip over the character that
+ can't be converted and append a "?" to the output buffer, then call <code>
+ iconv</code> again. Skipping over a UTF-8 character is fairly simple,
+ as follows from the <a href="http://www.cl.cam.ac.uk/%7Emgk25/unicode.html#utf-8">encoding rules</a>
+ :</li>
+
+ </ul>
+
+ <ol>
+
+ <ol>
+ <li>if the first byte is in
+binary 0xxxxxxx, then the character is only one byte long, just skip over
+that byte<br>
+ <br>
+ </li>
+ <li>if the first byte is in
+binary 11xxxxxx, then skip over that byte and all bytes 10xxxxxx that follow.<br>
+ </li>
+
+ </ol>
+
+ </ol>
+ </blockquote>
+
+<ul>
+ <li>eventually, the conversion
+handle needs to be closed (when the program exits):<br>
+ </li>
+
+</ul>
+
+<blockquote>
+ <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
+ that can't be converted.<br>
+
+
+<hr width="100%" size="2">
+
+<h2><a name="Support_for_configure.in"></a>Support for configure.in</h2>There
+is a macro available for use in configure.in for applications that are using
+autoconf to configure their sources. The following macro checks whether
+the Gedcom parser library is available and whether its version is high enough:<br>
+<blockquote><code>AM_LIB_GEDCOM_PARSER([<i>major</i>,[<i>minor</i>,[<i>patch</i>]]])</code><br>
+</blockquote>
+All the arguments are optional and default to 0. E.g. to check for
+version 1.34, you would put in configure.in the following statement:<br>
+<blockquote><code>AM_LIB_GEDCOM_PARSER(1,34)</code><br>
+</blockquote>
+To be able to use this macro in the sources of your application, you have three options:<br>
+<ul>
+ <li>Put the file <code>m4/gedcom.m4</code> in your autoconf data directory (i.e. the path given by '<code>aclocal --print-ac-dir</code>', usually <code>/usr/share/aclocal</code>). You can do this automatically by going into the m4 subdirectory and typing '<code>make install-m4</code>'.<br>
+ <br>
+ </li>
+ <li>If you're using autoconf, but not automake, copy the contents of <code>m4/gedcom.m4</code> in the <code>aclocal.m4</code> file in your sources.<br>
+ <br>
+ </li>
+ <li>If you're using automake, copy the contents of <code>m4/gedcom.m4</code> in the <code>acinclude.m4</code> file in your sources.<br>
+ </li>
+</ul>
+<br>
+There are three preprocessor symbols defined for version checks in the
+ header (but their direct use is deprecated: please use the macro above):<br>
+
+<ul>
+ <li><code>GEDCOM_PARSE_VERSION_MAJOR</code></li>
+ <li><code>GEDCOM_PARSE_VERSION_MINOR</code></li>
+ <li><code>GEDCOM_PARSE_VERSION</code><br>
+ </li>
+
+</ul>
+ The last one is equal to <code>(GEDCOM_PARSE_VERSION_MAJOR * 1000) + GEDCOM_PARSE_VERSION_MINOR.</code><br>
+
+
+<hr width="100%" size="2">
+
+<pre><font size="-1">$Id$<br>$Name$</font><br></pre>
+
+
+<pre> </pre>
+
+
+<br>
+<br>
+<br>
+<br>
+<br>
+<br>
+</body></html>
\ No newline at end of file