Some additional configuration.

[gedcom-parse.git] / doc / doxygen / index.doc

/* Documentation file
   Copyright (C) 2001,2002,2003 The Genes Development Team
   This file is part of the Gedcom parser library.
   Contributed by Peter Verthez <Peter.Verthez@advalvas.be>, 2003.

   The Gedcom parser library is free software; you can redistribute it
   and/or modify it under the terms of the GNU Lesser General Public
   License as published by the Free Software Foundation; either
   version 2.1 of the License, or (at your option) any later version.

   The Gedcom parser library is distributed in the hope that it will be
   useful, but WITHOUT ANY WARRANTY; without even the implied warranty of
   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
   Lesser General Public License for more details.

   You should have received a copy of the GNU Lesser General Public
   License along with the Gedcom parser library; if not, write to the
   Free Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA
   02111-1307 USA.  */

/* $Id$ */
/* $Name$ */

/*! \mainpage The Gedcom Parser Library

  The Gedcom Parser Library is a C library that provides an API to applications
  to parse and process arbitrary genealogy files in the standard GEDCOM format.
  It supports
  <a href="http://www.gendex.com/gedcom55/55gctoc.htm">release 5.5</a> of the
  GEDCOM standard.

  The following links provide a manual to the Gedcom parser library:

   - \ref callback
   - \ref gom

  \section libraries_headers Libraries and headers
  
  The Gedcom Parser Library provides two interfaces.  On the one hand, it can
  be used as a callback-based parser (comparable to the SAX interface of XML);
  on the other hand, the parser can be used to convert the GEDCOM file into an
  object model (comparable to the DOM interface of XML).  It comes with:

   - a library (\c libgedcom.so), to be linked in the application program,
     which implements the callback parser
   - a header file (\c gedcom.h), to be used in the sources of the application
     program
   - a header file (\c gedcom-tags.h) that is also installed, but that is
     automatically included via \c gedcom.h

  Additionally, if you want to use the C object model, the following should be
  used (note that \c libgedcom.so is also needed in this case, because the
  object model uses the callback parser internally):

   - a library (\c libgedcom_gom.so), to be linked in the application program,
     which implements the C object model
   - a header file (\c gom.h), to be used in the source of the application
     program

  There is a separate script and an M4 macro (for autoconf) to help with
  library and compilation flags, see the \ref devel "development support".

  \section utf8 Converting character sets

  All strings passed by the GEDCOM parser to the application are in UTF-8
  encoding.  Typically, an application needs to convert this to something
  else to be able to display it.

  The most common case is that the output character set is controlled by the
  locale mechanism (i.e. via the LANG, LC_ALL or LC_CTYPE environment
  variables), which also controls the gettext mechanism in the application.  

  With gedcom-parse comes a library implementing help functions for UTF-8
  encoding (see the <a href=utf8tools.html>documentation</a> for this library).
*/

/*! \defgroup callback Callback Interface */

/*! \defgroup maingedcom Main functions of the parser
    \ingroup callback

  The very simplest call of the Gedcom callback parser is simply the following
  piece of code (include of the \c gedcom.h header is assumed, as everywhere
  in this manual):

  \code
  int result;
  ...
  gedcom_init();
  ...
  result = gedcom_parse_file("myfamily.ged");
  \endcode

  Although this will not provide much information, one thing it does is parse
  the entire file and return the result.

  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.
*/

/*! \defgroup error Error handling
    \ingroup callback

  The library can be used in several different circumstances, both
  terminal-based as GUI-based.  Therefore, it leaves the actual display of the
  error message up to the application.

  For this, the application needs to register a callback before parsing the
  GEDCOM file, which will be called by the library on errors, warnings and
  messages.

  A typical piece of code would be (gom_parse_file() would be called in case
  the C object model is used):

  \code
  void my_message_handler(Gedcom_msg_type type, char* msg)
  {
    ...
  }
  ...
  gedcom_set_message_handler(my_message_handler);
  ...
  result = gedcom_parse_file("myfamily.ged");
  \endcode

  With this in place, the resulting code will show errors and warnings produced
  by the parser, e.g. on the terminal if a simple \c printf is used in the
  message handler.
*/

