+ Note that the default callback will be called for any tag that isn't
+ specifically subscribed upon by the application, and can thus be called
+ in various contexts. For simplicity, the example above doesn't take
+ this into account (the <code>parent</code> could be of different
+ types, depending on the context).<br>
+ <br>
+ Note also that the default callback is not called when the parent context
+ is <code>NULL</code><code></code>. This is e.g. the case if none
+ of the "upper" tags has been subscribed upon.<br>
+
+
+<hr width="100%" size="2"><br>
+<h2><a name="Support_for_writing_GEDCOM_files"></a>Support for writing GEDCOM files</h2>
+The Gedcom parser library also contains functions to writing GEDCOM files.
+ Similar as for the parsing itself, there are two interfaces: an interface
+which is very basic, and requires you to call a function for each line in
+the GEDCOM file, and an interface which just dumps the Gedcom object model
+to a file in one shot (if you use the Gedcom object model).<br>
+<br>
+Again, this section focuses on the basic interface, the Gedcom object model interface is described <a href="gom.html#Writing_the_object_model_to_file">here</a>.<br>
+<br>
+<h3><a name="Opening_and_closing_files"></a>Opening and closing files</h3>
+The basic functions for opening and closing Gedcom files for writing are the following:<br>
+<code></code>
+<blockquote><code>Gedcom_write_hndl <b>gedcom_write_open</b> (const char* filename);<br>
+int <b>gedcom_write_close</b> (Gedcom_write_hndl hndl, int* total_conv_fails);<br></code></blockquote>
+The function <code>gedcom_write_open</code> takes a parameter the name of
+the file to write, and returns a write handle, which needs to be used in
+subsequent functions. It returns <code>NULL</code> in case of errors.<br>
+<br>
+The function <code>gedcom_write_close</code> takes, next to the write handle,
+an integer pointer as parameter. If you pass an actual pointer for
+this, the function will write in it the total number of conversion failures;
+you can pass <code>NULL</code> if you're not interested. The function returns 0 in case of success, non-zero in case of failure.<br>
+<br>
+<h3><a name="Controlling_some_settings"></a>Controlling some settings<br>
+</h3>
+Note that by default the file is written in the same encoding as the read file was in. You can change
+this by calling the following function <i>before</i> calling <code>gedcom_write_open</code>, i.e. it affects all files that are opened after it is being called:<code></code><code><br>
+</code>
+<blockquote><code>int <b>gedcom_write_set_encoding</b> (Enc_from from, const char* charset, Encoding width, Enc_bom bom);<br></code></blockquote>The <code>from</code> parameter indicates how you want the encoding to be set:<br>
+<ul>
+ <li><b><code>ENC_FROM_FILE</code></b>: The same as the read file was in (this is the default).</li>
+ <li><b><code>ENC_FROM_SYS</code></b>: Not a valid value here, see below for <code>gedcom_write_set_terminator</code><br>
+ </li>
+ <li><b><code>ENC_MANUAL</code></b>: From the values given in the following parameters.</li>
+</ul>
+When <code>ENC_FROM_FILE</code><b> </b>is selected, the other parameters in the function are ignored (they can be passed as 0). When <code>ENC_MANUAL</code> is chosen, the meaning of the other parameters is as follows:<br>
+<br>
+The valid <code>charset</code> values are given in the first column in the file <code>gedcom.enc</code> in the data directory of gedcom-parse (<code>$PREFIX/share/gedcom-parse</code>).
+ The character sets UNICODE, ASCII and ANSEL are always supported (these
+are standard for GEDCOM), as well as ANSI (not standard), but there may be
+others.<br>
+<br>
+The <code>width</code> parameter takes one of the following values:<br>
+<ul>
+</ul>
+<ul>
+ <li><code><b>ONE_BYTE</b></code>: This should be used for all character sets except UNICODE.</li>
+ <li><code><b>TWO_BYTE_HILO</b></code>: High-low encoding for UNICODE (i.e. big-endian)</li>
+ <li><code><b>TWO_BYTE_LOHI</b></code>: Low-high encoding for UNICODE (i.e. little-endian)</li>
+</ul>
+The <code>bom</code> parameter determines whether a byte-order-mark should
+be written in the file in case of UNICODE encoding (usually preferred because
+it then clearly indicates the byte ordering). It takes one of the following
+values:<br>
+<ul>
+ <li><code><b>WITHOUT_BOM</b></code></li>
+ <li><code><b>WITH_BOM</b></code></li>
+</ul> For both these parameters you can pass 0 for non-UNICODE encodings,
+since that corresponds to the correct values (and is ignored anyway). The
+function returns 0 in case of success, non-zero in case of error. Note
+that you still need to pass the correct charset value for the HEAD.CHAR tag,
+otherwise you will get a warning, and the value will be forced to the correct
+value.<br>
+<br>
+Further, it is possible to control the kind of line terminator that is used, via the following function (also to be used before <code>gedcom_write_open</code>):<br>
+<blockquote><code>int <b>gedcom_write_set_line_terminator</b> (Enc_from from, Enc_line_end end);<br></code></blockquote>The values for the <code>from</code> parameter are given above. The value <b><code>ENC_FROM_SYS</code></b>
+is valid here, and means that the normal terminator for the current system
+is used (the second parameter of the function is then ignored). This
+is the default for this setting.<br>
+<br>
+The <code>end</code> parameter takes one of the following values:<br>
+<ul>
+ <li><b><code>END_CR</code></b>: only carriage return ("/r") (system value for Macintosh)</li>
+ <li><b><code>END_LF</code></b>: only line feed ("/n") (system value for Unix, Mac OS X)</li>
+ <li><b><code>END_CR_LF</code></b>: first carriage return, then line feed ("/r/n") (system value for DOS, Windows)</li>
+ <li><b><code>END_LF_CR</code></b>: first line feed, then carriage return ("/n/r")</li>
+</ul>
+By default, this is set to the appropriate line terminator on the current
+platform, so it only needs to be changed if there is some special reason
+for it.<br>
+<h3><a name="Writing_data"></a>Writing data<br>
+</h3>
+For actually writing the data, the principle is that every line in the GEDCOM
+file to write corresponds to a call to one of the following functions, except
+that CONT/CONC lines can be automatically taken care of. Note that
+the resulting GEDCOM file should conform to the GEDCOM standard. Several
+checks are built in already, and more will follow, to force this. There
+is no compatibility mode for writing GEDCOM files (and probably never will be).<br>
+<br>
+In general, each of the following functions expect their input in UTF-8 encoding (see also <a href="#Converting_character_sets">here</a>). If this is not the case, errors will be returned.<br>
+<br>
+Note that for examples of using these functions you can look at the sources for the Gedcom object model (e.g. the function <code>write_header</code> in <code>gom/header.c</code>).<br>
+<h4>Records</h4>
+For writing lines corresponding to records (i.e. on level 0), the following function is available:
+<blockquote><code>int <b>gedcom_write_record_str</b> (Gedcom_write_hndl hndl, Gedcom_rec rec, const char* xrefstr, const char* value);<br></code></blockquote>
+The <code>hndl</code> parameter is the write handle that was returned by <code>gedcom_write_open</code>. The <code>rec</code> parameter is one of the identifiers given in the first column in <a href="interface.html#Record_identifiers">this table</a> (except <code>REC_USER</code>: see below). The <code>xrefstr</code> and <code>val</code> parameters are respectively the cross-reference key of the record (something like '<code>@FAM01@</code>'), and the value of the record line, which should be <code>NULL</code> for some record types, according to the same table.<br>
+<h4>Elements</h4>
+For writing lines corresponding to elements (inside records, i.e. on a level
+bigger than 0), the following functions are available, depending on the data
+type:
+<blockquote><code>int <b>gedcom_write_element_str</b> (Gedcom_write_hndl hndl, Gedcom_elt elt, int parsed_tag, <br>
+
+ int parent_rec_or_elt, const char* value);<br>
+i</code><code>nt <b>gedcom_write_element_xref</b> (Gedcom_write_hndl hndl, Gedcom_elt elt, int parsed_tag, <br>
+
+ int parent_rec_or_elt, const struct xref_value*
+value);</code><br>
+ <code>int <b>gedcom_write_element_date</b> (Gedcom_write_hndl hndl, Gedcom_elt elt, int parsed_tag, <br>
+
+ int parent_rec_or_elt, const struct date_value*
+value);</code><br>
+ <code>i</code><code>nt <b>gedcom_write_element_age </b> (Gedcom_write_hndl hndl, Gedcom_elt elt, int parsed_tag, <br>
+
+ int parent_rec_or_elt, const struct age_value*
+value);</code><br>
+</blockquote>
+<blockquote><code></code></blockquote>
+These functions only differ in the type of the last argument, which is the value of the element.<br>
+<br>
+The <code>hndl</code> parameter is again the write handle returned by <code>gedcom_write_open</code>. The <code>elt</code> parameter is one of the identifiers given in the first column in <a href="interface.html#Element_identifiers">this table</a> (except <code>ELT_USER</code>: see below). The <code>parent_rec_or_elt</code> is the corresponding <code>rec</code> or <code>elt</code>
+identifier of the logically enclosing statement: this will determine the
+level number written on the line, as the level number of the parent + 1.<br>
+<br>
+Some of the identifiers can actually stand for different tags. For this reason, the <code>parsed_tag</code> has to be passed for some of them. This parsed tag is the same as was returned by the callback functions defined <a href="#Start_and_end_callbacks">above</a>, and is an identifier of the form <code>TAG_<i>name</i></code>. This parameter is needed whenever the second column in <a href="interface.html#Element_identifiers">this table</a> shows several possible tags (this is e.g. the case for <code>ELT_SUB_FAM_EVT</code>).<br>
+<br>
+Note that for writing a date value, the given value should be valid, i.e.
+all its struct fields filled in properly and consistent. This can be
+done by calling <code>gedcom_normalize_date</code> (see <a href="interface.html#date">here</a>).<br>
+<h4>User-defined tags</h4>
+For user-defined tags (tags starting with an underscore), there are separate functions, again depending on the data type:<code></code>
+<blockquote><code>int <b>gedcom_write_user_str</b> (Gedcom_write_hndl hndl, int level, const char* tag, const char* xrefstr,<br>
+ const char* value);<br>
+i</code><code>nt <b>gedcom_write_user_xref</b> (Gedcom_write_hndl hndl, </code><code>int level, const char* tag, const char* xrefstr,</code><br>
+ <code>
+
+ const struct xref_value* value);</code><br>
+ <code></code></blockquote>
+In the case of user-defined tags, the level and tag string are passed verbatim
+(not controlled by the library). This allows to write any extra data
+that doesn't use a standard tag, but is only allowed for tags starting with
+an underscore.<br>
+<hr width="100%" size="2">
+
+<h2><a name="Other_API_functions"></a>Other API functions<br>
+ </h2>
+
+ Although the above describes the basic interface of the gedcom parser, there
+ are some other functions that allow to customize the behaviour of the library.
+ These will be explained in the current section.<br>
+
+
+<h3><a name="Debugging"></a>Debugging</h3>
+ The library can generate various debugging output, not only from itself,
+ but also the debugging output generated by the yacc parser. By default,
+ no debugging output is generated, but this can be customized using the
+following function:<br>
+
+
+<blockquote><code>void <b>gedcom_set_debug_level</b> (int level, FILE*
+trace_output)</code><br>
+ </blockquote>
+ The <code>level</code> can be one of the following values:<br>
+
+
+<ul>
+ <li>0: no debugging information (this is the
+ default)</li>
+ <li>1: only debugging information from libgedcom
+ itself</li>
+ <li>2: debugging information from libgedcom
+ and yacc</li>
+
+
+</ul>
+ If the <code>trace_output</code> is <code>NULL</code>, debugging information
+ will be written to <code>stderr</code>, otherwise the given file handle
+ is used (which must be open).<br>
+ <br>
+
+
+<h3><a name="Error_treatment"></a>Error treatment</h3>
+ One of the previous sections already described the callback to be
+registered to get error messages. The library also allows to customize
+what happens on an error, using the following function:<br>
+
+
+<blockquote><code>void <b>gedcom_set_error_handling</b> (Gedcom_err_mech
+ mechanism)</code><br>
+ </blockquote>
+ The <code>mechanism</code> can be one of:<br>
+
+
+<ul>
+ <li><code>IMMED_FAIL</code>: immediately fail
+the parsing on an error (this is the default)</li>
+ <li><code>DEFER_FAIL</code>: continue parsing
+after an error, but return a failure code eventually</li>
+ <li><code>IGNORE_ERRORS</code>: continue parsing
+ after an error, return success always</li>
+
+
+</ul>
+ This doesn't influence the generation of error or warning messages,
+ only the behaviour of the parser and its return code.<br>
+ <br>
+
+
+<h3><a name="Compatibility_mode"></a>Compatibility mode<br>
+ </h3>
+ Applications are not necessarily true to the GEDCOM spec (or use a
+different version than 5.5). The intention is that the library is
+resilient to this, and goes in compatibility mode for files written by specific
+programs (detected via the HEAD.SOUR tag). This compatibility mode
+can be enabled and disabled via the following function:<br>
+
+
+<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 (some) compatibility for:<br>
+<ul>
+ <li>ftree</li>
+ <li>Lifelines (3.0.2)</li>
+ <li>Personal Ancestral File (PAF), version 2, 4 and 5</li>
+ <li>Family Origins</li>
+ <li>EasyTree</li>
+</ul>
+The following function allows to set some options for the compatibility handling:<br>
+<blockquote><code>void <b>gedcom_set_compat_options</b> (Gedcom_compat options)</code><br>
+ </blockquote>
+The parameter can be an OR'ed combination of the following options:<br>
+<ul>
+ <li><code>COMPAT_ALLOW_OUT_OF_CONTEXT</code></li>
+</ul>
+<blockquote>
+ <blockquote>In some compatibility cases, tags are coming out-of-order,
+i.e. their start element callback would have to come after the end element
+callback of the parent tag. E.g. instead of the standard GEDCOM<br>
+ <blockquote><code>1 DATE ...<br>
+2 TIME ...</code><br>
+ </blockquote>
+the genealogy program has generated something like:<br>
+ <blockquote><code>1 DATE ...<br>
+1 TIME ...</code><br>
+ </blockquote>
+This can give a problem if your end element callbacks free some resources. <br>
+ <br>
+If your program can handle elements out of context, you can enable this option.
+ By default it is disabled, and so the values of these out-of-context
+tags are lost (the parser generates a warning if this is the case). Note:
+currently the Gedcom object model in C has this option disabled too, although
+this will change in the future.<br>
+ </blockquote>
+</blockquote>
+<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>With<code>
+gedcom-parse</code> comes a library implementing help functions for UTF-8 encoding (<code></code>see
+the <a href="utf8tools.html">documentation</a> for this library).<br>
+
+
+<hr width="100%" size="2">
+
+<h2><a name="Support_for_configure.in"></a>Development support</h2>
+<h3>Macro for configure.in<br>
+</h3>
+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_PATH_GEDCOM_PARSER([<i>min_version</i>,[<i>action_if_found</i>,[<i>action_if_not_found,</i>[<i>modules</i>]]]])</code><br>
+</blockquote>
+All the arguments are optional and default to 0. E.g. to check for
+version 1.34.2, you would put in configure.in the following statement:<br>
+<blockquote><code>AM_PATH_GEDCOM_PARSER(1.34.2)</code><br>
+</blockquote>Note that version numbers now contains three parts (since version
+0.20.0: this is also the first version in which this macro is available).<br>
+<br>
+The macro also sets the variables <code>GEDCOM_CFLAGS</code> and <code>GEDCOM_LIBS</code> for use in Makefiles. Typically, this would be done as follows in a Makefile.am:<br>
+<blockquote><code>bin_programs = myprg</code><br>
+ <code>myprg_SOURCES = myprg.c foo.c bar.c<br>
+INCLUDES = @GEDCOM_CFLAGS@<br>
+LDADD = @GEDCOM_LIBS@</code></blockquote>
+If your program uses some extra modules, they can be passed as fourth argument
+in the macro, so that the CFLAGS and LIBS are correctly filled in. Currently,
+the only available module is <code>gom</code> (the Gedcom object model). For example:<br>
+<blockquote><code>AM_PATH_GEDCOM_PARSER(0.21.2, , ,gom)</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> As you see, this only checked the major and minor version, not the patch number, so this is obsolete.<br>
+<br>
+<h3>Compilation and linking flags</h3>
+Similar to other libraries, the GEDCOM parse library installs a script <code>gedcom-config</code> to help with compilation and linking flags for programs that don't use autoconf/automake.<br>
+<br>
+To get compilation flags for your program, use (depending on whether you
+only use the callback parser, or also the GEDCOM object model):
+<blockquote><code>gedcom-config --cflags<br>
+gedcom-config --cflags gom</code><br>
+</blockquote>
+Similarly, to get linking flags, use one of the following:
+<blockquote><code>gedcom-config --libs<br>
+gedcom-config --libs gom</code><br>
+</blockquote>
+
+
+
+<hr width="100%" size="2">
+
+<pre><font size="-1">$Id$<br>$Name$</font><br></pre>
+
+
+<pre> </pre>
+
+
+<br>
+<br>
+<br>
+<br>
+<br>
+<br>
+<br>
+<br>
+<br>
+<br>
+<br>
+</body></html>
\ No newline at end of file