From 82c71c8f5fb0c80e1ad689c320c8d9163b3495b0 Mon Sep 17 00:00:00 2001 From: Peter Verthez Date: Sun, 2 Feb 2003 14:40:05 +0000 Subject: [PATCH] Updated documentation with new features in 0.90.0. --- doc/gom.html | 76 +++++++++++++++++++++++++++++++++---- doc/interface.html | 9 +++-- doc/usage.html | 93 +++++++++++++++++++++++++++++++++++----------- 3 files changed, 146 insertions(+), 32 deletions(-) diff --git a/doc/gom.html b/doc/gom.html index 4ab405a..857e745 100644 --- a/doc/gom.html +++ b/doc/gom.html @@ -24,7 +24,12 @@
  • Modifying the object model
  • Writing the object model to file

    • @@ -73,7 +78,7 @@ struct submission*  gom_get_submission();
    to get the first of such records, and one to get a record via its cross-reference tag in the GEDCOM file:
    struct XXX*   gom_get_first_XXX();
    -struct XXX*   gom_get_XXX_by_xref(char* xref);
    +struct XXX*   gom_get_XXX_by_xref(const char* xref);
    @@ -126,11 +131,7 @@ tags is.  Each element of the linked list has:
    This way, none of the information in the GEDCOM file is lost, even the non-standard information.

    -

    Modifying the object model

    Currently, there are only functions available to modify strings in the model (and the date manipulation functions described here). - In principle it is possible to add new records, notes, ... yourself, -but you have to know what you are doing, because you should keep the model -consistent.  In the next release, functions will be available to add, -remove and modify anything in the model.
    +

    Modifying the object model

    Note that the date manipulations are described here.

    Manipulating strings

    @@ -175,6 +176,66 @@ failures for the result string.  Pass a pointer to an integer if you want to know this.  You can pass NULL if you're not interested.  The function returns NULL if an error occurred (e.g. if the given string is not a valid string for the current locale); in that case the target data variable is not modified.
    +
    +

    Adding and removing records

    +For each of the record types, there are two functions to add and remove records: +
    struct XXX*   gom_new_XXX(const char* xref);
    +int           gom_delete_XXX(struct XXX* obj);
    +
    + + +The XXX stands for one of the following: family, individual, multimedia, note, repository, source, submitter, user_rec.
    +
    +For submission records, the gom_delete_submission() has no parameters (since there can be only one such object anyway).
    +
    +When creating new records, the application is responsible for making sure +that mandatory fields (according to the GEDCOM spec) are filled in afterwards. + In a later release, there will be checks in gom_write_file when something is missing.
    +
    +

    Adding, removing and moving cross-references
    +

    +For struct members that are of type struct xref_value, the following function is available:
    +
    struct xref_value*  gom_set_xref(struct xref_value** data, const char* xref);
    +
    +This function modifies the data variable to point to the given xref, taking care of unreferencing the old value, and referencing the new value.  If an error occurs, NULL is returned (and the data variable is not changed).  If xref is NULL, the data is set to NULL.
    +
    +For struct members that are of type struct xref_list, the following functions are available:
    +
    struct xref_list*   gom_add_xref(struct xref_list** data, const char* xref);
    +int                 gom_remove_xref(struct xref_list** data, const char* xref);
    +int                 gom_move_xref(Gom_direction dir,     struct xref_list** data, const char* xref);
    +
    +The first function adds the given xref to the end of the data list.  The second function removes the given xref from the data list (if present; if not present an error is generated and 1 is returned).
    +
    +The third function moves the given xref up or down the data list, depending on the dir parameter, which can be:
    + +Again, an error is generated and 1 is returned if the given xref is not part +of the list.  If the xref cannot be moved up (because the first in the +list) or down (because the last in the list), a warning is generated, but +the function still returns success (0).
    +

    Adding, removing and moving substructures
    +

    +For struct members that are just a single value, the following functions are available:
    +
    struct XXX*   gom_set_new_XXX(struct XXX** data);
    +int           gom_delete_XXX(struct XXX** data);
    +
    +This is the case for XXX equal to address, change_date or place.  The first function creates a new substructure and assigns it to data (NULL is returned if there was already a value).  The second function deletes the value from data.
    +
    +Note: for change_date structs there is also the following short-cut function, which updates the date and time directly:
    +
    int gom_update_timestamp (struct change_date** obj, time_t tval);
    +For struct members that are a list (as described here), the following functions are available:
    +
    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);
    +
    + +This is the case for all XXX structs that have a next and previous member.  The first function creates a new substructure and adds it to the end of the data list.  The second function deletes the object from the data list (if present; if not present, an error is generated and 1 is returned).
    +
    +The third function moves the given obj up or down the data list, depending on the dir parameter, similar to the xref functions above.
    +
    +

    Writing the object model to file

    @@ -208,4 +269,5 @@ result = gom_header_update_timestamp(time(NULL));



    +
    \ No newline at end of file diff --git a/doc/interface.html b/doc/interface.html index eb3c4f0..2a90537 100644 --- a/doc/interface.html +++ b/doc/interface.html @@ -1208,7 +1208,7 @@ XREF_PTR(SUBN)
    ELT_SUB_SOUR, ELT_SUB_SOUR_TEXT

    - NULL
    STRING
    + NULL
    STRING
    NULL
    @@ -2313,7 +2313,7 @@ the value that is returned by GEDCOM_STRING(val) is always the s
    The following function creates a new date_value struct and initializes it properly, or copies an existing date value: -
    struct date_value* gedcom_new_date_value (struct date_value* copy_from);
    +
    struct date_value* gedcom_new_date_value (const struct date_value* copy_from);
    If the parameter copy_from is NULL, a new value is created and given initial values.  If it is non-NULL, the value is copied into a new date value.

    struct date
    @@ -2576,7 +2576,7 @@ The modifier can be one of the following:
  • AGE_NO_MODIFIER : no modifier
  • AGE_LESS_THAN  : the modifier '<' is added
  • AGE_GREATER_THAN : the modifier '>' is added
    • The following function creates a new age_value struct and initializes it properly, or copies an existing age value: -
    struct age_value* gedcom_new_age_value (struct age_value* copy_from);
    +
    struct age_value* gedcom_new_age_value (const struct age_value* copy_from);
    If the parameter copy_from is NULL, a new value is created and given initial values.  If it is non-NULL, the value is copied into a new age value.

    struct xref_value

    @@ -2691,4 +2691,5 @@ An example would thus be: "@This is an xref_val@".



    - +
    + \ No newline at end of file diff --git a/doc/usage.html b/doc/usage.html index 39a0cb3..a71b855 100644 --- a/doc/usage.html +++ b/doc/usage.html @@ -163,7 +163,7 @@ out of the GEDCOM file.  This section focuses on the callback mechanism 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.
    +nested calls to appropriate "start element" and "end element" callbacks (note: see 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 @@ -336,7 +336,9 @@ in the section for record callbacks above.
    - Currently, there is a beginning for compatibility for ftree and Lifelines (3.0.2).
    + Currently, there is (some) compatibility for:
    + +The following function allows to set some options for the compatibility handling:
    +
    void gedcom_set_compat_options (Gedcom_compat options)
    +
    +The parameter can be an OR'ed combination of the following options:
    + +
    +
    In some compatibility cases, tags are coming out-of-order, +i.e. their start element callback would have to come after the end element +callback of the parent tag.  E.g. instead of the standard GEDCOM
    +
    1 DATE ...
    +2 TIME ...
    +
    +the genealogy program has generated something like:
    +
    1 DATE ...
    +1 TIME ...
    +
    +This can give a problem if your end element callbacks free some resources.  
    +
    +If your program can handle elements out of context, you can enable this option. + By default it is disabled, and so the values of these out-of-context +tags are lost (the parser generates a warning if this is the case).  Note: +currently the Gedcom object model in C has this option disabled too, although +this will change in the future.
    +
    +
    +
    +

    Converting character sets

    @@ -738,4 +788,5 @@ gedcom-config --libs gom



    +
    \ No newline at end of file -- 2.30.2