Doxygen files.

[gedcom-parse.git] / README

diff --git a/README b/README
index e69de29bb2d1d6434b8b29ae775ad8c2e48c5391..84a7d7bc5e0d2a3076275067ef5b901d967b001a 100644 (file)
--- a/README
+++ b/README
@@ -0,0 +1,112 @@
+The Gedcom parser library (release @VERSION@)
+-------------------------
+The Gedcom parser library is a C library that provides an API to applications
+to parse, process and write arbitrary genealogy files in the standard gedcom
+format.
+
+Its main features are:
+
+ - portable to any POSIX systems (libiconv is needed on systems that lack
+   glibc 2.2, see below)
+
+ - strict callback-based parser written in C (using lex/yacc), a C object
+   model is also available (compare to the difference between SAX and DOM
+   in XML).
+
+ - supports the Gedcom 5.5 standard fully
+
+ - supports the standard encoding formats (ASCII, ANSEL, UNICODE), but
+   extensible (via a configuration file) to other encoding formats; by
+   default ANSI is also supported.
+
+ - all strings passed from callbacks to the using program are in UTF-8 format
+
+ - internationalization of the error and warning messages
+
+ - specific parsing of date values to a calendar-neutral date system (Julian
+   days aka serial day numbers); the date parser can be called separately and
+   dates can be manipulated
+
+ - specific parsing and checking of cross-references
+
+ - specific parsing of age values
+
+ - support for writing Gedcom files (both in line-by-line format, or via the
+   Gedcom object model)
+
+ - "compatibility-mode" parsing, to allow for not-exactly-standard syntaxes
+   used by other genealogy programs; currently, compatibility is added for
+   (not necessarily complete):
+     - ftree
+     - Lifelines 3.0.2
+     - Personal Ancestral File (PAF), version 2, 4 and 5
+     - Family Origins
+     - EasyTree
+
+NOTE:
+ - NO BACKWARD COMPATIBILITY is guaranteed for 0.x releases !
+
+To do list:
+ - specific parsing of other special values
+ - compatibility with other genealogy programs
+ - older/newer Gedcom standards ?
+ - writing GEDML files
+ - C++ object model
+ - ...
+
+For more information, refer to the documentation in the doc subdirectory,
+or to the SourceForge project web site and summary page:
+  http://gedcom-parse.sourceforge.net
+  http://sourceforge.net/projects/gedcom-parse
+
+Also, have a look at the 'Genes' program, from which this library is a
+spin-off, and which uses this library:
+  http://genes.sourceforge.net
+  http://sourceforge.net/projects/genes
+
+
+Requirements:
+------------
+For using the library:
+ - either glibc 2.2 or higher, or libiconv
+
+Note:
+
+  The official libiconv package doesn't have ANSEL support, and is not
+  extensible except by modifying its source code.
+
+  There is a modified libiconv package available on the SourceForge project
+  page, which is called 'libiconv-gedcom-1.8.x', based on libiconv 1.8.
+  Install this if you need ANSEL support and you don't have glibc 2.2.
+
+To compile the package, you'll need:
+ - gcc
+
+To compile from the CVS sources, you'll need in addition:
+ - autoconf
+ - automake
+ - flex
+ - bison (won't work with plain yacc)
+ - perl
+
+
+Installation:
+------------
+This is simply:
+
+  ./configure
+  make
+  make install
+
+If libiconv is not automatically found, you can give its path to configure,
+for example, if the library lives in /home/mydir/lib:
+
+  ./configure --with-libiconv-prefix=/home/mydir
+
+You can also run some tests via:
+  make check
+
+
+###############################################################################
+# $Id$
+# $Name$