/*! \defgroup cb_mech Data callback mechanism
    \ingroup callback
    
  The most important use of the parser is of course to get the data out of
  the GEDCOM file.  This section focuses on the callback mechanism (see
  \ref gom "here" for the C object model).  In fact, the mechanism involves
  two levels.

  The primary level is that each of the sections in a GEDCOM file is notified
  to the application code via a "start element" callback and an "end element"
  callback (much like in a SAX interface for XML), i.e. when a line containing
  a certain tag is parsed, the "start element" callback 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 (note: see
  \ref compat "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
  development.  Moreover, under GEDCOM it is allowed for an application to
  define its own tags, which will typically not  be supported by another
  application.  Still, in that case, data preservation is important; it would
  hardly be accepted that information that is not understood by a certain
  program is just removed.

  Therefore, the second level of callbacks involves a "default callback".  An
  application needs to subscribe to callbacks for tags it does support, and
  need to provide a "default callback" which will be called for tags it
  doesn't support.  The application can then choose to just store the
  information that comes via the default callback in plain textual format.  
*/

/*! \defgroup start_end Start and end callbacks
    \ingroup cb_mech

  The following simple example gets some information from the header record
  of a GEDCOM file.

  \code
    Gedcom_ctxt my_header_start_cb (Gedcom_rec rec,
                                    int level,
                                    Gedcom_val xref,
                                    char *tag,
                                    char *raw_value,
                                    int parsed_tag,
                                    Gedcom_val parsed_value)
    {
      printf("The header starts\n");
      return (Gedcom_ctxt)1;
    }

    void my_header_end_cb (Gedcom_rec rec, Gedcom_ctxt self)
    {
      printf("The header ends, context is %d\n", (int)self);
    }

    ...
    gedcom_subscribe_to_record(REC_HEAD, my_header_start_cb, my_header_end_cb);
    ...
    result = gedcom_parse_file("myfamily.ged");
  \endcode

  Using the gedcom_subscribe_to_record() function, the application requests
  to use the specified callbacks as start and end callback (type
  \ref Gedcom_rec_start_cb and \ref Gedcom_rec_end_cb).

  Such a callback
  can return a context value of type \ref Gedcom_ctxt.  This type is meant to
  be opaque; in fact, it's a void pointer, so you can pass anything via it.
  This context value will be passed to the callbacks of the direct
  child elements, and to the end callback.

  The example passes a simple integer as context, but an application could e.g.
  pass a \c struct (or an object in a C++ application) that will contain the
  information for the record.  In the end callback, the application could then
  e.g. do some finalizing operations on the \c struct to put it in its
  database.

  From the name of the function it becomes clear that this function is
  specific to complete records.  For the separate elements in records there
  is another function, which we'll see shortly.  Note that the callbacks need
  to have the signatures as shown in the example.

  We will now retrieve the SOUR field (the name of the program that wrote the
  file) from the header:
  \code
    Gedcom_ctxt my_header_source_start_cb(Gedcom_elt  elt,
                                          Gedcom_ctxt parent,
                                          int         level,
                                          char*       tag,
                                          char*       raw_value,
                                          int         parsed_tag,
                                          Gedcom_val  parsed_value)
    {
      char *source = GEDCOM_STRING(parsed_value);
      printf("This file was written by %s\n", source);
      return parent;
    }

    ...
    gedcom_subscribe_to_element(ELT_HEAD_SOUR,
                                my_header_source_start_cb,
                                NULL);
    ...
    result = gedcom_parse_file("myfamily.ged");
  \endcode

  The subscription mechanism for elements is similar, only the signatures of
  the callbacks differ.  The signature for the start callback shows that the
  context of the parent line (here e.g. the \c struct that describes the
  header) is passed to this start callback.

  The callback itself returns here in this example the same context, but this
  can be its own context object of course.  The end callback is called with
  both the context of the parent and the context of itself, which in this
  example will be the same.
*/

