gramps/doc/gramps.sgml

<!DOCTYPE article PUBLIC "-//GNOME//DTD DocBook PNG Variant V1.1//EN"[
<!ENTITY version "0.2.0"> <!-- replace with application version -->
]>


<!-- 
  This is a GNOME documentation template, designed by the GNOME
  Documentation Project Team. Please use it for writing GNOME
  documentation, making obvious changes. In particular, all the words
  written in UPPERCASE (with the exception of GNOME) should be
  replaced. As for "legalnotice", please leave the reference
  unchanged.

  Remember that this is a guide, rather than a perfect model to follow
  slavishly. Make your manual logical and readable.  And don't forget
  to remove these comments in your final documentation!  ;-)
-->

<!-- 
      (Do not remove this comment block.)
  Maintained by the GNOME Documentation Project
  http://developer.gnome.org/projects/gdp
  Template version: 1.0.3
  Template last modified: Nov 16, 2000
-->


<!-- =============Document Header ============================= -->

<article id="index"> <!-- please do not change the id -->

  <artheader>
    <title>gramps User Manual</title>
    <copyright>
      <year>2001</year>
      <holder>Donald N. Allingham</holder>
    </copyright>

  <!-- translators: uncomment this:

  <copyright>
   <year>2001</year>
   <holder>ME-THE-TRANSLATOR (Latin translation)</holder>
  </copyright>

   -->

  <!-- do not put authorname in the header except in copyright - use
  section "authors" below -->

  <!-- Use this legal notice for online documents which depend on -->
  <!-- core GNOME packages.                                       -->
  <legalnotice id="legalnotice">
   <para>
    Permission is granted to copy, distribute and/or modify this document
    under the terms of the <ulink type="help" 
    url="gnome-help:fdl"><citetitle>GNU Free Documentation
    License</citetitle></ulink>, Version 1.1 or any later version 
    published by the Free Software Foundation with no Invariant Sections, 
    no Front-Cover Texts, and no Back-Cover Texts.  A copy of the license
    can be found <ulink type="help" url="gnome-help:fdl">here</ulink>.
   </para>
   <para>
    Many of the names used by companies to distinguish their products and
    services are claimed as trademarks. Where those names appear in any
    GNOME documentation, and those trademarks are made aware to the members
    of the GNOME Documentation Project, the names have been printed in caps
    or initial caps.
   </para>
  </legalnotice>

  <!-- Use this legal notice for documents which are placed on  -->
  <!-- the web, shipped in any way other than online documents  -->
  <!-- (eg. PS, PDF, or RTF), or which do not depend on the     -->
  <!-- core GNOME distribution.                                 -->
  <!--                                                          -->
  <!-- If you use this version, you must place the following    -->
  <!-- line in the document declaration at the top of your      -->
  <!-- document:                                                -->
  <!--   <!ENTITY FDL SYSTEM "fdl.sgml">                        -->
  <!-- and the following line at the bottom of your document    -->
  <!-- after the last </sect1>.                                 -->
  <!--   &FDL;                                                  -->
  <!--
  <legalnotice id="legalnotice">
   <para>
    Permission is granted to copy, distribute and/or modify this document
    under the terms of the <link linkend="fdl"><citetitle>GNU
    Free Documentation License</citetitle></link>, Version 1.1 or any later
    version published by the Free Software Foundation with no Invariant
    Sections, no Front-Cover Texts, and no Back-Cover Texts.  A copy of the
    license can be found in <xref linkend="fdl">.
   </para>
   <para>
    Many of the names used by companies to distinguish their products and
    services are claimed as trademarks. Where those names appear in any
    GNOME documentation, and those trademarks are made aware to the members
    of the GNOME Documentation Project, the names have been printed in caps
    or initial caps.
   </para>
  </legalnotice>
  -->

  <!-- This is the manual version, not application version. --> 
    <releaseinfo>
       This is version 1.0 of the gramps manual.
    </releaseinfo>

  </artheader>

 <!-- ============= Document Body ============================= -->

 <!-- ============= Introduction ============================== -->
  <sect1 id="intro">
    <title>Introduction</title>

    <para>
    gramps is an acronym for the Genealogical Research and Analysis
    Management Programming System.  It was conceived under the concept
    that most genealogy programs were designed to provide the
    researcher the capability to input information related to a
    particular family tree.  Most of these programs have allowed for
    the arranging and storing of information consistent with the
    GEDCOM standards.  They usually provide a means for displaying
    descendant or ancestral relationships by means of graphical
    displays, charts, or reports.  These may be augmented with
    pictures or other media to enhance the data.  Most provide for
    inputting data on unconnected individuals/families that may or may
    not have a relationship to the primary surname being researched.
    Various other enhancements may also be provided in the
    genealogical program that allows for different degrees of
    importing and exporting data from other programs and printing of
    the data contained in the various reports.  gramps, on the other
    hand, attempts to provide all of the common capabilities of these
    programs, but, more importantly, to provide a capability not
    common to these programs.  This is the ability to input any bits
    and pieces of information directly into gramps and
    rearrange/manipulate any/all data events in the entire data base
    (in any order or sequence) to assist the user in doing research,
    analysis and correlation with the potential of filling
    relationship gaps.  In short, a tool that provides a way to input
    all your research into one place and do your analysis and
    correlation using the speed, power, and accuracy of your computer
    instead of pencils and unmanageable reams of paper.
    </para>
    <para>
      To run <application>gramps</application>, select
      <menuchoice>
	<guisubmenu>Programs</guisubmenu>
	<guisubmenu>Applications</guisubmenu>
	<guimenuitem>gramps</guimenuitem>
      </menuchoice>
      from the <guimenu>Main Menu</guimenu>, or type
      <command>gramps</command> on the command line.
    </para>
    <para>
      <application>gramps</application> is included in the
      <filename>gramps</filename> package, which is part of the
      GNOME desktop environment. This document describes version
      &version; of <application>gramps</application>.
    </para>
  </sect1>

 <!-- ================ Usage ================================ -->
 <!-- This section should describe basic usage of the application. -->

  <sect1 id="usage">
    <title>Using gramps</title>
    <para>
      <application>gramps</application> is a genealogy program.
      This section describes basic usage of
      <application>gramps</application>.
    </para>
  </sect1>

  <sect1 id="firsttime">
    <title>Running gramps for the first time.</title>
    <para>
      This section should discuss the start up druid.
    </para>
  </sect1>

  <sect1 id="mainwindow">
    <title>Main Window</title>
    <para>
      Starting <application>gramps</application> opens the
      <interface>Main window</interface>, shown in <xref
      linkend="mainwindow-fig">. The window is at first empty.

      <!-- ==== Figure ==== -->
      <figure id="mainwindow-fig">
        <title>gramps Main Window</title>
	<screenshot>
	  <screeninfo>gramps Main Window</screeninfo>
	  <graphic fileref="mainwin" format="PNG" srccredit="Don Allingham">
          </graphic>
	</screenshot>
      </figure>
    <!-- ==== End of Figure ==== -->
    </para>
  </sect1>

 <!-- ========= Basic Usage =========================== -->
  <sect1 id="personlist">
    <title>Person List</title>
    <para>
    The Person List window is the initial view seen on the main
    window.  It displays the name, gender, birth date, and death
    date of all individuals in the database.  At any time, you can
    return to the this view either by pressing the People button at
    the top of the screen, or by choosing the
    <menuchoice>
    <guisubmenu>View</guisubmenu>
    <guimenuitem>Person List</guimenuitem> 
    </menuchoice>
    entry from the menus.
    </para> 
    <sect2>
    <title>Selecting and Editing Individuals</title>
    <para>
    The Person List view lists the individuals in the database. A
    individual can be selected as the active person by clicking on
    an entry in the list. Once a person has been selected as the active 
    person, the person's name appears in the status bar in the lower
    left hand corner of the window.
    </para>
    <para>
    Once the active person has been selected, pressing the Edit
    Person button will display the Edit Person dialog allowing you
    to edit the individual's personal information.  If the Edit
    Person button is pressed without an active person being set, a
    blank Edit Person dialog is presented, allowing you to enter a
    new person.  Double-clicking on a entry will set the active
    person and bring up the individual in the Edit Person dialog.
    </para>
    <para>
    Pressing the Add Person button will display a blank Edit Person
    dialog, allowing you to add a new person to the database.
    </para>
    <para>
    If the Delete Person button is pressed, the active person and
    all of the personal information related to the active person are
    removed from the database.
    </para>
    </sect2>
    <sect2>
     <title>Applying Filters</title>
    <para>
    <application>gramps</application> allows you to apply filters to
    the Person List. When a filter is applied, the Person List will
    only display the entries matching the filter. All of the entries
    remain in the database, but are temporarily hidden.
    </para>
    <para>
    There are three parts to a filter. The first part is the
    selection of the filter to be applied. A filter is selected from
    the option menu directly above the Person List.  The second part
    is an option qualifier. This qualifier provides more specific
    information for the filter. Many filters do not require the
    qualifier, and it will be grayed out if not needed.  The third
    part of the filter is the invert selection.  When this option is
    selected, <application>gramps</application> will display the
    entries that do not match the filter.
    </para>
    <para>
    A filter is not applied until the Apply button is pressed.  The
    filter will remain in effect until the next time the Apply
    button is pressed.
    </para>
    </sect2>
    <sect2>
     <title>Sorting</title>
    <para>
    Four columns are shown in the Person List display. The entries in
    the list can be sorted by three of the field: Name, Birth Date, or 
    Death Date.  Clicking on the column label will cause the list to 
    be resorted by that column.  Arrows on the label indicate whether
    the list is sort by ascending or descending order. 
    </para>
    <para>
    If the list is already sorted by a particular column, clicking on
    the same column label will switch sorting order.  For example, if
    the list is currently sorted in ascending order by Name, clicking
    on the Name column header will resort the list in descending order.
    </para>
    </sect2>

  </sect1>

  <sect1 id="familyview">
    <title>Family View</title>
    <para>
    The Family View window displays the spouses, parents, and children
    of the active person. At any time, you can return to the this view
    either by pressing the Family button at the top of the screen, or
    by choosing the
    <menuchoice>
    <guisubmenu>View</guisubmenu>
    <guimenuitem>Family View</guimenuitem> 
    </menuchoice>
    entry from the menus.
    </para> 
    <para> 
    This section should describe the family view.
    </para>
  </sect1>

  <sect1 id="pedegreeview">
    <title>Pedegree View</title>
    <para>
    The Pedegree View window displays the active person, the active
    person's parents, and the active parent's grandparents in a somewhat
    graphical manner. At any time, you can return to the this view
    either by pressing the Pedegree button at the top of the screen, or
    by choosing the
    <menuchoice>
    <guisubmenu>View</guisubmenu>
    <guimenuitem>Pedgree</guimenuitem> 
    </menuchoice>
    entry from the menus.
    </para>
    <para>
    This section should describe the pedegree view.
    </para>
  </sect1>

  <sect1 id="sourcelist">
    <title>Source List</title>
    <para>
    The Source List window displays the different sources which have been
    entered into the database. At any time, you can return to the this view
    either by pressing the Sources button at the top of the screen, or
    by choosing the
    <menuchoice>
    <guisubmenu>View</guisubmenu>
    <guimenuitem>Sources</guimenuitem> 
    </menuchoice>
    entry from the menus.
    </para>
    <para>
    This section should describe the source list.
    </para>
  </sect1>

 <!-- ============= Customization ============================= -->

 <sect1 id="prefs">
  <title>Customization</title>
  <para>
   To change the application settings, select
   <menuchoice>
    <guimenu>Settings</guimenu>
    <guimenuitem>Preferences...</guimenuitem>
   </menuchoice>.  This opens the
   <interface>Preferences</interface> dialog, shown in <xref
   linkend="preferences-fig">.
  </para>

  <figure id="preferences-fig">
   <title>Preferences Dialog</title>
   <screenshot>
    <screeninfo>Preferences Dialog</screeninfo>
    <graphic fileref="preferences" format="png" srccredit="Don Allingham">
    </graphic>
   </screenshot>
  </figure>

  <para>
  </para>

 </sect1>

 <!-- ============= Generating Reports ============================= -->

 <sect1 id="genreports">
  <title>Generating Reports</title>
  <para>
  <application>gramps</application> can produce a wide variety of 
  reports. New report generators can be written by the user without
  modifying the main program. For this reason, there may be more 
  reports available than are documented by this manual
  </para>
  <para>
  Unlike many genealogy programs, <application>gramps</application>
  does not directly print reports. Instead,
  <application>gramps</application> produces reports in formats that
  are understood by other programs.  These formats include OpenOffice,
  AbiWord, PDF, and HTML, among others. This allows the generated
  reports to be modified after they are generated, stored for use
  later, or emailed to another person.
  </para>
  <sect2 id="htmltemplates">
  <title>Using HTML templates</title>
  <para>
  Many programs exist to convert GEDCOM files into HTML files that
  can be viewed in a web browser. Most of these programs generate
  HTML files according to their own predefined style. Since most
  people have a style that they prefer, they are left with the option
  of modifying hundreds of files by hand.
  </para>
  <para>
  To solve this problem, <application>gramps</application> allows the
  user to specify a template to be used for generating HTML files.  At
  the time the report is generated, if HTML is selected as the target
  format, the user can select an HTML template to be used.  Since the
  template is chosen at report generation time, a different template
  may be chosen each time, allowing the user to change the appearence
  of the generated files at any time.  Nearly any existing HTML file
  can be used as an HTML template for
  <application>gramps</application>.
  </para>
  <para>
  When a file has been established as the HTML template file,
  <application>gramps</application> uses the template for each file
  that it generates. <application>gramps</application> starts each
  file by copying data from the template until it reaches an HTML
  comment uses as a marker.  At that point,
  <application>gramps</application> inserts its data into the output
  file. <application>gramps</application> the continues reading the
  until it reaches a second comment that tells it to resume copying
  from the template.
  </para>
  <para>
  <application>gramps</application> uses the string <function>&lt;!--
  START --&gt;</function> to indicate where it should start inserting
  its information, and the string <function>&lt;!-- STOP
  --&gt;</function> to indicate where it should resume copying data
  from the template.  The effect is that
  <application>gramps</application> will create a new document,
  replacing everything between the <function>&lt;!-- START
  --&gt;</function> and <function>&lt;!-- STOP --&gt;</function> comments
  with the report information.
  </para>
  <para>
  The comment markers should be at the beginning of a line in the HTML
  template file.  Adding the comments to an existing HTML document will
  not affect the original HTML document in any way.
  </para>
  <para>
  If no HTML template is specified, or if the specified template
  cannot be read, <application>gramps</application> will use a
  default, predefined template.
  </para>
  <para>
    <figure id="templateexample">
    <title>Sample HTML Template Example</title>
    <programlisting>
