<!--
	  User Manual for Gramps - a GTK+/GNOME based genealogy program

	  Copyright (C) 2003-2005  Alexander Roitman

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

	  This document 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 General Public License for more details.

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

<!-- $Id$ -->

<appendix id="faq">
  <title>Frequently Asked Questions</title>
  <para>

    This appendix contains the list of questions that frequently come
    up in mailing list discussions and forums. This list is by no
    means complete. If you would like to add questions/answers to this
    list, please email your suggestions to <ulink
    url="mailto:gramps-devel@lists.sf.net"
    type="mailto">gramps-devel@lists.sf.net</ulink>

  </para>
      
  <variablelist>
    <varlistentry>
      <term>What is &app;?</term>
      <listitem>
        <para> 
	  &app; is the Genealogical Research and Analysis Management
	  Program System. In other words, it is a personal genealogy
	  program letting you store, edit, and research genealogical
	  data using the powers of your computer.
        </para>
      </listitem>
    </varlistentry>

    <varlistentry>
      <term>Where do I get it and how much does it cost?</term>
      <listitem>
        <para> 
	  &app; can be downloaded from <ulink
	  url="http://sf.net/projects/gramps"
	  type="http">http://sf.net/projects/gramps</ulink> at no
	  charge.  &app; is an Open Source project covered by the GNU
	  General Public License.  You have full access to the source
	  code and are allowed to distribute the program and source
	  code freely.
        </para>
      </listitem>
    </varlistentry>

    <varlistentry>
      <term>Does it work with Windows (tm)?</term>
      <listitem>
        <para> 
	  No. &app; uses the GTK and GNOME libraries. While the GTK
	  libraries have been ported to Windows, the GNOME libraries
	  have not.  This, however, may change in the future.
        </para>
      </listitem>
    </varlistentry>

    <varlistentry>
      <term>Does it work with the Mac?</term>
      <listitem>
	<para> 
	  <ulink url="http://fink.sourceforge.net" type="http">
	  The Fink project</ulink> has ported 
	  <ulink url="http://fink.sourceforge.net/pdb/package.php/gramps"
	  type="http"> some older versions</ulink> of 
	  &app; to OSX (tm). The Mac OSX port is not directly supported by 
	  the &app; project, primarily because none of the &app; developers 
	  have access to Mac OSX and because OSX is not Free Software.
	</para><para>
	  This version of &app; (&appversion;) does not appear to have been 
	  ported by the Fink project. Please contact the Fink project for 
	  more information.
        </para><para>  
	  Some people have had success using the DarwinPorts instead of the
	  Fink project.
        </para>
      </listitem>
    </varlistentry> 

    <varlistentry>
      <term>Does it work with KDE?</term>
      <listitem>
	<para> 
	  Yes, as long as the required GNOME libraries are installed.
	</para>
      </listitem>
    </varlistentry>

    <varlistentry>
      <term>Do I really have to have GNOME installed?</term>
      <listitem>
        <para>
	  Yes, but you do not have to be running the GNOME desktop.
	</para>
      </listitem>
    </varlistentry>

    <varlistentry>
      <term>What version of GNOME do I need?</term>
      <listitem>
        <para> 
	  This version of gramps requires GNOME 2.8.0 or higher.
	  Previous versions in 1.0.x series required GNOME 2.0. 
        </para>
      </listitem>
    </varlistentry>

    <varlistentry>
      <term>Is &app; compatible with other genealogical software?</term>
      <listitem>
        <para> 
	  &app; makes every effort to maintain compatibility with
	  GEDCOM, the general standard of recording genealogical
	  information. We have import and export filters that enable
	  &app; to read and write GEDCOM files.
        </para><para>
	  It is important to understand that the GEDCOM standard is
	  poorly implemented -- virtually every genealogical software
	  has its own "flavor" of GEDCOM. As we learn about new
	  flavor, the import/export filters can be created very
	  quickly.  However, finding out about the unknown flavors
	  requires user feedback.  Please feel free to inform us about
	  any GEDCOM flavor not supported by &app;, and we will do our
	  best to support it!
        </para>
      </listitem>
    </varlistentry>

    <varlistentry>
      <term>Can &app; read files created by other genealogy programs?</term>
      <listitem>
        <para>See above.</para>
      </listitem>
    </varlistentry>

    <varlistentry>
      <term>Can &app; write files readable by other genealogy programs?</term>
      <listitem>
        <para>See above.</para>
      </listitem>
    </varlistentry>

    <varlistentry>
      <term>Can &app; print a genealogical tree for my family?</term>
      <listitem>
        <para> 
	  Yes. Different people have different ideas of what a
	  genealogical tree is.  Some think of it as a chart going
	  from the distant ancestor and listing all his/her
	  descendants and their families. Others think it should be a
	  chart going from the person back in time, listing the
	  ancestors and their families. Yet other people think of a
	  table, text report, etc.
        </para><para>
	  &app; can produce any of the above, and many more different
	  charts and reports. Moreover, the plugin architecture
	  enables users (you) to create their own plugins which could
	  be new reports, charts, or research tools.
        </para>
      </listitem>
    </varlistentry>

    <varlistentry>
      <term>In what formats can &app; output its reports?</term>
      <listitem>
        <para> 
	  Text reports are available in HTML, PDF, AbiWord, KWord,
	  LaTeX, RTF, and OpenOffice formats. Graphical reports
	  (charts and diagrams) are available in PostScript, PDF, SVG,
	  OpenOffice, and GraphViz formats.
        </para>
      </listitem>
    </varlistentry>

    <varlistentry>
      <term>Is &app; compatible with the Internet?</term>
      <listitem>
        <para> 
	  &app; can store web addresses and direct your browser to
	  them. It can import data that you download from the
	  Internet. It can export data that you could send over the
	  Internet. &app; is familiar with the standard file formats
	  widely used on the Internet (e.g. JPEG, PNG, and GIF images,
	  MP3, OGG, and WAV sound files, QuickTime, MPEG, and AVI
	  movie files, etc). Other than that, there is little that a
	  genealogical program can do with the Internet.
        </para>
      </listitem>
    </varlistentry>

    <varlistentry>
      <term>Can I create custom reports/filters/whatever?</term>
      <listitem>
        <para> 
	  Yes. There are many levels of customization. One is creating
	  or modifying the templates used for the reports. This gives
	  you some control over the fonts, colors, and some layout of
	  the reports. You can also use &app; controls in the report
	  dialogs to tell what contents should be used for a
	  particular report. In addition to this, you have an ability
	  to create your own filters -- this is useful in selecting
	  people based on criteria set by you. You can combine these
	  filters to create new, more complex filters.  Finally, you
	  have an option to create your own plugins. These may be new
	  reports, research tools, import/export filters, etc. This
	  assumes some knowledge of programming in Python.
        </para>
      </listitem>
    </varlistentry>

    <varlistentry>
      <term>What standards does &app; support?</term>
      <listitem>
        <para> 
	  The nice thing about standards is that there never is a
	  shortage of them. &app; is tested to support the following
	  flavors of GEDCOM: GEDCOM5.5, Brother's Keeper, Family
	  Origins, Family Tree Maker, Ftree, GeneWeb, Legacy, Personal
	  Ancestral File, Pro-Gen, Reunion, and Visual Genealogie.
        </para>
      </listitem>
    </varlistentry>

    <varlistentry>
      <term>What is the maximum database size (bytes) &app; can handle?</term>
      <listitem>
        <para> 
	  &app; has no hard limits on the size of a database that it
	  can handle.  Starting with this release, &app; no longer 
	  loads all data into memory, which allows it to work with a
	  much larger database than before.  In reality, however,
	  there are practical limits. The main limiting factors are
	  the available memory on the system and the cache size used
	  for BSDDB database access. With common memory sizes these
	  days, &app; should have no problem using databases with tens
	  of thousands of people.
        </para>
      </listitem>
    </varlistentry>

    <varlistentry>
      <term>How many people can &app; database handle?</term>
      <listitem>
        <para> 
	  We have found that on a typical system, &app; tends to bog
	  down after the database has around 150,000 people. Again,
	  this is dependent on how much memory you have.
	</para>
      </listitem>
    </varlistentry>

    <varlistentry>
      <term>Why is &app; running so slowly?</term>
      <listitem>
        <para>
	  It does not anymore! Just try out the current
	  version, &appversion;.
        </para>
      </listitem>
    </varlistentry>

    <varlistentry>
      <term>
        My database is really big. Is there a way around loading 
	all the data into memory?
      </term>
      <listitem>
        <para> 
	  Starting with this release, &app; no longer loads all data
	  into memory, which allows it to work with a much larger
	  database than before.
        </para>
      </listitem>
    </varlistentry>

    <varlistentry>
      <term>I want to rerun the Startup dialog. How do I do this?</term>
      <listitem>
        <para> 
	  &app; keeps a flag in the GNOME configuration database to
	  indicate that the startup dialog has been run. To cause
	  &app; to rerun this, the flag needs to be reset. This can be
	  done with the following command:
        </para>
        <para>
	  <command>gconftool-2 -u /apps/gramps/behavior/startup</command>
        </para>
      </listitem>
    </varlistentry>

    <varlistentry>
      <term>
        Why are non-latin characters displayed as garbage in PDF/PS
        reports?
      </term>
      <listitem>
        <para>
	  This is a limitation of the builtin fonts of PS and PDF
	  formats. To print non-latin text, use the Print...  in the
	  format selection menu of the report dialog. This will use
	  the gnome-print backend, which supports PS and PDF creation,
	  as well as direct printing.
	</para>
        <para>
	  If you only have latin text, the PDF option will produce a
	  smalled PDF compared to that created by gnome-print, simply
	  because no font information will be embedded.
        </para>
      </listitem>
    </varlistentry>

    <varlistentry>
      <term>
        Why can I not add/remove/edit columns to the lists in People
	View and Family View?
      </term>
      <listitem>
        <para>
	  Now you can! Just try out the current version, &appversion;.
	</para>
      </listitem>
    </varlistentry>

    <varlistentry>
      <term>
        I would like to contribute to &app; by writing my favorite
        report. How do I do that?
      </term>
      <listitem>
        <para> 
	  The easiest way to contribute to reports, filters, tools,
	  etc. is to copy an existing &app; report, filter, or
	  tool. If you can create what you want by modifying existing
	  code -- great! If your idea does not fit into the logic of
	  any existing &app; tool, the <ulink
	  url="http://gramps.sourceforge.net/phpwiki/index.php/GrampsDevelopersPage"
	  type="http">following page</ulink> may provide some help in
	  writing your own plugin from scratch.
        </para> 
        <para> 
	  If you need more help or would like to discuss your idea
	  with us, please do not hesitate to contact us at <ulink
	  url="mailto:gramps-devel@lists.sf.net"
	  type="mailto">gramps-devel@lists.sf.net</ulink>
        </para>
	<para>
	  To test your work in progress, you may save your plugin
	  under <replaceable>$HOME/.gramps/plugins</replaceable>
	  directory and it should be found and imported on startup.
	  The correctly written plugin will register itself with
	  &app;, create menu item, and so on.
        </para>
        <para>
	  If you are happy with your plugin and would like to
	  contribute your code back to the &app; project, you are very
	  welcome to do so by contacting us at <ulink
	  url="mailto:gramps-devel@lists.sf.net"
	  type="mailto">gramps-devel@lists.sf.net</ulink>
        </para>
      </listitem>
    </varlistentry>

    <varlistentry>
      <term>
        I found a bug and I want it fixed right now!  What do I do?
      </term>
      <listitem>
        <para> 
	  The best thing you can do is to fix the bug and send the
	  patch to <ulink url="mailto:gramps-devel@lists.sf.net"
	  type="mailto">gramps-devel@lists.sf.net</ulink> :-)
        </para>
	<para>A good bug report would include:</para>
	<itemizedlist>
	  <listitem>
	    <para>   
	      Version of gramps you were using when you encountered
	      the bug (available through
	      <menuchoice><guisubmenu>Help</guisubmenu>
	      <guimenuitem>About</guimenuitem></menuchoice> menu
	      item).
	    </para>
	  </listitem>
	  <listitem>
	    <para>
	      Language under which gramps was run (available by executing 
	    </para>
	    <para><command>echo $LANG</command></para>
	    <para>in your terminal).</para>
	  </listitem>
	  <listitem>
	    <para>Symptoms indicating that this is indeed a bug.</para>
	  </listitem>
	  <listitem>
	    <para>
	      Any Traceback messages, error messages, warnings, etc,
	      that showed up in your terminal or a in separate
	      traceback window.
	    </para>
	  </listitem>
	</itemizedlist>
	<para>
	  Most problems can be fixed quickly provided there is enough
	  information.  To ensure this, please follow up on your bug
	  reports. In particular, if you file a bug report with sf.net
	  bug tracker, PLEASE log in to sf.net before filing (register
	  your free account if you don't have one). Then we will have
	  a way of contacting you should we need more information. If
	  you choose to file your report anonymously, at least check
	  every so often whether your report page has something new
	  posted, as it probably would.
	</para>
	<para>
	  If the above explanations seem vague, please follow <ulink
	  url="http://www.chiark.greenend.org.uk/~sgtatham/bugs.html"
	  type="http">this link.</ulink>
        </para>
      </listitem>
    </varlistentry>

    <varlistentry>
      <term>
        It is obvious that &app; absolutely needs to become a
	(client-server/web-based/PHP/weblog/Javascript/C++/distributed/KDE/Motif/Tcl/Win32/C#/You-name-it)
	application. When is this going to happen?
      </term>
      <listitem>
        <para> 
	  The surest way to see it happen is to get it done by
	  yourself. Since &app; is free/open source, nobody prevents
	  you from taking all of the code and continuing its
	  development in whatever direction you see fit.  In doing so,
	  you may consider giving your new project another name to
	  avoid confusion with the continuing &app; development. If
	  you would like the &app; project to provide advice,
	  expertise, filters, etc., we will gladly cooperate with your
	  new project, to ensure compatibility or import/export
	  options to your new format of a project.
        </para>
	<para>                                                                                
	  If, however, you would like the &app; project to to adopt
	  your strategy, you would need to convince &app; developers
	  that your strategy is good for &app; and superior to the
	  present development strategy.
	</para>
      </listitem>
    </varlistentry>
  </variablelist>
</appendix>
