X-Git-Url: https://git.dlugolecki.net.pl/?a=blobdiff_plain;f=doc%2Fusage.html;h=44bdb95f340ff8f32f71773c645385d81054959f;hb=9ae65232975e359f903cbd9f2cb0f1fc4ec58891;hp=39a0cb3594f58e5ca6cfeb0a30d3c1e99c09f371;hpb=3ee5b48397287fe02a74620cb9ec87e670ab5881;p=gedcom-parse.git
diff --git a/doc/usage.html b/doc/usage.html
index 39a0cb3..44bdb95 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.
- The
Gedcom_val argument of the end callback
- is currently not used. It is there for future enhancements.
+ is used to pass 'complete' values, e.g. the full text of a note. See
+ the interface details
+ for the exact type of this argument.
- There are also two
Gedcom_val arguments
in the start callback for records. The first one (xref
) contains the xref_value corresponding to the cross-reference
@@ -445,11 +447,18 @@ you can pass NULL if you're not interested. The function retu
Controlling some settings
-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
+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 before calling gedcom_write_open, i.e. it affects all files that are opened after it is being called:
int gedcom_write_set_encoding (const char* charset, Encoding width, Enc_bom bom);
+int gedcom_write_set_encoding (Enc_from from, const char* charset, Encoding width, Enc_bom bom);
The from parameter indicates how you want the encoding to be set:
+
+ ENC_FROM_FILE: The same as the read file was in (this is the default).ENC_FROM_SYS: Not a valid value here, see below for gedcom_write_set_terminator
+ ENC_MANUAL: From the values given in the following parameters.
+When ENC_FROM_FILE is selected, the other parameters in the function are ignored (they can be passed as 0). When ENC_MANUAL is chosen, the meaning of the other parameters is as follows:
+
The valid charset values are given in the first column in the file gedcom.enc in the data directory of gedcom-parse ($PREFIX/share/gedcom-parse).
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
@@ -478,12 +487,16 @@ 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:
- END_CR: only carriage return ("/r") (cf. Macintosh)END_LF: only line feed ("/n") (cf. Unix, Mac OS X)END_CR_LF: first carriage return, then line feed ("/r/n") (cf. DOS, Windows)END_CR: only carriage return ("/r") (system value for Macintosh)END_LF: only line feed ("/n") (system value for Unix, Mac OS X)END_CR_LF: first carriage return, then line feed ("/r/n") (system value for DOS, Windows)END_LF_CR: first line feed, then carriage return ("/n/r")
By default, this is set to the appropriate line terminator on the current
@@ -496,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
@@ -511,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);
@@ -539,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
@@ -637,7 +651,41 @@ default)
- Currently, there is a beginning for compatibility for ftree and Lifelines (3.0.2).
+ Currently, there is (some) compatibility for:
+
+ - ftree
+ - Lifelines (3.0.2)
+ - Personal Ancestral File (PAF), version 2, 4 and 5
+ - Family Origins
+ - EasyTree
+
+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:
+
+ COMPAT_ALLOW_OUT_OF_CONTEXT
+
+ 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). The Gedcom object model in C has this option enabled.
+
+
+
+
Converting character sets
@@ -738,4 +786,6 @@ gedcom-config --libs gom
+
+