X-Git-Url: https://git.dlugolecki.net.pl/?a=blobdiff_plain;f=doc%2Fusage.html;h=0a8c7e85c5ece5d1352d099348de28d8366d81f0;hb=0c115941610604f62f53b2e4f1dfb67427863f13;hp=ee3e248bae1331b1f9d175c2320c416ef024881d;hpb=7372fd1bb10934271adbb12fe27f45df8ea225d2;p=gedcom-parse.git diff --git a/doc/usage.html b/doc/usage.html index ee3e248..0a8c7e8 100644 --- a/doc/usage.html +++ b/doc/usage.html @@ -17,15 +17,7 @@
-lgedcom
option
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: -lgedcom_gom -lgedcom
gedcom_init()
also initializes locale handling by calling setlocale(LC_ALL, "")
, in case the application would not do this (it doesn't hurt for the application to do the same).gom_parse_file()
. For this, an entire model based on C structs is used. These structs are documented here,
-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.struct header* gom_get_header();
-struct submission* gom_get_submission();
-
- -struct XXX* gom_get_first_XXX();
-struct XXX* gom_get_XXX_by_xref(char* xref);
-
The XXX stands for one of the following:-family,
individual, multimedia, note, repository, source, submitter, user_rec
.
-
next
member of the structs. This means that e.g. the following piece of code will traverse the linked list of family records:-Thestruct family* fam;
-
-for (fam = gom_get_first_family() ; fam ; fam = fam->next) {
- ...
-}
-
next
member of the last element in the list is guaranteed to have the NULL
value.previous
member. But for implementation reasons the behaviour of this previous
member on the edges of the linked list will not be guaranteed, i.e. it can be circular or terminated with NULL
, no assumptions can be made in the application code.next
and previous
-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 here):-Note that all character strings in the object model are encoded in UTF-8 (Why UTF-8?).struct family* fam = ...;
-
-struct xref_list* xrl;
-for (xrl = fam->children ; xrl ; xrl = xrl->next) {
- ...
-}
-
extra
(of type struct user_data*
).
- 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:gettext
mechanism in the application.
-gedcom-parse
contains an example implementation (utf8-locale.c
- and utf8-locale.h
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).
see
+the "utf8" subdirectory of the top directory). Feel free to use
+ it in your source code. It isn't installed anywhere, so you need
+to take over the source and header files in your application. Note that on
+some systems it uses libcharset, which is also included in this subdirectory.
+ -The +first one returns 1 if the given input is a valid UTF-8 string, it returns +0 otherwise, the second gives the number of UTF-8 characters in the given +input. Note that the second function assumes that the input is valid +UTF-8, and gives unpredictable results if it isn't.+char *convert_utf8_to_locale (char *input, int *conv_failures);
char *convert_locale_to_utf8 (char *input);int is_utf8_string (char *input);
int utf8_strlen (char *input);
+++char *convert_utf8_to_locale (char *input, int *conv_failures);
char *convert_locale_to_utf8 (char *input);
+ 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
setlocale
function (the second step detailed
@@ -747,45 +686,38 @@ handle needs to be closed (when the program exits):- - The example implementation - mentioned above grows the output buffer dynamically and outputs "?" for characters + + The example implementation +mentioned above grows the output buffer dynamically and outputs "?" for characters that can't be converted.iconv_close(iconv_handle);
- There are three preprocessor symbols defined for version checks in the - header:AC_CHECK_LIB(gedcom, gedcom_parse_file,,
- AC_MSG_ERROR(Cannot - find libgedcom: Please install gedcom-parse))
- AC_MSG_CHECKING(for libgedcom version)
- AC_TRY_RUN([
- #include <stdio.h>
- #include <stdlib.h>
- #include <gedcom.h>
- int
- main()
- {
- if (GEDCOM_PARSE_VERSION >= 1034) exit(0);
- exit(1);
- }],
- ac_gedcom_version_ok='yes',
- ac_gedcom_version_ok='no',
- ac_gedcom_version_ok='no')
- if test "$ac_gedcom_version_ok" = 'yes' ; then
- AC_MSG_RESULT(ok)
- else
- AC_MSG_RESULT(not ok)
- AC_MSG_ERROR(You need at least version 1.34 of gedcom-parse)
- fi
-
+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_LIB_GEDCOM_PARSER([major,[minor,[patch]]])
+
+To be able to use this macro in the sources of your application, you have three options:AM_LIB_GEDCOM_PARSER(1,34)
+
m4/gedcom.m4
in your autoconf data directory (i.e. the path given by 'aclocal --print-ac-dir
', usually /usr/share/aclocal
). You can do this automatically by going into the m4 subdirectory and typing 'make install-m4
'.m4/gedcom.m4
in the aclocal.m4
file in your sources.m4/gedcom.m4
in the acinclude.m4
file in your sources.GEDCOM_PARSE_VERSION_MAJOR
(GEDCOM_PARSE_VERSION_MAJOR * 1000) + GEDCOM_PARSE_VERSION_MINOR.
+