doc/doxygen/index.doc

   1 /* Documentation file
   2    Copyright (C) 2001,2002,2003 The Genes Development Team
   3    This file is part of the Gedcom parser library.
   4    Contributed by Peter Verthez <Peter.Verthez@advalvas.be>, 2003.
   5
   6    The Gedcom parser library is free software; you can redistribute it
   7    and/or modify it under the terms of the GNU Lesser General Public
   8    License as published by the Free Software Foundation; either
   9    version 2.1 of the License, or (at your option) any later version.
  10
  11    The Gedcom parser library is distributed in the hope that it will be
  12    useful, but WITHOUT ANY WARRANTY; without even the implied warranty of
  13    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  14    Lesser General Public License for more details.
  15
  16    You should have received a copy of the GNU Lesser General Public
  17    License along with the Gedcom parser library; if not, write to the
  18    Free Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA
  19    02111-1307 USA.  */
  20
  21 /* $Id$ */
  22 /* $Name$ */
  23
  24 /*! \mainpage The Gedcom Parser Library
  25
  26   The Gedcom Parser Library is a C library that provides an API to applications
  27   to parse and process arbitrary genealogy files in the standard GEDCOM format.
  28   It supports
  29   <a href="http://www.gendex.com/gedcom55/55gctoc.htm">release 5.5</a> of the
  30   GEDCOM standard.
  31
  32   The following links provide a manual to the Gedcom parser library:
  33
  34    - \ref callback
  35    - \ref gom
  36
  37   The Gedcom Parser Library provides two interfaces.  On the one hand, it can
  38   be used as a callback-based parser (comparable to the SAX interface of XML);
  39   on the other hand, the parser can be used to convert the GEDCOM file into an
  40   object model (comparable to the DOM interface of XML).  It comes with:
  41
  42    - a library (\c libgedcom.so), to be linked in the application program,
  43      which implements the callback parser
  44    - a header file (\c gedcom.h), to be used in the sources of the application
  45      program
  46    - a header file (\c gedcom-tags.h) that is also installed, but that is
  47      automatically included via \c gedcom.h
  48
  49   Additionally, if you want to use the C object model, the following should be
  50   used (note that \c libgedcom.so is also needed in this case, because the
  51   object model uses the callback parser internally):
  52
  53    - a library (\c libgedcom_gom.so), to be linked in the application program,
  54      which implements the C object model
  55    - a header file (\c gom.h), to be used in the source of the application
  56      program
  57
  58   There is a separate script and an M4 macro (for autoconf) to help with
  59   library and compilation flags, see the development support (TODO: REFERENCE!)
  60 */
  61
  62 /*! \defgroup callback Callback Interface */
  63
  64 /*! \defgroup gom Gedcom Object Model in C */
  65
  66 /*! \defgroup main Main functions of the parser
  67     \ingroup callback
  68
  69   The very simplest call of the Gedcom callback parser is simply the following
  70   piece of code (include of the \c gedcom.h header is assumed, as everywhere
  71   in this manual):
  72
  73   \code
  74   int result;
  75   ...
  76   gedcom_init();
  77   ...
  78   result = gedcom_parse_file("myfamily.ged");
  79   \endcode
  80
  81   Although this will not provide much information, one thing it does is parse
  82   the entire file and return the result.
  83
  84   The next sections will refine this
  85   piece of code to be able to have meaningful errors and the actual data that
  86   is in the file.
  87 */
  88
  89 /*! \defgroup error Error handling
  90     \ingroup callback
  91
  92   The library can be used in several different circumstances, both
  93   terminal-based as GUI-based.  Therefore, it leaves the actual display of the
  94   error message up to the application.
  95
  96   For this, the application needs to register a callback before parsing the
  97   GEDCOM file, which will be called by the library on errors, warnings and
  98   messages.
  99
 100   A typical piece of code would be:
 101
 102   \code
 103   void my_message_handler(Gedcom_msg_type type, char* msg)
 104   {
 105     ...
 106   }
 107   ...
 108   gedcom_set_message_handler(my_message_handler);
 109   ...
 110   result = gedcom_parse_file("myfamily.ged");
 111   \endcode
 112
 113   With this in place, the resulting code will show errors and warnings produced
 114   by the parser, e.g. on the terminal if a simple \c printf is used in the
 115   message handler.
 116 */
 117
 118 /*! \defgroup cb_mech Data callback mechanism
 119     \ingroup callback
 120 */
 121
 122 /*! \defgroup write Support for writing GEDCOM files
 123     \ingroup callback
 124 */
 125
 126 /*! \defgroup gommain Main functions of the object model
 127     \ingroup gom
 128
 129   Programs using the Gedcom object model in C should use the following
 130   (inclusion of
 131   both the \c gedcom.h and \c gom.h headers is required; contrast this with
 132   the example given for the \ref main "callback parser"):
 133
 134   \code
 135   int result;
 136   ...
 137   gedcom_init();
 138   ...
 139   result = gom_parse_file("myfamily.ged");
 140   \endcode
 141 */