&lt;HTML&gt;
&lt;HEAD&gt;
&lt;TITLE&gt;
This is my Title
&lt;/TITLE&gt;
&lt;/HEAD&gt;
&lt;BODY BGCOLOR="#FFFFFF"&gt;
&lt;P&gt;
This is a simple template.  This text will appear in the html output.
&lt;/P&gt;
&lt;!-- START --&gt;
&lt;P&gt;
This is where gramps will place its report information. Any 
information between the two comments, including this paragraph,
will not appear in the gramps generated output.
&lt;/P&gt;
&lt;!-- STOP --&gt;
&lt;P&gt;
This text, since it appears after the stop comment, will also
appear in every gramps generated file.
&lt;/P&gt;
&lt;/BODY&gt;
&lt;/HTML&gt;
    </programlisting>
    </figure>
  </para>
  </sect2>

 </sect1>

 <!-- ============= Writing Filters ============================= -->

 <sect1 id="writingfilters">
  <title>Writing Filters</title>
  <para>
   Users can create their own filters and add them to
   <application>gramps</application>.  By adding the filter to the
   user's private filter directory 
   (<filename class="directory">~/.gramps/filters</filename>), 
   the filter will be automatically
   recognized the next time that the program is started.
   </para>
   <sect2 id="createfilter">
    <title>Creating a filter</title>
    <para>
     Filters are written in the <application>python</application>
     language.  Each filter is initialized with the qualifier string.
     The qualifier string passes an additional text string to the
     filter. This string can be used to further qualify the filter.
     For example, if the filter is used to match names, the qualifier
     would be used to provide the name that is being compared against.
    </para>
    <para>
    Each filter is a python class, and should be in its own separate
    module (file). The module should consist of the filter class
    definition, and three functions &mdash;
    <function>create</function>, <function>need_qualifier</function>,
    and <function>get_name</function>.
    </para>
    <para>
    The <function>create</function> function takes a string as its
    only argument, returns a instance of the filter class. The string
    argument is the qualifier string used to provide more specific
    information.
    </para>
    <para>
    The <function>need_qualifier</function> function takes no
    arguments, and returns either a 0 or 1 to indicate if a qualifier
    string is needed by the filter. Regardless of what
    <function>need_qualifier</function> indicates, a text string is
    always passed to the filter and the <function>create</function>
    function.  The value returned by
    <function>need_qualifier</function> indicates to the program
    whether or not the qualifier field in the display should be
    enabled or disabled.
    </para>
    <para>
    The <function>get_name</function> function is used to provide a
    description for the filter. This description is entered into
    filter selection menus. If the filter is intended to be used by
    others, it should be prepared for internationalization.  This is
    accomplished by importing the <function>intl</function> module,
    add defining <function>_</function> to be
    <function>intl.gettext</function>.  The string returned by
    <function>get_name</function> should be passed through the
    <function>_</function> function to allow for conversion to the
    target langauge.
    </para>
    <para>
    All filters must be derived from the
    <function>Filter.Filter</function> class. The
    <function>__init__</function> task may be overridden, but if so,
    should call the <function>__init__</function> function on the
    <function>Filter.Filter</function> class.  The parent class
    provides the variable <function>self.text</function>, which
    contains the text string passed as the qualifier.
    </para>
    <para>
    All filter classes must define a <function>match</function>
    function. The function takes one argument (other than
    <function>self</function>), which is an object of type
    <function>Person</function> to compare against. The function
    should return a 1 if the person matches the filter, or a zero if
    the person does not.
    </para>
    <figure id="filtersrc">
    <title>Sample filter implementation</title>
    <programlisting>