/*! \defgroup defcb Default callbacks
    \ingroup cb_mech

  An application doesn't always implement the entire GEDCOM spec, and
  application-specific tags may have been added by other applications.  To
  preserve this extra data anyway, a default callback can be registered by
  the application, as in the following example:

  \code
    void my_default_cb (Gedcom_elt elt, Gedcom_ctxt parent, int level,
                        char* tag, char* raw_value, int parsed_tag)
    {
      ...
    }

    ...
    gedcom_set_default_callback(my_default_cb);
    ...
    result = gedcom_parse_file("myfamily.ged");
  \endcode

  This callback has a similar signature as the previous ones, but it doesn't
  contain a parsed value.  However, it does contain the parent context, that
  was returned by the application for the most specific containing tag that
  the application supported.

  Suppose e.g. that this callback is called for some tags in the header that
  are specific to some other application, then our application could make
  sure that the parent context contains the struct or object that represents
  the header, and use the default callback here to add the level, tag and
  raw_value as plain text in a member of that struct or object, thus
  preserving the information.

  The application can then write this out when the data is saved again in a
  GEDCOM file.  To make it more specific, consider the following example:

  \code
    struct header {
      char* source;
      ...
      char* extra_text;
    };

    Gedcom_ctxt my_header_start_cb(Gedcom_rec rec, int level, Gedcom_val xref,
                                   char* tag, char *raw_value,
                                   int parsed_tag, Gedcom_val parsed_value)
    {
      struct header head = my_make_header_struct();
      return (Gedcom_ctxt)head;
    }

    void my_default_cb(Gedcom_elt elt, Gedcom_ctxt parent, int level,
                       char* tag, char* raw_value, int parsed_tag)
    {
      struct header head = (struct header)parent;
      my_header_add_to_extra_text(head, level, tag, raw_value);
    }

    gedcom_set_default_callback(my_default_cb);
    gedcom_subscribe_to_record(REC_HEAD, my_header_start, NULL);
    ...
    result = gedcom_parse_file(filename);
  \endcode

  Note that the default callback will be called for any tag that isn't
  specifically subscribed upon by the application, and can thus be called in
  various contexts.  For simplicity, the example above doesn't take this into
  account (the parent could be of different types, depending on the context).

  Note also that the default callback is not called when the parent context is
  \c NULL.  This is e.g. the case if none of the "upper" tags has been
  subscribed upon.
*/

/*! \defgroup parsed Parsed values
    \ingroup callback

  The \c Gedcom_val type is meant to be an opaque type.  The only thing that
  needs to be known about it is that it can contains specific data types, which
  have to be retrieved from it using pre-defined macros.

  Currently, the specific \c Gedcom_val types are (with \c val of type
  \c Gedcom_val):
  
  <table border="1" width="100%">
    <tr>
      <td>&nbsp;</td>
      <td><b>type checker</b></td>
      <td><b>cast function</b></td>
    </tr>
    <tr>
      <td>null value</td>
      <td><code>GEDCOM_IS_NULL(val)</code></td>
      <td>N/A</td>
    </tr>
    <tr>
      <td>string</td>
      <td><code>GEDCOM_IS_STRING(val)</code></td>
      <td><code>char* str = GEDCOM_STRING(val);</code></td>
    </tr>
    <tr>
      <td>date</td>
      <td><code>GEDCOM_IS_DATE(val)</code></td>
      <td><code>struct date_value dv = GEDCOM_DATE(val);</code></td>
    </tr>
    <tr>
      <td>age</td>
      <td><code>GEDCOM_IS_AGE(val)</code></td>
      <td><code>struct age_value age = GEDCOM_AGE(val);</code></td>
    </tr>
    <tr>
      <td>xref pointer</td>
      <td><code>GEDCOM_IS_XREF_PTR(val)</code></td>
      <td><code>struct xref_value *xr = GEDCOM_XREF_PTR(val);</code></td>
    </tr>
  </table>

  The type checker returns a true or a false value according to the type of
  the value, but this is in principle only necessary in the rare circumstances
  that two types are possible, or where an optional value can be provided.
  In most cases, the type is fixed for a specific tag.

  The exact type per tag can be found in the
  <a href="interface.html">interface details</a>.

  The null value is used for when the GEDCOM spec doesn't allow a value, or
  when an optional value is allowed but none is given.
 
  The string value is the most general used value currently, for all those
  values that don't have a more specific meaning.  In essence, the value that
  is returned by \c GEDCOM_STRING(val) is always the same as the \c raw_value
  passed to the start callback, and is thus in fact redundant.

  For the other data types, there is a specific section giving details.
*/

/*! \defgroup parsed_date Date values
    \ingroup parsed

  The Gedcom_val contains a struct date_value if it denotes a date.  The
  struct date is a part of the struct date_value.
*/

/*! \defgroup parsed_age Age values
    \ingroup parsed

  The Gedcom_val contains a struct age_value if it denotes an age.
*/

