X-Git-Url: https://git.dlugolecki.net.pl/?a=blobdiff_plain;f=doc%2Fusage.html;h=a71b855221b5643a9fd96d5fbd29b8835e163748;hb=82c71c8f5fb0c80e1ad689c320c8d9163b3495b0;hp=225470e6c4f56daf6ef2d4a947abfe05a1eebb7c;hpb=d8da8e963c3bc71c777ce132aca3c6d792e699d4;p=gedcom-parse.git diff --git a/doc/usage.html b/doc/usage.html index 225470e..a71b855 100644 --- a/doc/usage.html +++ b/doc/usage.html @@ -163,7 +163,7 @@ out of the GEDCOM file.  This section focuses on the callback mechanism is called for that tag, and when all its subordinate lines with their tags have been processed, the "end element" callback is called for the original tag.  Since GEDCOM is hierarchical, this results in properly -nested calls to appropriate "start element" and "end element" callbacks.
+nested calls to appropriate "start element" and "end element" callbacks (note: see compatibility handling).

However, it would be typical for a genealogy program to support only a subset of the GEDCOM standard, certainly a program that is still under @@ -336,7 +336,9 @@ in the section for record callbacks above.
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.

Further, it is possible to control the kind of line terminator that is used, via the following function (also to be used before gedcom_write_open):
-
int gedcom_write_set_line_terminator (Enc_line_end end);
+
int gedcom_write_set_line_terminator (Enc_from from, Enc_line_end end);
The values for the from parameter are given above.  The value ENC_FROM_SYS +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.
+
The end parameter takes one of the following values:
By default, this is set to the appropriate line terminator on the current @@ -494,14 +509,14 @@ 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.
+is no compatibility mode for writing GEDCOM files (and probably never will be).

In general, each of the following functions expect their input in UTF-8 encoding (see also here).  If this is not the case, errors will be returned.

Note that for examples of using these functions you can look at the sources for the Gedcom object model (e.g. the function write_header in gom/header.c).

Records

For writing lines corresponding to records (i.e. on level 0), the following function is available: -
int gedcom_write_record_str (Gedcom_write_hndl hndl, Gedcom_rec rec, char* xrefstr, char* value);
+
int gedcom_write_record_str (Gedcom_write_hndl hndl, Gedcom_rec rec, const char* xrefstr, const char* value);
The hndl parameter is the write handle that was returned by gedcom_write_open.  The rec parameter is one of the identifiers given in the first column in this table (except REC_USER: see below).  The xrefstr and val parameters are respectively the cross-reference key of the record (something like '@FAM01@'), and the value of the record line, which should be NULL for some record types, according to the same table.

Elements

For writing lines corresponding to elements (inside records, i.e. on a level @@ -509,18 +524,18 @@ bigger than 0), the following functions are available, depending on the data type:
int gedcom_write_element_str  (Gedcom_write_hndl hndl, Gedcom_elt elt, int parsed_tag,
                      -         int parent_rec_or_elt, char* value);
+         int parent_rec_or_elt, const char* value);
int gedcom_write_element_xref (Gedcom_write_hndl hndl, Gedcom_elt elt, int parsed_tag,
                      -         int parent_rec_or_elt, struct xref_value* +         int parent_rec_or_elt, const struct xref_value* value);
int gedcom_write_element_date (Gedcom_write_hndl hndl, Gedcom_elt elt, int parsed_tag,
                      -         int parent_rec_or_elt, struct date_value* +         int parent_rec_or_elt, const struct date_value* value);
int gedcom_write_element_age  (Gedcom_write_hndl hndl, Gedcom_elt elt, int parsed_tag,
                      -         int parent_rec_or_elt, struct age_value* +         int parent_rec_or_elt, const struct age_value* value);
@@ -537,11 +552,12 @@ all its struct fields filled in properly and consistent.  This can be done by calling gedcom_normalize_date (see here).

User-defined tags

For user-defined tags (tags starting with an underscore), there are separate functions, again depending on the data type: -
int gedcom_write_user_str  (Gedcom_write_hndl hndl, int level, char* tag, char* xrefstr,
-                            char* value);
-int gedcom_write_user_xref (Gedcom_write_hndl hndl, int level, char* tag, char* xrefstr,
- -                            struct xref_value* value);
+
int gedcom_write_user_str  (Gedcom_write_hndl hndl, int level, const char* tag, const char* xrefstr,
+                            const char* value);
+int gedcom_write_user_xref (Gedcom_write_hndl hndl, int level, const char* tag, const char* xrefstr,
+ +                      +      const struct xref_value* value);
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 @@ -635,7 +651,43 @@ default)
- Currently, there is a beginning for compatibility for ftree and Lifelines (3.0.2).
+ Currently, there is (some) compatibility for:
+ +The following function allows to set some options for the compatibility handling:
+
void gedcom_set_compat_options (Gedcom_compat options)
+
+The parameter can be an OR'ed combination of the following options:
+ +
+
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
+
1 DATE ...
+2 TIME ...
+
+the genealogy program has generated something like:
+
1 DATE ...
+1 TIME ...
+
+This can give a problem if your end element callbacks free some resources.  
+
+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.
+
+
+
+

Converting character sets

@@ -735,4 +787,6 @@ gedcom-config --libs gom



+
+
\ No newline at end of file