import Filter
import string
import intl
_ = intl.gettext

# class definition

class SubString(Filter.Filter):

    def match(self,person):
        name = person.getPrimaryName().getName()
        return string.find(name,self.text) >= 0

# module functions

def get_name(s):
    return _("Names that contain a substring")

def create(text):
    return SubString(text)

def need_qualifier():
    return 1
    </programlisting>
    </figure>
   </sect2>
 </sect1>

 <!-- ============= Writing Reports ============================= -->

 <sect1 id="writingreports">
  <title>Writing Reports</title>
   <para>
   Users can create their own report generators and add them to
   <application>gramps</application>.  By adding the report generator
   to the user's private filter directory (<filename
   class="directory">~/.gramps/plugins</filename>), the report
   generator filter will be automatically recognized the next time
   that the program is started.
   </para>
   <sect2 id="createreport">
    <title>Creating a report generator</title>
    <para>
     Like filters, report generators are written in the
     <application>python</application> language. Fewer restrictions
     are made on report generators than on filters.  The report
     generator is passed the current <application>gramps</application>
     database and the active person.  The generator needs to take
     special care to make sure that it does not alter the database in
     anyway.
    </para>
    <para>
    The function <function>get_name</function> is used to provide the
    name of the the report generator. As with a filter definition,
    this string should support internationalization via the
    <function>intl</function> module. The returned string consists of
    two parts, separated by a forward slash.  The first part of the
    string is the category of the report generator.
    <application>gramps</application> uses this part to group similar
    reports together in the interface. The second part of the string
    is the actual name of the reprot generator, and will be displayed
    in the report menu.
    </para>
    <para>
    A report generator module must supply the
    <function>report</function> function, and can optionally define
    the <function>get_description</function> and
    <function>get_xpm_data</function> functions.  The
    <function>report</function> takes two arguments &mdash; a database
    (of type <function>RelDataBase</function>) and the currently
    selected person (of type <function>Person</function>). The
    <function>report</function> is reponsible for generating the
    actual report.
    </para>
    <para>
    If the <function>get_description</function> is defined, it is used
    to provide a more detailed description of the report. The
    description is used to provide the user with more information in
    the report selection window.  The function takes no arguments, and
    should return a text string.
    </para>
    <para>
    If the <function>get_xpm_data</function> is defined, it is used to
    provide an graphic logo for the report in the report selection
    window.  The function takes no arguments, and should return a list
    of strings containing the XPM file data.  The XPM image should be
    48x48 pixels in size.
    </para>
    <figure id="reportsrc">
    <title>Sample report implementation</title>
    <programlisting>
