<li><a href="#Start_and_end_callbacks">Start and end callbacks</a></li>
<li><a href="#Default_callbacks">Default callbacks</a></li>
- </ul><li><a href="#C_object_model">C object model</a></li>
+ </ul><li><a href="#Support_for_writing_GEDCOM_files">Support for writing GEDCOM files</a></li>
<ul>
- <li><a href="#Main_functions">Main functions</a></li>
- <li><a href="#Object_model_structure">Object model structure</a></li>
- <li><a href="#User_data">User data</a><br>
+ <li><a href="#Opening_and_closing_files">Opening and closing files</a></li>
+ <li><a href="#Controlling_some_settings">Controlling some settings</a></li>
+ <li><a href="#Writing_data">Writing data</a><br>
</li>
</ul>
-
- <li><a href="#Other_API_functions">Other API functions</a></li>
+<li><a href="#Other_API_functions">Other API functions</a></li>
<ul>
<li><a href="#Debugging">Debugging</a></li>
</ul>
<li><a href="#Converting_character_sets">Converting character sets</a></li>
- <li><a href="#Support_for_configure.in">Support for configure.in</a><br>
+ <li><a href="#Support_for_configure.in">Development support</a><br>
<br>
</li>
- <li><a href="interface.html">Interface details of the callback parser</a></li><li><a href="gomxref.html">C object model details</a><br>
+ <li><a href="interface.html">Interface details of the callback parser</a></li><li><a href="gom.html">C object model</a><br>
</li>
</li>
-</ul>
-
- Next to these, there is also a data directory in <code>$PREFIX/share/gedcom-parse</code>
+</ul>There is a separate script to help with library and compilation flags, see the <a href="#Support_for_configure.in">development support</a>.<br>
+<br>
+Next to these, there is also a data directory in <code>$PREFIX/share/gedcom-parse</code>
that contains some additional stuff, but which is not immediately
important at first. I'll leave the description of the data directory
for later.<br>
on the linking of the program as the last option, so that its initialization
code is run first. 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>
+ <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">
<hr width="100%" size="2">
<h2><a name="Data_callback_mechanism"></a>Data callback mechanism</h2>
The most important use of the parser is of course to get the data
-out of the GEDCOM file. This section focuses on the callback mechanism (see the <a href="#C_object_model">next section</a> for the C object model). In fact, the mechanism involves two levels.<br>
+out of the GEDCOM file. This section focuses on the callback mechanism (see <a href="gom.html">here</a> for the C object model). In fact, the mechanism involves two levels.<br>
<br>
The primary level is that each of the sections in a GEDCOM file is
notified to the application code via a "start element" callback and an
<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>
+<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="Main_functions"></a>Main functions<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>
-The following functions are available to get at these structs:<br>
+Note that by default the file is written in ASCII encoding (and hence e.g.
+accented characters will cause a conversion failure). 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> (const char* charset, Encoding width, Enc_bom bom);<br></code></blockquote>
+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>
- <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>
+<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_line_end end);<br></code></blockquote>
+The <code>end</code> parameter takes one of the following values:<br>
+<ul>
+ <li><b><code>END_CR</code></b>: only carriage return ("/r") (cf. Macintosh)</li>
+ <li><b><code>END_LF</code></b>: only line feed ("/n") (cf. Unix, Mac OS X)</li>
+ <li><b><code>END_CR_LF</code></b>: first carriage return, then line feed ("/r/n") (cf. 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>
-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>
+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 (currently) no compatibility mode for writing GEDCOM files.<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>
+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>
-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>
+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, char* xrefstr, 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, 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, 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, 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, struct age_value*
+value);</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>
+<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, char* tag, char* xrefstr,<br>
+ char* value);<br>
+i</code><code>nt <b>gedcom_write_user_xref</b> (Gedcom_write_hndl hndl, </code><code>int level, char* tag, char* xrefstr,</code><br>
+ <code>
+ 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>
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 example implementation (<code>utf8-locale.c</code>
- and <code> utf8-locale.h</code> in the "t" subdirectory of the top directory).
- 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). <br>
- <br>
- Its interface is:<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>
- </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>
+ <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>Support for configure.in</h2>
- Programs using the GEDCOM parser library and using autoconf to configure
- their sources can use the following statements in configure.in (the example
- is checking for gedcom-parse, version 1.34):<br>
-
-<blockquote><code>AC_CHECK_LIB(gedcom, gedcom_parse_file,,<br>
- AC_MSG_ERROR(Cannot
- find libgedcom: Please install gedcom-parse))<br>
- AC_MSG_CHECKING(for libgedcom version)<br>
- AC_TRY_RUN([<br>
- #include <stdio.h><br>
- #include <stdlib.h><br>
- #include <gedcom.h><br>
- int<br>
- main()<br>
- {<br>
- if (GEDCOM_PARSE_VERSION >= 1034) exit(0);<br>
- exit(1);<br>
- }],<br>
- ac_gedcom_version_ok='yes',<br>
- ac_gedcom_version_ok='no',<br>
- ac_gedcom_version_ok='no')<br>
- if test "$ac_gedcom_version_ok" = 'yes' ; then<br>
- AC_MSG_RESULT(ok)<br>
- else<br>
- AC_MSG_RESULT(not ok)<br>
- AC_MSG_ERROR(You need at least version 1.34 of gedcom-parse)<br>
- fi</code><br>
- </blockquote>
- There are three preprocessor symbols defined for version checks in the
- header:<br>
+<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>
</ul>
- The last one is equal to <code>(GEDCOM_PARSE_VERSION_MAJOR * 1000) + GEDCOM_PARSE_VERSION_MINOR.</code><br>
+ 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> </pre>
+<br>
+<br>
+<br>
+<br>
+<br>
+<br>
+<br>
+<br>
<br>
<br>
</body></html>
\ No newline at end of file