X-Git-Url: https://git.dlugolecki.net.pl/?a=blobdiff_plain;f=doc%2Fusage.html;h=0a8c7e85c5ece5d1352d099348de28d8366d81f0;hb=689214a4ea2c158a838b6b8129719d9dbf8cabb3;hp=ee3d2d4b1133ea50d60f301feb1ef40107719a84;hpb=c7d446fe2de9a4b79a122dbe9310fc5c03764eca;p=gedcom-parse.git diff --git a/doc/usage.html b/doc/usage.html index ee3d2d4..0a8c7e8 100644 --- a/doc/usage.html +++ b/doc/usage.html @@ -102,8 +102,9 @@ the -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
-
- The next sections will refine this piece of code to be able to have +
The function 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).
+ 
+The next sections will refine this piece of code to be able to have meaningful errors and the actual data that is in the file.
@@ -515,17 +516,29 @@ controls the gettext mechanism in the application.  

The source distribution of -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).  
+gedcom-parse contains an a library implementing help functions for UTF-8 encoding (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. +  

- Its interface is:
+ Its interface contains first of all the following two help functions:
- 
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);
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.
+
+For conversion, the following functions are available:
+
+ 
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 @@ -673,45 +686,38 @@ handle needs to be closed (when the program exits):
iconv_close(iconv_handle);
- - 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.
-

Support for configure.in

- Programs using the GEDCOM parser library and using autoconf to configure - their sources can use the following statements in configure.in (the example - is checking for gedcom-parse, version 1.34):
- -
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
-
- There are three preprocessor symbols defined for version checks in the - header:
+

Support for configure.in

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_LIB_GEDCOM_PARSER(1,34)
+
+To be able to use this macro in the sources of your application, you have three options:
+ +
+There are three preprocessor symbols defined for version checks in the + header (but their direct use is deprecated: please use the macro above):
The last one is equal to (GEDCOM_PARSE_VERSION_MAJOR * 1000) + GEDCOM_PARSE_VERSION_MINOR.
+
@@ -730,6 +737,9 @@ handle needs to be closed (when the program exits):
+
+
+