Difference between revisions of "Example.gramps"

From Gramps
Jump to: navigation, search
(Load example.gramps)
m (Connecting to the example Media Objects)
(42 intermediate revisions by 8 users not shown)
Line 1: Line 1:
Your installation of Gramps should include an example family tree database. This is used to provide a known stable environment for testing.
+
==What is in an Example Tree?==
 +
The example family tree database ('''<code>example.gramps</code>''' file) ideally will have an example of everything, at least one, of everything Gramps does, or which it is possible to do in Gramps, even if obscure etc.
  
If you think you have an issue/bug in your ''Family Tree''/database, try the same operation with the example family tree. If the problem happens there as well, then it is probably not due to a [[Recover corrupted family tree|corruption in your data]].
+
{{man tip|Before filing a bug report...|Is your Tree damaged? When you suspect that you have discovered an issue (aka 'bug') in Gramps, first try the same operation with the example family tree.<br />&bull; If the problem happens there as well, then [[How_to_create_a_good_bug_report|file a bug report]]. <br />&bull; If the problem cannot be recreated using the example family tree, then you may need to [[Recover corrupted family tree|fix a corruption in your data]].}}
 +
==The purpose of an Example Tree==
 +
[[File:Importfamilytree-dialogLinux-51.png|thumb|right|400px|Fig. {{#vardefineecho:figure|{{#expr:{{#var:figure}}+1}}}} Import Family Tree - Gnome for Ubuntu dialog example]]
 +
[[File:Importfamilytree-dialog-51.png|thumb|right|400px|Fig. {{#vardefineecho:figure|{{#expr:{{#var:figure}}+1}}}} Import Family Tree - Windows dialog example]]
 +
[[File:Importfamilytree-dialogMac-51.png|thumb|right|400px|Fig. {{#vardefineecho:figure|{{#expr:{{#var:figure}}+1}}}} Import Family Tree - macOS dialog example]]
 +
 
 +
Your installation of Gramps should include some example family tree data. This data is used for working through tutorials and for safely exploring tools or features.
 +
 
 +
And, because many of the features of Gramps cannot be explored until the Tree is populated with People, Families, Events, Places, Sources, Media and other types of data; importing the example data creates a playground for exploring Gramps.
 +
 
 +
Further, most of the examples, [[:Category:How_do_I...|"How do I..." tutorials]] and screen-capture [[Special:ListFiles|illustrations (aka figures)]] in this wiki are based on this example data freshly imported into a newly created (empty) tree. So, by using this data when following instructions on a new technique, you should see the same results.
 +
 
 +
This eliminates the ambiguity and wonder if a different result was because you didn't correctly apply the technique or your data had a critical difference. That lets you focus appropriately: on improving your technique or repairing your data.
 +
 
 +
Such a tree can be considered to be 'expendable.' If you accidentally mangle the tree then simply [[Gramps_{{man version}}_Wiki_Manual_-_Manage_Family_Trees#Deleting_a_Family_Tree|discard the Tree]], create a [[Gramps_{{man version}}_Wiki_Manual_-_Manage_Family_Trees#Starting_a_new_Family_Tree|new Tree]] and [[Gramps_{{man version}}_Wiki_Manual_-_Manage_Family_Trees#Importing_data|import]] the example family tree data again.
 +
 
 +
The example is also used to provide a known, stable and predictable environment for testing. Many conditions cannot be recreated without tree data. Using this tree (as a common frame of reference) eliminates the extra complexity of [[How_to_create_a_good_bug_report#Creating_a_test_database|describing how to recreate the data]] before [[How_to_create_a_good_bug_report#Recording_the_steps_that_reproduce_the_bug|describing the issue]].
  
 
==Load <code>example.gramps</code>==
 
==Load <code>example.gramps</code>==
Follow these steps to load the example family tree:
+
Follow these steps to bring the external file "'''example.gramps'''" into a family tree database:
# Find <code>example.gramps.gz</code> or <code>example.gramps</code> on your system. For example:
+
# Find <code>example.gramps</code> or <code>example.gramps.gz</code> on your system.<br />For example in each Operating System:
## on Linux <code>/usr/share/doc/gramps/example/gramps/</code>
+
#* on Linux, <code>/usr/share/doc/gramps/example/gramps/</code>. If the file is named <code>example.gramps.gz</code>, rename it to <code>example.gramps</code> and gramps will recognize it. You can copy this file to a temporary location or import it directly from this directory.
## on MS-Windows AIO <code>C:\Program Files\GrampsAIO64-X.X.X\share\doc\gramps\example\gramps</code> (On MS-Windows ensure you can see hidden files; [[Gramps_5.0_Wiki_Manual_-_User_Directory#MS_Windows|User Directory:MS Windows]])
+
#* on MS-Windows v{{template:Version windows AIO64}} AIO, <code>C:\Program&nbsp;Files\GrampsAIO64-{{template:Version windows AIO64}}\share\doc\gramps\example\gramps</code> (On MS-Windows, ensure you can see hidden files; see  [[Gramps_{{Version manual}}_Wiki_Manual_-_User_Directory#MS_Windows|User Directory:MS Windows]])
## on Apple MacOS <code>/Users/<username>/Library/Application Support/gramps</code> (On MacOS ensure you can see hidden files; see: [[Gramps_5.0_Wiki_Manual_-_User_Directory#Mac_OS_X|User Directory:Mac OS X]])
+
#* on Apple macOS, the example database is located inside the application bundle at <code>/Applications/Gramps.app/Contents/Resources/share/doc/gramps/example/gramps/</code>
# On Linux open <code>example.gramps.gz</code>, and extract <code>example.gramps</code> to a temporary location.
 
 
# Start Gramps
 
# Start Gramps
# To create a new family tree {{man menu|Family Trees > Manage Family Trees...}} select the {{man button|New}} button. Give it some name, such as ''example''
+
# Create a new family tree [[File:ManageDatabases-icon-toolbar-51.png|right|thumb|Fig. {{#vardefineecho:figure|{{#expr:{{#var:figure}}+1}}}} Manage databases - icon on toolbar (Same as using menu {{man menu|Family Trees &#x27a1; Manage Family Trees...}})]]
# Open this new family tree. It will be empty.
+
#* If the "Family Tree - Gramps" dialog did not appear automatically when starting Gramps, select the {{man menu|Family Tree &#x27a1; Manage Family Trees...}} menu option or use the [[Gramps_5.1_Wiki_Manual_-_Keybindings|keybinding]] {{man key press|Ctrl|o}}
# In {{man menu|Edit > Preferences}}, change the {{man label|Base path for relative media paths:}}. This could be in a new directory, to keep it separate to your own family tree media. (eg On Linux <code>~/gramps/example/</code>)
+
#* select the {{man button|New}} button.  
# Copy the media files from the example directory (that you found in step 1, above) to this media path directory.
+
#* Give it some name, such as ''example''
# In Gramps, use {{man menu|Family Trees > Import...}} to import <code>example.gramps</code>.
+
#* select the {{man button|Load Family Tree}} button to open this highlighted new family tree. ''With this empty tree, the interface will be distressingly bare.''
 +
# [[Gramps_{{Version manual}}_Wiki_Manual_-_Manage_Family_Trees#Importing_data|import]] the example.gramps file
 +
#* Use {{man menu|Family Trees &#x27a1; Import...}} menu or use the [[Gramps_5.1_Wiki_Manual_-_Keybindings#2|keybinding]] {{Man key press|Ctrl|i}} to open the [[File Chooser|File Chooser]]
 +
#* browse to the folder found in step 1<br />''The default file chooser navigation option for filepaths is to displaying each hierarchical level using clickable [https://wikipedia.org/wiki/Breadcrumb_navigation breadcrumb navigation]. If you would rather type (or paste) in the path found above, press the {{man key press|Ctrl|L}} keybinding to swtch from breadcrumbs to an editable text box.''
 +
#* click the <code>example.gramps</code> item to highlight (aka "select") the file
 +
#* click the highlighted file again to begin the import
 +
====Import Statistics of the example.gramps family tree====
 +
{| class="wikitable"
 +
|
 +
Number of new objects imported:
 +
* People: 2157
 +
* Families: 762
 +
* [[Sources|{{man label|Sources}}]]: 4
 +
* [[Events_in_Gramps|{{man label|Events}}]]: 3432
 +
* Media Objects: 7
 +
* [[Places_in_Gramps|{{man label|Places}}]]: 1294
 +
* [[Repositories_in_Gramps|{{man label|Repositories}}]]: 3
 +
* Notes: 19
 +
* [[Tags_in_Gramps|{{man label|Tags}}]]: 2
 +
* [[Citations#Why_Cite|{{man label|Citations}}]]: 2854
 +
 
 +
Media objects with relative paths have been
 +
imported. These paths are considered relative to
 +
the media directory you can set in the preferences,
 +
or, if not set, relative to the user's directory.
 +
|[[File:GEDCOM-ImportStatistics-dialog-50.png|right|200px|thumb|Fig. {{#vardefineecho:figure|{{#expr:{{#var:figure}}+1}}}} Import Statistics - dialog]]
 +
|}
 +
 
 +
==Connecting to the example Media Objects==
 +
[[File:Broken Media Path.png|right|350px|thumb|Fig. {{#vardefineecho:figure|{{#expr:{{#var:figure}}+1}}}} Media object with a broken filepath]]
 +
There are seven example Media Objects (images in JPEG and PNG file format) distributed with the '''example.gramps''' tree. The filepaths specified in the tree  use a relative media path as the starting point (the {{man label|Base path for relative media paths:}}). The default  directory (defined in the Preferences) uses a different starting point.
 +
 
 +
So these images won't be locatable until the media path has been re-defined. And the Preview thumbnails will display 'broken link' icon of a box with a red 'x'.
 +
 
 +
The media path can be reset now or if starting to experiment with images.  
 +
# In {{man menu|Edit > Preferences}}, change the {{man label|Base path for relative media paths:}} in the [[Gramps_{{Version manual}}_Wiki_Manual_-_Settings#General|{{man label|General}}]] tab. This could be in a new directory, to keep it separate to your own family tree media. (<abbr title="exempli gratia - Latin phrase meaning 'for example'">e.g.</abbr> On Linux <code>~/gramps/example/</code>)
 +
# Copy the media files from the example directory (that you found in step 1, above) to this media path directory.  
 +
{{man note|The '''example.gramps''' family tree data file| Alternately, a replacement Gramps ''[https://raw.githubusercontent.com/gramps-project/gramps/maintenance/gramps51/example/gramps/example.gramps example.gramps]'' [[XML|{{man label|XML}}]] family tree database file (without the Media Objects) can be downloaded from the GitHub file store.}}
  
 
==See also==
 
==See also==
* [[Recover corrupted family tree]]
+
* [https://youtu.be/L5fXrfETAUw Gramps Tutorial #2: Creating Backups & Updating your Software] YouTube video by [https://www.youtube.com/channel/UCVIYPTJ3MGttLICyJDBZeSw TechTutorials].<br />''Importing the [[Example.gramps]] Tree begins at 17 minutes 4 seconds.''
 
+
* [[Data.gramps]] - a smaller (60 person) sample file
 +
* sample.ged - a 42 person [[Gramps_Glossary#gedcom|GEDCOM]] tree <br />''(hint: GEDCOM files do not specify a [[Gramps_Glossary#home_person|Home Person]]. Edwin Michael Smith is a reasonable person to [[Gramps_{{man version}}_Wiki_Manual_-_Settings#Setting_Home_person|set as Home Person]].)''
 +
: for MS Windows, located in <tt>C:\Program Files\GrampsAIO64-{{template:Version windows AIO64}}\share\doc\gramps\example\gedcom\</tt>
 +
* [[PseudonymTree.gramps|PseudonymTree.gramps]] - sample Pseudonym person Gramps tree for exploring filters & charts. (No Events or Media)
 +
* [https://github.com/gramps-project/gramps/tree/maintenance/gramps51/example/ Gramps-Project example files] (GitHub folder)
 +
* [[Plugins_Command_Line#Generate_Testcases_for_Persons_and_Families|testcase file generator]]
 +
* Backup and data recovery
 +
** [[How to make a backup]]
 +
** [[Template:Backup_Omissions|Backup omissions]] - what is not included during a backup
 +
** [[Recover corrupted family tree]]
 +
* Feature request {{bug|12394}} : '''example.gramps''' tree changes requested for version 5.2 wiki manual illustration purposes
 
[[Category:Documentation]]
 
[[Category:Documentation]]
 
[[Category:Gramps Examples]]
 
[[Category:Gramps Examples]]
 
[[Category:Genealogy]]
 
[[Category:Genealogy]]
 
[[Category:Developers/General]]
 
[[Category:Developers/General]]

Revision as of 07:28, 15 September 2021

What is in an Example Tree?

The example family tree database (example.gramps file) ideally will have an example of everything, at least one, of everything Gramps does, or which it is possible to do in Gramps, even if obscure etc.

Tango-Dialog-information.png
Before filing a bug report...

Is your Tree damaged? When you suspect that you have discovered an issue (aka 'bug') in Gramps, first try the same operation with the example family tree.
• If the problem happens there as well, then file a bug report.
• If the problem cannot be recreated using the example family tree, then you may need to fix a corruption in your data.

The purpose of an Example Tree

Fig. 1 Import Family Tree - Gnome for Ubuntu dialog example
Fig. 2 Import Family Tree - Windows dialog example
Fig. 3 Import Family Tree - macOS dialog example

Your installation of Gramps should include some example family tree data. This data is used for working through tutorials and for safely exploring tools or features.

And, because many of the features of Gramps cannot be explored until the Tree is populated with People, Families, Events, Places, Sources, Media and other types of data; importing the example data creates a playground for exploring Gramps.

Further, most of the examples, "How do I..." tutorials and screen-capture illustrations (aka figures) in this wiki are based on this example data freshly imported into a newly created (empty) tree. So, by using this data when following instructions on a new technique, you should see the same results.

This eliminates the ambiguity and wonder if a different result was because you didn't correctly apply the technique or your data had a critical difference. That lets you focus appropriately: on improving your technique or repairing your data.

Such a tree can be considered to be 'expendable.' If you accidentally mangle the tree then simply discard the Tree, create a new Tree and import the example family tree data again.

The example is also used to provide a known, stable and predictable environment for testing. Many conditions cannot be recreated without tree data. Using this tree (as a common frame of reference) eliminates the extra complexity of describing how to recreate the data before describing the issue.

Load example.gramps

Follow these steps to bring the external file "example.gramps" into a family tree database:

  1. Find example.gramps or example.gramps.gz on your system.
    For example in each Operating System:
    • on Linux, /usr/share/doc/gramps/example/gramps/. If the file is named example.gramps.gz, rename it to example.gramps and gramps will recognize it. You can copy this file to a temporary location or import it directly from this directory.
    • on MS-Windows v5.2.1 AIO, C:\Program Files\GrampsAIO64-5.2.1\share\doc\gramps\example\gramps (On MS-Windows, ensure you can see hidden files; see User Directory:MS Windows)
    • on Apple macOS, the example database is located inside the application bundle at /Applications/Gramps.app/Contents/Resources/share/doc/gramps/example/gramps/
  2. Start Gramps
  3. Create a new family tree
    Fig. 4 Manage databases - icon on toolbar (Same as using menu Family Trees ➡ Manage Family Trees...)
    • If the "Family Tree - Gramps" dialog did not appear automatically when starting Gramps, select the Family Tree ➡ Manage Family Trees... menu option or use the keybinding Ctrl+o
    • select the New button.
    • Give it some name, such as example
    • select the Load Family Tree button to open this highlighted new family tree. With this empty tree, the interface will be distressingly bare.
  4. import the example.gramps file
    • Use Family Trees ➡ Import... menu or use the keybinding Ctrl+i to open the File Chooser
    • browse to the folder found in step 1
      The default file chooser navigation option for filepaths is to displaying each hierarchical level using clickable breadcrumb navigation. If you would rather type (or paste) in the path found above, press the Ctrl+L keybinding to swtch from breadcrumbs to an editable text box.
    • click the example.gramps item to highlight (aka "select") the file
    • click the highlighted file again to begin the import

Import Statistics of the example.gramps family tree

Number of new objects imported:

Media objects with relative paths have been imported. These paths are considered relative to the media directory you can set in the preferences, or, if not set, relative to the user's directory.

Fig. 5 Import Statistics - dialog

Connecting to the example Media Objects

Fig. 6 Media object with a broken filepath

There are seven example Media Objects (images in JPEG and PNG file format) distributed with the example.gramps tree. The filepaths specified in the tree use a relative media path as the starting point (the Base path for relative media paths:). The default directory (defined in the Preferences) uses a different starting point.

So these images won't be locatable until the media path has been re-defined. And the Preview thumbnails will display 'broken link' icon of a box with a red 'x'.

The media path can be reset now or if starting to experiment with images.

  1. In Edit > Preferences, change the Base path for relative media paths: in the General tab. This could be in a new directory, to keep it separate to your own family tree media. (e.g. On Linux ~/gramps/example/)
  2. Copy the media files from the example directory (that you found in step 1, above) to this media path directory.
Gramps-notes.png
The example.gramps family tree data file

Alternately, a replacement Gramps example.gramps XML family tree database file (without the Media Objects) can be downloaded from the GitHub file store.

See also

for MS Windows, located in C:\Program Files\GrampsAIO64-5.2.1\share\doc\gramps\example\gedcom\