/*! \defgroup parsed_xref Cross-reference values
    \ingroup parsed

  The Gedcom_val contains a pointer to a struct xref_value if it denotes a
  cross-reference (note: not the struct itself, but a pointer to it !)
  
  The parser checks whether all cross-references that are used are defined
  (if not, an error is produced) and whether all cross-references that are
  defined are used (if not, a warning is produced).  It also checks whether
  the type of the cross-reference is the same on definition and use (if
  not, an error is produced).

  The first two checks are done at the end of
  the parsing, because cross-references can be defined after their usage
  in GEDCOM.

  A cross-reference key must be a string of maximum 22 characters, of the
  following format:

   - an at sign ('@')
   - followed by an alphanumeric character (A-Z, a-z, 0-9 or underscore)
   - followed by zero or more characters, which can be any character
     except an at sign
   - terminated by an at sign ('@')

  An example would thus be: <code>"@This is an xref_val@"</code>.
*/

/*! \defgroup compat Compatibility mode
    \ingroup callback

  Applications are not necessarily true to the GEDCOM spec (or use a different
  version than 5.5).  The intention is that the library is resilient to this,
  and goes in compatibility mode for files written by specific programs
  (detected via the \c HEAD.SOUR tag).

  Currently, there is (some) compatibility for:
    - ftree
    - Lifelines (3.0.2)
    - Personal Ancestral File (PAF), version 2, 4 and 5
    - Family Origins
    - EasyTree
*/

/*! \defgroup write Support for writing GEDCOM files
    \ingroup callback

  The Gedcom parser library also contains functions to writing GEDCOM files.
  Similar as for the parsing itself, there are two interfaces: an interface
  which is very basic, and requires you to call a function for each line in
  the GEDCOM file, and an interface which just dumps the Gedcom object model
  to a file in one shot (if you use the Gedcom object model).

  Again, this section focuses on the basic interface, the Gedcom object model
  interface is described \ref gom "here".

  Writing a GEDCOM file involves the following steps:

   - first set the encoding options as you want them using
     gedcom_write_set_encoding() and gedcom_write_set_line_terminator()\n\n
     By default a file is written in the same encoding as the last read file
     was in, and the terminator is set to the appropriate one on the current
     platform.
     
   - open the file using gedcom_write_open()
   
   - write the date using gedcom_write_record_str(), ...\n\n
     The principle is that every line in the GEDCOM file to write corresponds
     to a call of one of these functions, except that \c CONT/CONC lines can
     be automatically taken care of.\n\n
     Note that the result GEDCOM file should conform to the GEDCOM standard.
     Several checks are built in already, and more will follow, to force this.
     There is no compatibility mode for writing GEDCOM file (and probably never
     will be).\n\n
     All these functions expect their input in UTF-8 encoding.  If this is
     not the case, errors will be returned.  Note that for examples of using
     these functions, you can look at the sources of the Gedcom object model
     (e.g. the function \c write_header in \c gom/header.c).

   - close the file using gedcom_write_close()
*/

/*! \defgroup debug Debugging
    \ingroup callback

  The library can generate various debugging output, not only from itself, but
  also the debugging output generated by the yacc parser.  By default, no
  debugging output is generated, but this can be changed.
*/

/*! \defgroup devel Development support
  \section configure Macro 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:
  \code
    AM_PATH_GEDCOM_PARSER([min_version,[action_if_found,[action_if_not_found,[modules]]]])
  \endcode

  All the arguments are optional and default to 0.  E.g. to check for version
  1.34.2, you would put in configure.in the following statement:
  \code
    AM_PATH_GEDCOM_PARSER(1.34.2)
  \endcode

  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).

  The macro also sets the variables GEDCOM_CFLAGS and GEDCOM_LIBS for use in
  Makefiles.  Typically, this would be done as follows in a Makefile.am:
  \code
    bin_programs   = myprg
    myprg_SOURCES  = myprg.c foo.c bar.c
    INCLUDES       = @GEDCOM_CFLAGS@
    LDADD          = @GEDCOM_LIBS@
  \endcode

  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 is gom (the Gedcom object model).  For
  example:
  \code
    AM_PATH_GEDCOM_PARSER(0.21.2, , ,gom)
  \endcode

  To be able to use this macro in the sources of your application, you have
  three options:

   - Put the file \c m4/gedcom.m4 in your autoconf data directory (i.e. the
     path given by <code>'aclocal --print-ac-dir'</code>, usually
     <code>/usr/share/aclocal)</code>.  You can
     do this automatically by going into the m4 subdirectory and typing
     <code>'make install-m4'</code>.

   - If you're using autoconf, but not automake, copy the contents of
     \c m4/gedcom.m4 in the \c aclocal.m4 file in your sources.

   - If you're using automake, copy the contents of \c m4/gedcom.m4 in the
     \c acinclude.m4 file in your sources.

  \section flags Compilation and linking flags

  Similar to other libraries, the GEDCOM parse library installs a script
  \c gedcom-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):
  \code
    gedcom-config --cflags
    gedcom-config --cflags gom
  \endcode

  Similarly, to get linking flags, use one of the following:
  \code
    gedcom-config --libs
    gedcom-config --libs gom
  \endcode
 */

