+ If we look at the other arguments of the start callback, we see the
+ level number (the initial number of the line in the GEDCOM file), the tag
+ (e.g. "SOUR"), and then a raw value, a parsed tag and a parsed value. The
+ raw value is just the raw string that occurs as value on the line next
+to the tag (in UTF-8 encoding). The parsed value is the meaningful
+value that is parsed from that raw string. The parsed tag is described
+in the section for record callbacks above.<br>
+ <br>
+ The <code>Gedcom_val</code> type is meant to be an opaque type. The
+ only thing that needs to be known about it is that it can contain specific
+ data types, which have to be retrieved from it using pre-defined macros.
+ These data types are described in the <a href="interface.html#Gedcom_val_types"> interface details</a>.
+ <br>
+ <br>
+ Some extra notes:<br>
+
+
+<ul>
+ <li>The <code>Gedcom_val</code> argument of the end callback
+ is currently not used. It is there for future enhancements.</li>
+ <li>There are also two <code>Gedcom_val</code> arguments
+ in the start callback for records. The first one (<code>xref</code>
+ ) contains the <code>xref_value</code> corresponding to the cross-reference
+ (or <code>NULL</code> if there isn't one), the second one (<code>parsed_value</code>
+ ) contains the value that is parsed from the <code>raw_value</code>. See
+ the <a href="interface.html#Record_identifiers">interface details</a>
+ .</li>
+
+
+</ul>
+
+
+<h3><a name="Default_callbacks"></a>Default callbacks<br>
+ </h3>
+ As described above, an application doesn't always implement the entire
+ GEDCOM spec, and application-specific tags may have been added by other
+ applications. To preserve this extra data anyway, a default callback
+ can be registered by the application, as in the following example:<br>
+
+<blockquote><code>void <b>my_default_cb</b> (Gedcom_elt elt, Gedcom_ctxt parent, int level,
+ char* tag, char* raw_value, int parsed_tag)<br>
+ {<br>
+ ...<br>
+ }<br>
+ <br>
+ ...<br>
+ <b>gedcom_set_default_callback</b>(my_default_cb);<br>
+ ...<br>
+ result = <b>gedcom_parse_file</b>("myfamily.ged");</code><br>
+ </blockquote>
+ This callback has a similar signature as the previous ones,
+ but it doesn't contain a parsed value. However, it does contain the
+ parent context, that was returned by the application for the most specific
+ containing tag that the application supported.<br>
+ <br>
+ Suppose e.g. that this callback is called for some tags in the header
+ that are specific to some other application, then our application could
+ make sure that the parent context contains the struct or object that represents
+ the header, and use the default callback here to add the level, tag and
+ raw_value as plain text in a member of that struct or object, thus preserving
+ the information. The application can then write this out when the
+data is saved again in a GEDCOM file. To make it more specific, consider
+ the following example:<br>
+
+<blockquote><code>struct header {<br>
+ char* source;<br>
+ ...<br>
+ char* extra_text;<br>
+ };<br>
+ <br>
+ Gedcom_ctxt my_header_start_cb(Gedcom_rec rec, int level, Gedcom_val xref, char* tag,
+ char *raw_value,<br>
+
+ int parsed_tag, Gedcom_val parsed_value)<br>
+ {<br>
+ struct header head = my_make_header_struct();<br>
+ return (Gedcom_ctxt)head;<br>
+ }<br>
+ <br>
+ void my_default_cb(Gedcom_elt elt, Gedcom_ctxt parent, int level, char* tag, char*
+raw_value, int parsed_tag)<br>
+ {<br>
+ struct header head = (struct header)parent;<br>
+ my_header_add_to_extra_text(head, level, tag, raw_value);<br>
+ }<br>
+ <br>
+ gedcom_set_default_callback(my_default_cb);<br>
+ gedcom_subscribe_to_record(REC_HEAD, my_header_start, NULL);<br>
+ ...<br>
+ result = gedcom_parse_file(filename);</code><br>
+ </blockquote>
+ 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="C_object_model"></a>C object model</h2>
+In the GEDCOM object model, all the data is immediately available after calling <code>gom_parse_file()</code>. For this, an entire model based on C structs is used. These structs are documented <a href="gomxref.html">here</a>,
+and follow the GEDCOM syntax quite closely. Each of the records in
+a GEDCOM file are modelled by a separate struct, and some common sub-structures
+have their own struct definition.<br>
+<br>
+<h3><a name="Main_functions"></a>Main functions<br>
+</h3>
+The following functions are available to get at these structs:<br>
+<ul>
+ <li>First, there are two functions to get the header record and the submission
+record (there can be only one of them in a GEDCOM file):<br>
+ <blockquote><code>struct header* gom_get_header();<br>
+struct submission* gom_get_submission();<br>
+ </code></blockquote>
+ </li>
+ <li>Further, for each of the other records, there are two functions, one
+to get the first of such records, and one to get a record via its cross-reference
+tag in the GEDCOM file:<br>
+ <blockquote><code>struct XXX* gom_get_first_XXX();<br>
+struct XXX* gom_get_XXX_by_xref(char* xref);</code><br>
+ </blockquote>
+ </li>
+</ul>
+<blockquote>The XXX stands for one of the following: <code>family, </code><code>individual, multimedia, note, repository, source, submitter, user_rec</code>.<br>
+</blockquote>
+<h3><a name="Object_model_structure"></a>Object model structure<br>
+</h3>
+All records of a certain type are linked together in a linked list. The
+above functions only give access to the first record of each linked list.
+ The others can be accessed by traversing the linked list via the <code>next</code> member of the structs. This means that e.g. the following piece of code will traverse the linked list of family records:<br>
+<blockquote><code>struct family* fam;<br>
+ <br>
+for (fam = gom_get_first_family() ; fam ; fam = fam->next) {<br>
+ ...<br>
+}</code><br>
+</blockquote>
+The <code>next</code> member of the last element in the list is guaranteed to have the <code>NULL</code> value.<br>
+<br>
+Actually, the linked list is a doubly-linked list: each record also has a <code>previous</code> member. But for implementation reasons the behaviour of this <code>previous</code> member on the edges of the linked list will not be guaranteed, i.e. it can be circular or terminated with <code>NULL</code>, no assumptions can be made in the application code.<br>
+<br>
+This linked-list model applies also to all sub-structures of the main record structs, i.e. each struct that has a <code>next </code>and <code>previous</code>
+member following the above conventions. This means that the following
+piece of code traverses all children of a family (see the details of the
+different structs <a href="gomxref.html">here</a>):<br>
+<blockquote><code>struct family* fam = ...;<br>
+ <br>
+struct xref_list* xrl;<br>
+for (xrl = fam->children ; xrl ; xrl = xrl->next) {<br>
+ ...<br>
+}</code> <br>
+</blockquote>
+Note that all character strings in the object model are encoded in UTF-8 (<a href="file:///home/verthezp/src/external/gedcom-parse/doc/encoding.html">Why UTF-8?</a>).<br>
+<h3><a name="User_data"></a>User data</h3>
+Each of the structs has an extra member called <code>extra</code> (of type <code>struct user_data*</code>).
+ This gathers all non-standard GEDCOM tags within the scope of the struct
+in a flat linked list, no matter what the internal structure of the non-standard
+tags is. Each element of the linked list has:<br>
+<ul>
+ <li>a level: the level number in the GEDCOM file</li>
+ <li>a tag: the tag given in the GEDCOM file</li>
+ <li>a value: the value, which can be a string value or a cross-reference value (one of the two will be non-NULL)<br>
+ </li>
+</ul>
+This way, none of the information in the GEDCOM file is lost, even the non-standard information.<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