import intl
_ = intl.gettext

def report(database,person):
   ... actual code ...

def get_description():
    return "A detailed text description of what the report generator does"

def get_name():
    return _("Category/report name")

def get_xpm_image():
    return [
    "... XPM image data"
    ]
    </programlisting>
    </figure>
   </sect2>
   <sect2 id="alittlehelp">
    <title>A little help - Format Interfaces</title>
    <para>
    <application>gramps</application> provides some help with writing
    reports.  Several generic python classes exist that aid in the
    writing of report generators.  These classes provide an abstract
    interface for a type of document, such as a drawing, word
    processor document, or a spreadsheet.  From these core classes,
    <application>gramps</application> derives interfaces to various
    document formats.  This means that by coding to the generic word
    processing class (<function>TextDoc</function>), a report
    generator can instant access to multiple file formats (such as
    HTML, OpenOffice, and AbiWord).
    </para>
    <para>
    This scheme of deriving a output format from a generic base class
    also makes it easier to add new formats.  Creating a new
    derivied class targeting a different format (such as
    <application>KWord</application> or
    <application>LaTeX</application>) makes it easy for existing
    report generators to use the new formats.
    </para>
   </sect2>
 </sect1>

 <!-- ============= Writing Tools ============================= -->

 <sect1 id="writingtools">
  <title>Writing Tools</title>
  <para>
  </para>

 </sect1>

 <!-- ============= Various Sections ============================= -->

 <!-- Here you should add, if necessary, several more sect1's,
 describing other windows (besides the main one), file formats,
 preferences dialogs,  etc. as appropriate. Try not to make any of
 these sections too long. -->


 <!-- ============= Bugs ================================== -->
 <!-- This section should describe known bugs and limitations of
      the program if there are any - please be frank and list all
      problems you know of. -->
 <sect1 id="bugs">
  <title>Known Bugs and Limitations</title>
  <para>
   This application has no known bugs.
  </para>
 </sect1>