/*! \defgroup gom Gedcom Object Model in C */

/*! \defgroup gommain Main functions of the object model
    \ingroup gom

  Programs using the Gedcom object model in C should use the following
  (inclusion of
  both the \c gedcom.h and \c gom.h headers is required; contrast this with
  the example given for the \ref maingedcom "callback parser"):

  \code
  int result;
  ...
  gedcom_init();
  ...
  result = gom_parse_file("myfamily.ged");
  \endcode

  In the Gedcom object model, all the data is immediately available after
  calling gom_parse_file().  For this, an entire model based on C structs
  is used.  These structs are documented
  <a href=gomxref.html>here</a>, and follow the GEDCOM syntax quite closely.
  Each of the records in a GEDCOM file is modelled by a separate struct, and
  some common sub-structures have their own struct definition.

  The next sections describe the functions to be used to get at these structs.
*/

/*! \defgroup gomget Retrieving information in the object model
  \ingroup gom

  \section gomget_basic Basic retrieval

  The functions documented in this section allow to retrieve the objects
  from the object model:

   - First, there are two functions to get the header record and the submission
     record (there can be only one of them in a GEDCOM file):
     \code
       struct header*      gom_get_header();
       struct submission*  gom_get_submission();
     \endcode

   - Further, for each of the other records, there are two functions, one to
     get the first of such records, and one to get a record via its
     cross-reference tag in the GEDCOM file:
     \code
       struct XXX*   gom_get_first_XXX();
       struct XXX*   gom_get_XXX_by_xref(const char* xref);
     \endcode

     The XXX stands for one of the following: family, individual, multimedia,
     note, repository, source, submitter, user_rec.

     Note that the structs are documented <a href=gomxref.html>here</a>.

  \section gomget_obj_list Object lists

  All records of a certain type are linked together in a linked list.  The
  above functions only give access to the first record of each linked list.
  The others can be accessed by traversing the linked list via the \c next
  member of the structs.  This means that e.g. the following piece of code will
  traverse the linked list of family records:
  \code
    struct family* fam;

    for (fam = gom_get_first_family() ; fam ; fam = fam->next) {
      ...
    }
  \endcode

  The \c next member of the last element in the list is guaranteed to have the
  \c NULL value.

  Actually, the linked list is a doubly-linked list: each record also has a
  \c previous member.  But for implementation reasons the behaviour of this
  \c previous member on the edges of the linked list will not be guaranteed,
  i.e. it can be circular or terminated with \c NULL, no assumptions can be
  made in the application code.

  This linked-list model applies also to all sub-structures of the main record
  structs, i.e. each struct that has a \c next and \c previous member follows
  the above conventions.  This means that the following piece of code
  traverses all children of a family (see the details of the different
  structs <a href=gomxref.html>here</a>):
  \code
    struct family* fam = ...;

    struct xref_list* xrl;
    for (xrl = fam->children ; xrl ; xrl = xrl->next) {
      ...
    } 
  \endcode

  Note that all character strings in the object model are encoded in UTF-8
  (<a href=encoding.html>Why UTF-8?</a>), but see \ref gom_mod_string "further"
  for how to
  convert these automatically.

  All structs and sub-structures are documented <a href=gomxref.html>here</a>.

  \section gomget_user User data

  Each of the structs has an extra member called \c 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:
    - a level: the level number in the GEDCOM file
    - a tag: the tag given in the GEDCOM file
    - a value: the value, which can be a string value or a cross-reference
      value (one of the two will be non-NULL)

  This way, none of the information in the GEDCOM file is lost, even the
  non-standard information.
*/

