+ </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_ctxt parent,
+int level, char* tag, char* raw_value)<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(int level, Gedcom_val xref, char* tag)<br>
+ {<br>
+ struct header head = my_make_header_struct();<br>
+ return (Gedcom_ctxt)head;<br>
+ }<br>
+ <br>
+ void my_default_cb(Gedcom_ctxt parent, int level, char* tag, char* raw_value)<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>
+
+ <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 libgedcom, 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>
+ Note that, currently, no actual compatibility code is present, but this
+is on the to-do list.<br>
+
+ <hr width="100%" size="2">
+ <pre>$Id$<br>$Name$<br></pre>
+ <pre>
+ </pre>
+
+ </body>
+ </html>