gramps/doc/gramps.sgml

<!DOCTYPE article PUBLIC "-//GNOME//DTD DocBook PNG Variant V1.1//EN"[
        <!-- if not using PNG graphic, replace reference above with
             .....PUBLIC "-//OASIS//DTD DocBook V3.1//EN"[
         -->
<!ENTITY version "0.1.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>

    <!-- ========= Basic Usage =========================== -->
    <sect2 id="mainwin">
      <title>Person List</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> 
    </sect2>

    <sect2 id="familyview">
      <title>Family View</title>
      <para>
      </para>
    </sect2>

    <sect2 id="pedegreeview">
      <title>Pedegree View</title>
      <para>
      </para>
    </sect2>

    <sect2 id="enteringdata">
      <title>Entering data</title>
	<para>
        </para>
    </sect2>
  </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>
"Category/report name"

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

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

def get_xpm_image():
   return [
   "... XPM image data"
   ]
    </programlisting>
    </figure>
   </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>