/*! \defgroup gom_modify Modifying the object model
   \ingroup gom
*/

/*! \defgroup gom_mod_string Manipulating strings
   \ingroup gom_modify

  There are some functions available to retrieve and change strings in the
  Gedcom object model, depending on whether you use UTF-8 strings in your
  application or locale-defined strings.

  The functions gom_get_string() and gom_set_string() retrieve and set the
  string in UTF-8 encoding.  The first one is in fact superfluous, because it
  just returns the data pointer, but it is there for symmetry with the
  functions given below for the locale-defined input and output.

  Examples of use of these functions would be, e.g. for retrieving and setting
  the system ID in the header:
  \code
    struct header* head = gom_get_header();
    char* oldvalue = gom_get_string(head->source.id);
    char* newvalue = "My_Gedcom_Tool";

    if (gom_set_string(&head->source.id, newvalue)) {
      printf("Modified system id from %s to %s\n", oldvalue, newvalue);
    }
  \endcode

  Next to these functions, the functions gom_get_string_for_locale() and
  gom_set_string_for_locale() retrieve and set the string in the format defined
  by the current locale.

  The use of these functions is the same as the previous ones, but e.g. in
  the "en_US" locale the string will be returned by the first function in
  the ISO-8859-1 encoding.  Conversion to and from UTF-8 for the object model
  is done on the fly.
*/

/*! \defgroup gom_add_rec Adding and deleting records
   \ingroup gom_modify

  For each of the record types, there are two functions to add and delete
  records:
  \code
    struct XXX*   gom_new_XXX(const char* xref);
    int           gom_delete_XXX(struct XXX* obj);
  \endcode

  The XXX stands for one of the following: family, individual, multimedia,
  note, repository, source, submitter, user_rec.

  For submission records, the gom_delete_submission() function has no
  parameters, because there can be only one submission record.

  When creating new records, the application is responsible for making sure
  that the mandatory fields (according to the GEDCOM spec) are filled in
  afterwards.  In a later release, there will be checks in gom_write_file()
  to missing information.

  Note that records cannot be deleted if there are still referenced (see
  gom_add_xref()): the delete function will return an error then.

  All structs and sub-structures are documented <a href=gomxref.html>here</a>.
*/

/*! \defgroup gom_add_xref Adding, deleting and moving cross-references
   \ingroup gom_modify
*/

/*! \defgroup gom_add_sub Adding, deleting and moving substructures
   \ingroup gom_modify

  For struct members that are just a single value, the following functions
  are available:
  \code
    struct XXX*   gom_set_new_XXX(struct XXX** data);
    int           gom_delete_XXX(struct XXX** data);
  \endcode

  This is the case for XXX equal to address, change_date or place.  The first
  function creates a new substructure and assigns it to \c data.  The fields
  in the substructure still need to be filled in by the application.  The
  second function deletes the value from \c data.

  Note that for change_date structs there is the gom_update_timestamp()
  short-cut function, which updates the time and date directly.

  For struct members that are a list (as described
  \ref gomget_obj_list "here"), the following functions are available:
  \code
    struct XXX*   gom_add_new_XXX(struct XXX** data);
    int           gom_remove_XXX(struct XXX** data, struct XXX* obj);
    int           gom_move_XXX(Gom_direction dir, struct XXX** data, struct XXX* obj);
  \endcode

  This is the case for all XXX sub-structs that have a \c next and \c previous
  member.

  The first function creates a new substructure and adds it to the end of the
  \c data list.  The second function deletes the object from the \c data list
  if present (if not present, an error is generated and 1 is returned).

  The third function moves the given \c obj up or down the \c data list,
  depending on the \c dir parameter, similar to gom_move_xref().

  All structs and sub-structures are documented <a href=gomxref.html>here</a>.
*/

/*! \defgroup gom_write Writing the object model to file
   \ingroup gom

  Writing the current object model to a file is simply done using
  gom_write_file().  The customization functions given \ref write "here" can
  be used before gom_write_file() to control some settings.

  Before you write the file, you can update the timestamp in the header using
  the function gom_header_update_timestamp().

  Typically, this function would be used as follows, to set the current time
  in the timestamp:
  \code
    int result;
    result = gom_header_update_timestamp(time(NULL));
  \endcode
*/

/*! \defgroup gom_struct Structure definitions
   \ingroup gom

  All structs and sub-structures are documented <a href=gomxref.html>here</a>.
*/