X-Git-Url: https://git.dlugolecki.net.pl/?a=blobdiff_plain;f=doc%2Fusage.html;h=a71b855221b5643a9fd96d5fbd29b8835e163748;hb=e64a3ac05141381579c407b779d6db66ecdb367d;hp=39a0cb3594f58e5ca6cfeb0a30d3c1e99c09f371;hpb=3ee5b48397287fe02a74620cb9ec87e670ab5881;p=gedcom-parse.git
diff --git a/doc/usage.html b/doc/usage.html
index 39a0cb3..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.
Gedcom_val
argument of the end callback
- is currently not used. It is there for future enhancements.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
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.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: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.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.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")write_header
in gom/header.c
).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.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);
i
nt 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).
-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);
+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,43 @@ default)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);
+The parameter can be an OR'ed combination of the following options:void gedcom_set_compat_options (Gedcom_compat 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+
++the genealogy program has generated something like:1 DATE ...
+2 TIME ...
+
++This can give a problem if your end element callbacks free some resources.1 DATE ...
+1 TIME ...
+
+
+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.
+