X-Git-Url: https://git.dlugolecki.net.pl/?a=blobdiff_plain;f=doc%2Fusage.html;h=a71b855221b5643a9fd96d5fbd29b8835e163748;hb=e64a3ac05141381579c407b779d6db66ecdb367d;hp=1c59ae9dc2a126295800cfeb46ea2b61cf507c86;hpb=c80fb171c952d002191509a343bb4c3747dffc35;p=gedcom-parse.git
diff --git a/doc/usage.html b/doc/usage.html
index 1c59ae9..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
@@ -470,18 +479,24 @@ values:WITHOUT_BOM
WITH_BOM
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);
@@ -537,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 @@ -635,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);
- 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:- ftree
+- Lifelines (3.0.2)
+- Personal Ancestral File (PAF), version 2, 4 and 5
+- Family Origins
+- EasyTree
+
++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.
+
+
Converting character sets
@@ -661,11 +713,23 @@ 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:
-AM_LIB_GEDCOM_PARSER([major,[minor,[patch]]])
+All the arguments are optional and default to 0. E.g. to check for -version 1.34, you would put in configure.in the following statement:AM_PATH_GEDCOM_PARSER([min_version,[action_if_found,[action_if_not_found,[modules]]]])
-AM_LIB_GEDCOM_PARSER(1,34)
+version 1.34.2, you would put in configure.in the following statement:
+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).AM_PATH_GEDCOM_PARSER(1.34.2)
+
+
+The macro also sets the variablesGEDCOM_CFLAGS
andGEDCOM_LIBS
for use in Makefiles. Typically, this would be done as follows in a Makefile.am:
++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 isbin_programs = myprg
+myprg_SOURCES = myprg.c foo.c bar.c
+INCLUDES = @GEDCOM_CFLAGS@
+LDADD = @GEDCOM_LIBS@gom
(the Gedcom object model). For example:
+To be able to use this macro in the sources of your application, you have three options:AM_PATH_GEDCOM_PARSER(0.21.2, , ,gom)
@@ -689,10 +753,10 @@ There are three preprocessor symbols defined for version checks in the
- The last one is equal to(GEDCOM_PARSE_VERSION_MAJOR * 1000) + GEDCOM_PARSE_VERSION_MINOR.
+ The last one is equal to(GEDCOM_PARSE_VERSION_MAJOR * 1000) + GEDCOM_PARSE_VERSION_MINOR.
As you see, this only checked the major and minor version, not the patch number, so this is obsolete.
Compilation and linking flags
-Similar to other libraries, the GEDCOM parse library installs a scriptgedcom-config
to help with compilation and linking flags.
+Similar to other libraries, the GEDCOM parse library installs a scriptgedcom-config
to help with compilation and linking flags for programs that don't use autoconf/automake.
To get compilation flags for your program, use (depending on whether you only use the callback parser, or also the GEDCOM object model): @@ -722,4 +786,7 @@ gedcom-config --libs gom
+
+
+