gramps/help/C/filtref.xml

<appendix id="append-filtref">

<!--
	  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$ -->

      <title>Filter rules reference</title>
      <para>This appendix lists of all the filter rules currently defined 
      in &app;. Each of these rules is available for use when creating custom 
      filters, see <xref linkend="tools-util-cfe"/>. The rules are
      listed by their categories. 
      </para>

        <!-- =============== Appendices Sub-subsection ================ -->
    	<sect1 id="filtref-general">
        <title>General filters</title>
        <para>This category includes the following most general rules:</para>
        
          <variablelist>

          <varlistentry><term>Has complete record</term>
          <listitem><para> This rule matches all people whose records are 
          marked as complete. Currently, the completeness of personal 
          information is marked manually, in the <guilabel>Edit Person</guilabel> 
          dialog. 
          </para></listitem>
          </varlistentry>

          <varlistentry><term>People with incomplete names</term>
          <listitem><para> This rule matches all people with either
          given name or family name missing.
          </para></listitem>
          </varlistentry>

          <varlistentry><term>Is bookmarked person</term>
          <listitem><para> This rule matches all people who are on the
          bookmark list.
          </para></listitem>
          </varlistentry>

          <varlistentry><term>Has text matching substring of</term>
          <listitem><para> This rule matches all people whose records contain
          specified substring. All textual records are searched. Optionally,
          the search can be made case sensitive, or a regular expression 
          match.
          </para></listitem>
          </varlistentry>

          <varlistentry><term>Everyone</term>
          <listitem><para> This rule matches any person in the database.
          As such it is not very useful on its own except for testing purposes.
          However, it may be useful in combinations with other rules. 
          </para></listitem>
          </varlistentry>

          <varlistentry><term>People probably alive</term>
          <listitem><para> This rule matches all people whose records do
          not indicate their death and who are not unreasonably old,
          judging by their available birth data and today's date.
          </para></listitem>
          </varlistentry>

          <varlistentry><term>Has a name</term>
          <listitem><para> This rule matches any person whose name 
          matches the specified value in full or in part. For example, 
          Marta Ericsdotter will be matched by the rule using the 
          value "eric" for the family name. 
          </para>

          <para> Separate values can be used for Given name, Family name, 
          Suffix, and the Title. The rule returns a match if, and only if, 
          all non-empty values are (partially) matched by a person's 
          name. To use just one value, leave the other values empty. 
          </para></listitem>
          </varlistentry>

          <varlistentry><term>Has the Id</term>
          <listitem><para> This rule matches any person with a specified
          &app; ID. The rule returns a match only if the ID is matched 
          exactly. 
          </para>

          <para> You can either enter the ID into a text entry field, or 
          select a person from the list by clicking 
          <guibutton>Select...</guibutton> button. In the latter case, the 
          ID will appear in the text field after the selection was made. 
          </para></listitem>
          </varlistentry>

          <varlistentry><term>Is default person</term>
          <listitem><para> This rule matches the default (home) person. 
          </para></listitem>
          </varlistentry>

          <varlistentry><term>People marked private</term>
          <listitem><para> This rule matches people whose records are marked
          as private.
          </para></listitem>
          </varlistentry>

          <varlistentry><term>Is a female</term>
          <listitem><para> This rule matches any female person. 
          </para></listitem>
          </varlistentry>

          <varlistentry><term>People who have images</term>
          <listitem><para> This rule matches people with images in their
          galleries.
          </para></listitem>
          </varlistentry>

          <varlistentry><term>People without a birth date</term>
          <listitem><para> This rule matches people missing birth date.
          </para></listitem>
          </varlistentry>

          <varlistentry><term>Is a male</term>
          <listitem><para> This rule matches any male person. 
          </para></listitem>
          </varlistentry>

          </variablelist>

        </sect1> 

        <!-- =============== Appendices Sub-subsection ================ -->
    	<sect1 id="filtref-event">
        <title>Event filters</title>
        <para>This category includes the following rules that match people
        based on their recorded events:</para>
          <variablelist>

          <varlistentry><term>Has the birth</term>
          <listitem><para> This rule matches people whose birth event 
          matches specified values for Date, Place, and Description. 
          The rule returns a match even if the person's birth event matches 
          the value partially. The matching rules are case-insensitive. 
          For example, anyone born in Sweden will be matched by the rule 
          using the value "sw" for the Place. 
          </para>

          <para> The rule returns a match if, and only if, 
          all non-empty values are (partially) matched by a person's 
          birth. To use just one value, leave the other values empty. 
          </para></listitem>
          </varlistentry>

          <varlistentry><term>Has the death</term>
          <listitem><para> This rule matches people whose death event 
          matches specified values for Date, Place, and Description. 
          The rule returns a match even if the person's death event 
          matches the value partially. The matching rules are case-insensitive. 
          For example, anyone who died in Sweden
          will be matched by the rule using the value "sw" for the Place.
          </para>

          <para> The rule returns a match if, and only if, 
          all non-empty values are (partially) matched by a person's 
          death. To use just one value, leave the other values empty. 
          </para></listitem>
          </varlistentry>

          <varlistentry><term>Has source of</term>
          <listitem><para> This rule matches people whose records refer
          to the specified source.
          </para></listitem>
          </varlistentry>

          <varlistentry><term>Has the personal event</term>
          <listitem><para> This rule matches people that have a personal 
          event matching specified values for the Event type, Date, Place, 
          and Description. The rule returns a match even if the person's 
          event matches the value partially. The matching rules are 
          case-insensitive. For example, anyone who graduated 
          in Sweden will be matched by the rule using the Graduation event 
          and the value "sw" for the Place.
          </para>

          <para> The personal events should be selected from a pull-down menu. 
          The rule returns a match if, and only if, all non-empty values 
          are (partially) matched by the personal event. 
          To use just one value, leave the other values empty. 
          </para></listitem>
          </varlistentry>

          <varlistentry><term>Has the family event</term>
          <listitem><para> This rule matches people that have a family 
          event matching specified values for the Event type, Date, Place, 
          and Description. The rule returns a match even if the person's 
          event matches the value partially. The matching rules are 
          case-insensitive. For example, anyone who was married in Sweden 
          will be matched by the rule using the Marriage event and the 
          value "sw" for the Place. 
          </para>

          <para> The family events should be selected from a pull-down menu. 
          The rule returns a match if, and only if, all non-empty values 
          are (partially) matched by the personal event. 
          To use just one value, leave the other values empty. 
          </para></listitem>
          </varlistentry>

          <varlistentry><term>Witness</term>
          <listitem><para> This rule matches people who are present as
          a witness in the event. If the personal or family event type is
          specified, only the events of this type will be searched.
          </para></listitem>
          </varlistentry>

          <varlistentry><term>People with incomplete events</term>
          <listitem><para> This rule matches people missing date or place in
          any personal event.
          </para></listitem>
          </varlistentry>

          <varlistentry><term>Families with incomplete events</term>
          <listitem><para> This rule matches people missing date or place in
          any family event of any of their families.
          </para></listitem>
          </varlistentry>

          </variablelist>
        </sect1> 

        <!-- =============== Appendices Sub-subsection ================ -->
    	<sect1 id="filtref-family">
        <title>Family filters</title>
        <para>This category includes the following rules that match people 
        based on their family relationships:</para>
          <variablelist>

          <varlistentry><term>People with children</term>
          <listitem><para> This rule matches people with children.
          </para></listitem>
          </varlistentry>

          <varlistentry><term>People with multiple marriage records</term>
          <listitem><para> This rule matches people with more than one spouse.
          </para></listitem>
          </varlistentry>

          <varlistentry><term>People with no marriage records</term>
          <listitem><para> This rule matches people with no spouses.
          </para></listitem>
          </varlistentry>

          <varlistentry><term>People who were adopted</term>
          <listitem><para> This rule matches adopted people.
          </para></listitem>
          </varlistentry>

          <varlistentry><term>Has the relationships</term>
          <listitem><para> This rule matches people with a particular 
          relationship. The relationship must match the type selected from 
          the menu. Optionally, the number of relationships and the number 
          of children can be specified. 
          </para>

          <para> The rule returns a match if, and only if, 
          all non-empty values are (partially) matched by a person's 
          relationship. To use just one value, leave the other values empty. 
          </para></listitem>
          </varlistentry>

          <varlistentry><term>Is spouse of filter match</term>
          <listitem><para> This rule matches people married to someone 
          who is matched by the specified filter. 
          The specified filter name should be selected from the menu. 
          </para></listitem>
          </varlistentry>

          <varlistentry><term>Is a child of filter match</term>
          <listitem><para> This rule matches people for whom either parent  
          is matched by the specified filter. 
          The specified filter name should be selected from the menu. 
          </para></listitem>
          </varlistentry>

          <varlistentry><term>Is a parent of filter match</term>
          <listitem><para> This rule matches people whose child  
          is matched by the specified filter. 
          The specified filter name should be selected from the menu. 
          </para></listitem>
          </varlistentry>

          <varlistentry><term>Is a sibling of filter match</term>
          <listitem><para> This rule matches people whose sibling  
          is matched by the specified filter. 
          The specified filter name should be selected from the menu. 
          </para></listitem>
          </varlistentry>

          </variablelist>
        </sect1> 

        <!-- =============== Appendices Sub-subsection ================ -->
    	<sect1 id="filtref-ancestral">
        <title>Ancestral filters</title>
        <para>This category includes the following rules that match people 
        based on their ancestral relations to other people:</para>
          <variablelist>

          <varlistentry><term>Is an ancestor of</term>
          <listitem><para> This rule matches people who are ancestors of the 
          specified person. The Inclusive option determines whether the 
          specified person should be considered his/her own ancestor (useful 
          for building reports). 
          </para>

          <para> You can either enter the ID into a text entry field, or 
          select a person from the list by clicking 
          <guibutton>Select...</guibutton> button. In the latter case, the 
          ID will appear in the text field after the selection was made.
          </para></listitem>
          </varlistentry>

          <varlistentry><term>Is an ancestor of person at 
          least N generations away</term>
          <listitem><para> This rule matches people who are ancestors of the 
          specified person and are at least N generations away from that person 
          in their lineage. For example, using this rule with the value of 2 
          for the number of generations will match grandparents, 
          great-grandparents, etc., but not the parents of the specified 
          person. 
          </para></listitem>
          </varlistentry>

          <varlistentry><term>Is an ancestor of person not more 
          than N generations away</term>
          <listitem><para> This rule matches people who are ancestors of the 
          specified person and are no more than N generations away from that 
          person in their lineage. For example, using this rule with the value 
          of 2 for the number of generations will match parents and 
          grandparents, but not great-grandparents, etc., of the specified 
          person. 
          </para></listitem>
          </varlistentry>

          <varlistentry><term>Has a common ancestor with</term>
          <listitem><para> This rule matches people who have common ancestors 
          with the specified person. 
          </para></listitem>
          </varlistentry>

          <varlistentry><term>Has a common ancestor with filter match</term>
          <listitem><para> This rule matches people who have common ancestors 
          with someone who is matched by the specified filter.
          The specified filter name should be selected from the menu. 
          </para></listitem>
          </varlistentry>

          <varlistentry><term>Is an ancestor of filter match</term>
          <listitem><para> This rule matches people who are ancestors 
          of someone who is matched by the specified filter.
          The specified filter name should be selected from the menu. 
          </para></listitem>
          </varlistentry>

          </variablelist>
        </sect1> 

        <!-- =============== Appendices Sub-subsection ================ -->
    	<sect1 id="filtref-descendant">
        <title>Descendant filters</title>
        <para>This category includes the following rules that match people 
        based on their descendant relations to other people:</para>
          <variablelist>

          <varlistentry><term>Is a descendant of</term>
          <listitem><para> This rule matches people who are descendants of the 
          specified person. The Inclusive option determines whether the 
          specified person should be considered his/her own descendant (useful 
          for building reports). 
          </para>

          <para> You can either enter the ID into a text entry field, or 
          select a person from the list by clicking 
          <guibutton>Select...</guibutton> button. In the latter case, the 
          ID will appear in the text field after the selection was made.
          </para></listitem>
          </varlistentry>

          <varlistentry><term>Is a descendant of person at 
          least N generations away</term>
          <listitem><para> This rule matches people who are descendants of the 
          specified person and are at least N generations away from that person 
          in their lineage. For example, using this rule with the value of 2 
          for the number of generations will match grandchildren, 
          great-grandchildren, etc., but not the children of the specified 
          person.
          </para></listitem>
          </varlistentry>

          <varlistentry><term>Is a descendant of person not more 
          than N generations away</term>
          <listitem><para> This rule matches people who are descendants of the 
          specified person and are no more than N generations away from that 
          person in their lineage. For example, using this rule with the value 
          of 2 for the number of generations will match children and 
          grandchildren, but not great-grandchildren, etc., of the specified 
          person. 
          </para></listitem>
          </varlistentry>

          <varlistentry><term>Is a descendant of filter match</term>
          <listitem><para> This rule matches people who are descendants 
          of someone who is matched by the specified filter.
          The specified filter name should be selected from the menu. 
          </para></listitem>
          </varlistentry>

          <varlistentry><term>Is a descendant family member of</term>
          <listitem><para> This rule not only matches people who are 
          descendants of the specified person, but also those descendants' 
          spouses.
          </para></listitem>
          </varlistentry>

          </variablelist>
        </sect1> 

        <!-- =============== Appendices Sub-subsection ================ -->
    	<sect1 id="filtref-relat">
        <title>Relationship filters</title>
        <para>This category includes the following rules that match people
        based on their mutual relationship:</para>
          <variablelist>

          <varlistentry><term>Relationship path between two people</term>
          <listitem><para> This rule matches all ancestors of both people
          back to their common ancestors (if exist). This produces the 
          &quot;relationship path&quot; between these two people, through
          their common ancestors. 
          </para>
          
          <para> You can either enter the ID of each person into the 
          appropriate text entry fields, or select people from the list by 
          clicking their <guibutton>Select...</guibutton> buttons. In the 
          latter case, the ID will appear in the text field after the 
          selection was made.
          </para>
          </listitem>
          </varlistentry>

          </variablelist>
        </sect1>
        
        <!-- =============== Appendices Sub-subsection ================ -->
    	<sect1 id="filtref-misc">
        <title>Miscellaneous filters</title>
        <para>This category includes the following rules which do not
        naturally fit into any of the above categories:</para>
          <variablelist>

          <varlistentry><term>Has the personal attribute</term>
          <listitem><para> This rule matches people who have the personal 
          attribute of the specified value. The specified personal attribute
          name should be selected from the menu. The specified value should 
          be typed into the text entry field. 
          </para></listitem>
          </varlistentry>

          <varlistentry><term>Has the family attribute</term>
          <listitem><para> This rule matches people who have the family 
          attribute of the specified value. The specified family attribute
          should be selected from the menu. The specified value should be 
          typed into the text entry field. 
          </para></listitem>
          </varlistentry>

          <varlistentry><term>Matches the filter named</term>
          <listitem><para> This rule matches people who are matched 
          by the specified filter. 
          The specified filter name should be selected from the menu. 
          </para></listitem>
          </varlistentry>

          </variablelist>
        </sect1>
        
</appendix>