<!-- ============= Authors ================================ -->

 <sect1 id="authors">
  <title>Authors</title>
  <para>
   <application>gramps</application> was written by Donald N. Allingham
   (<email>donaldallingham@home.com</email>). To find more information about
   <application>gramps</application>, please visit the <ulink
   url="http://gramps.sourceforge.net" type="http">gramps Web
   page</ulink>.  
  </para>

  <para>
   This manual was written by Donald N. Allingham
   (<email>donaldallingham@home.com</email>) and Lawrence L. Allingham
   (<email>llkla@erinet.com</email>).
  </para>

  <!-- For translations: uncomment this:

  <para>
   Latin translation was done by ME
   (<email>MYNAME@MYADDRESS</email>). Please send all  comments  and
   suggestions regarding this translation to SOMEWHERE.
  </para>

  -->

 </sect1>


 <!-- ============= Application License ============================= -->

 <sect1 id="license">
  <title>License</title>
  <para>
   This program is free software; you can redistribute it and/or
   modify it under the terms of the  <ulink type="help" url="gnome-help:gpl">
    <citetitle>GNU General Public License</citetitle></ulink> as
   published by the Free Software Foundation; 
   either version 2 of the License, or (at your option) any later
   version.
  </para>
  <para>
   This program 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
   <citetitle>GNU General Public License</citetitle> for more details.
  </para>
  <para>
   A copy of the <citetitle>GNU General Public License</citetitle> is
   included as an appendix to the <citetitle>GNOME Users
   Guide</citetitle>.  You may also obtain a copy of the
   <citetitle>GNU General Public License</citetitle> from the Free
   Software Foundation by visiting <ulink type="http"
   url="http://www.fsf.org">their Web site</ulink> or by writing to
   <address>
    Free Software Foundation, Inc.
    <street>59 Temple Place</street> - Suite 330
    <city>Boston</city>, <state>MA</state> <postcode>02111-1307</postcode>
    <country>USA</country>
   </address>
  </para>
 </sect1>
</article>