Gramps - User contributions [en]

What to do for a release

2026-04-13T13:43:18Z

Codefarmer: There is no 32-bit version AIO package any more

{{man note|Developer notes for '''What to do for a release '''}}

Note that the main use of this page will be for making a normal "minor" release. If you are making a "major" release (e.g. x.y.0) then you will need to update this page first, to change the numbers. But if you are only making an "alpha" or "beta" release, some steps may be skipped, or altered slightly.

Note also that there are additional necessary [[What_to_do_for_a_release#Post-release|Post release]] tasks which are related to making a new release. For instance, the wiki will require making a new release-section and updating [[Template:Version_Templates#General|"General" version templates]]. For the making a new release-section on the bug tracker. Or when making new Debian and Mac and Windows [[:Category:Developers/Packaging|packaging]], they will need to be coordinated with the appropriate [[Team#Package_Maintainers|package maintainers]] and updating the corresponding [[:Category:Versions|Versions]] : [[Template:Version_Templates|Templates]].

==Pre-release==
===Agree a release timetable===

Co-ordinate with the [[Team#Package_Maintainers|package maintainers]] to agree a release timetable.
For a major release there may be a schedule on the [[5.2_Roadmap|Roadmap]]

===Announce a feature freeze===
For a major release, announce a feature freeze on the ''gramps-devel'' mailing list.
This will usually be about 4 weeks before the release date.

===Translation update===
The translation template should be updated, if necessary, just before the string freeze is announced.
* Check for new files since the last release:
cd po
intltool-update -m
:That will create a file called <code>missing</code>in the <code>po</code> directory if there are new files that need to be scanned for translatable strings. Examine each of the files listed in <code>missing</code>, adding each to <code>POTFILES.in</code> if it contains translatable string constants and to <code>POTFILES.skip</code> if it does not.
* Generate a new template file:
python3 update_po.py -p # makes a new gramps.pot template file
git diff gramps.pot
:Examine the changes. If they're all just comments about where a string is found you need not commit the change (so the next line will restore the official file, instead of the one you just made):
git restore gramps.pot
:If there have been changes on <code>msgid</code> entries, you'll need to commit <code>gramps.pot</code> and ask translators to update their <tt>.po</tt> files before you can make a release:
git add gramps.pot
git commit -m "Update translation template for new release"
git push
:After updating the <code>pot</code> file, push the changes and wait for Weblate to update the <code>po</code> files. Merge the corresponding pull request from Weblate.
* Check current translation files:
python3 update_po.py -k all
:There should be very few warnings or fatal errors. Warnings related to new languages using default values in their headers are acceptable. There will also be some fatal errors reported due to the non-standard way we handle inflected dates. See the section on [https://gramps-project.org/wiki/index.php/Date_Handler#Localizing_the_date_formats Localizing the date formats] in the [https://gramps-project.org/wiki/index.php/Date_Handler Date Handler] wiki page for further details. For example "{long_month}" may be translated as "{long_month.forms[Р]}".
:All other fatal errors should be fixed.
Also see:
* [[Template:Gramps_translations#INCOMPLETE_TRANSLATIONS]] - Update if any translation needs to be added or excluded due to not meeting the minimum 70% completion requirement.

===Announce a string freeze===
For a major release, announce a string freeze on the ''gramps-devel'' mailing list and on Weblate.
This will usually be about 2 weeks before the release date.

In the ''Program'' component on Weblate, select "Manage⟶Post announcement" from the menu. Enter an ''Expiry date'' the day before the release date, and select the ''Notify users'' checkbox to send a notification to all subscribed users.

==Prepare your repository==
* Check out the current stable branch:
git checkout maintenance/gramps{{Stable_branch}}
:That branch name assumes that you're using the same name as the Github repository; if you're not (perhaps you don't use <code>maintenance</code> in the name) use your local name.
* Make sure that your local copy is clean:
git status
: If you have any uncommitted changes, either commit them now or stash them until after you've completed the release.
* Clean up any untracked files and make sure that the local repo is up to date:
git clean -fdx
git pull --rebase
:If you had commits that hadn't been pushed yet they'll show up as "applying" messages in the output of this command. If that's the case re-run the tests and push as usual.
* Build and test to make sure that everything works, then clean the repo of all build products.

===Check the About box year===

Check if the year in the {{man label|About}} box needs to be updated

eg:
''© 2007-2024 The Gramps Developers''
to
''© 2007-'''2025''' The Gramps Developers''.

Found in <code>gramps/gen/const.py</code>

===API docs update year===
If needed in the file:

docs/conf.py

Update the year for the copyright.

copyright = '2001-2025, The Gramps Project'

===Update Classifier in setup.py===
Change [https://pypi.python.org/pypi?%3Aaction=list_classifiers Classifier] to the appropriate one in [https://github.com/gramps-project/gramps/blob/maintenance/gramps50/setup.py setup.py] (master is always the first one)

<pre>
Development Status :: 1 - Planning
Development Status :: 2 - Pre-Alpha
Development Status :: 3 - Alpha
Development Status :: 4 - Beta
Development Status :: 5 - Production/Stable
</pre>

Check if any additional language classifier needs to be added also.

==Release name==
Refer to (and update) the [[Previous releases of Gramps|list of previous releases]].

Previously you needed to select an appropriate name but we have not named releases for several years now. You will still need to add the release though, including things like its relevant color.

* [[Talk:Previous_releases_of_Gramps|Suggestions]] : For Gramps 5.0 <code>Just remember that you're standing on a planet that's evolving</code>

==Changelog and NEWS file==

[https://www.gnu.org/licenses/old-licenses/gpl-2.0.en.html#section2 Section ''2a''] of the '''G'''eneral '''P'''ublic '''L'''icense says that if you distribute a modified version of a program: ''you must cause the modified files to carry prominent notices stating that you changed the files and the date of any change''.

Note that the <code>{{version}}</code> below means the ''previous'' version, not the one you're about to release (which is the
<code>..</code>).
git log v{{version}}.. --pretty --numstat --summary --no-merges | git2cl > ChangeLog
git log v{{version}}.. --pretty --numstat --summary --no-merges -- po/*.po | git2cl > po/ChangeLog
git add ChangeLog
git add po/ChangeLog
*Edit and update the <code>NEWS</code> file using the new ChangeLog entries as a guide. If this is the first branch in a new series there will be no NEWS file, so look at a previous release and mimic the format.
Commit the NEWS file:
git add NEWS
git commit -m "Update ChangeLog and NEWS files"

==Working on VERSION==
* Modify <code>[https://github.com/gramps-project/gramps/blob/master/gramps/version.py gramps/version.py]</code>. Update <code>VERSION_TUPLE</code> to the new version and set <code>DEV_VERSION</code> to indicate an official release:

VERSION_TUPLE = (4, 2, ...)

- DEV_VERSION = True
+ DEV_VERSION = False

* Add an entry to the [https://github.com/gramps-project/gramps/blob/maintenance/gramps52/data/org.gramps_project.Gramps.metainfo.xml.in org.gramps_project.Gramps.metainfo.xml.in] file.

* Save the changes:
git commit -am "Release Gramps {{version}}"

* Check that the version number is correct:
python3 Gramps.py -v

* If everything looks good, push the changes:
git push origin maintenance/gramps{{Stable_branch}}
* If that fails then someone pushed a commit while you were working. Return to [[What_to_do_for_a_release#Prepare_your_repository|Prepare your repository]] and start over.

==Create a tag==
Create the release tag; note the '''v''' leading the actual tag.:
git tag -am "Tag {{version}}" v{{version}}

==Push to repository==
Push the changes to the repository:
git push origin v{{version}}

===Update DEV_VERSION to indicate a development version===

Revert change on <code>DEV_VERSION</code> in <code>gramps/version.py</code> so that the git revision is appended to the reported version in non-release builds:
- DEV_VERSION = False
+ DEV_VERSION = True

Save change:
git commit -am "Set to development version"
git push

===Github===
* Github generates a tarball automatically when we push a tag.
* Go to [https://github.com/gramps-project/gramps Github] and log in if necessary.
* Select '''NN Releases''' from the line of items just above the thick line ('''NN''' is the number of releases so far).
* Find the tag you just pushed and click it, or click the "Draft a new release" button.
* Copy the NEWS file contents into the '''Write''' tab. You can use the '''Preview''' tab to check your formatting.
* Add the sh256sum of the source distribution to the bottom of the release notes.

You can obtain the sha256sum with the following command:

git archive --format=tar --prefix=gramps-{{version}} v{{version}} | gzip | sha256sum

Alternatively, download it and use:

sha256sum gramps-{{version}}.tar.gz

* Click '''Publish Release''' at the bottom of the edit area when you're satisfied with the contents.

===SourceForge===
* Go to [https://sourceforge.net/projects/gramps/files/ the SourceForge files page] and log in if necessary.
* Click on '''Stable''' or '''Unstable''' depending on the class of the release you're making.
* Click '''Add Folder''' and name the directory for the release version. Click "'Create'". Click your new folder to enter it.
* You can either download the GitHub-generated tarball or create one locally:
python3 setup.py sdist
* Click '''Add File''' and drag the tarball to the drop area on the web page.
* Copy the release notes from GitHub into a file called README.md and upload it.

==Announcing the new release==
* update mantisdb(Bug/issue database) and enable the new version via Admin:Projects item for reporting issues. (You will need a high-enough status on the bug tracker in order to do this, so you can ask an appropriate person if you aren't.)
* announce on gramps-announce@lists.sourceforge.net, gramps-devel@lists.sourceforge.net and gramps-users@lists.sourceforge.net (You will need to be a member of all three lists first, to send to them.)
* announce on the Discourse forum in the "[https://gramps.discourse.group/c/gramps-announce Announcements]" category.
* announce on Gramps [https://gramps-project.org/blog/blog/ blog] (File under: [https://gramps-project.org/blog/category/releases/ Gramps Releases] and [https://gramps-project.org/blog/category/news/ News]) (not needed for an alpha or beta release)
* update [[News]] section on this wiki (not needed for an alpha or beta release)
* update the list of [[Previous releases of Gramps|previous releases]]
* update reference to the new version on the [[Template:Version|wiki template]] {{version}} (not needed for an alpha or beta release)
* Verify other [[:Category:Versions|"version" Wiki templates]] values: Last version, Stable version, etc.
* update [[HeadlineNews]] (not needed for an alpha or beta release)
* update <nowiki>{{version-released}}</nowiki> [https://gramps-project.org/wiki/index.php/Template:Version-released date template] for the [[Download]] pages {{version-released}} (not needed for an alpha or beta release)
* change the Matrix room title and IRC channel title (not needed for an alpha or beta release)
* update the version number at [https://en.wikipedia.org/wiki/Gramps_(software) Wikipedia] (not needed for an alpha or beta release)

==Post-release==
* merge forward the <code>NEWS</code> file

=See also=
*Category [[:Category:Versions|Versions]] : [[Template:Version_Templates|Template]]
*Building a distribution to share as on the [[Download]] page
:[[File:Windows_32x32.png]] [[Building Gramps AIO cx freeze-based]] - Updating the MS-Windows All-In-One package

* [[Brief introduction to Git]]
* [[Running a development version of Gramps]]
* [[:Category:Developers/Packaging]]
* [[:Category:AppData]] - Screenshots used by Appdata - Debian
* [[.dtd and .rng]]
* [[Rollover_for_the_manual|Rollover for the Wiki]] - for major and feature releases. No rollover for maintenance releases.
* [[Special:WhatLinksHere/Template:Bug|List of pages linked to Bug Report template]] - verify the reported issues still apply to the new release. Leave links in place for any issue fixed in maintenance releases. Simply add notations for the version where the fix was applied. Remove links for fixed issues in Rollovers.

=External links=
* https://github.com/gramps-project
* https://gramps-project.org/cpanel
* https://sourceforge.net/projects/gramps/

[[Category:Developers/General]]
[[Category:Developers/Packaging]]

Programming guidelines

2026-04-09T18:38:30Z

Codefarmer: suggest standalone black installation as the least preferred option

In a multi-programmer environment, it is important to follow common coding guidelines to make sure the code remains maintainable.

== Coding style ==

=== PEP8 ===
* Write [https://www.python.org/dev/peps/pep-0008/ PEP 8] compatible code! This is important to have a consistent, readable codebase.
** it is not explicit in PEP8, but we like a space after a comma

=== Tabs ===
* Do not use TABs. Use space characters. In Gramps we use 4 spaces for indentation. This does not mean you must set your TAB stops to 4. TABs and indents are not the same thing. Most editors have a configuration option to set indentation and TAB stops. Be careful to just set the '''indentation''' to 4, which automatically means it has to be '''spaces'''. TABs are still necessary, in Makefiles for example, and they '''have to''' be equivalent to 8 spaces, '''always'''. To summarize:
** uses spaces, no TABs
** indentation is 4
** TAB stops (if any) are at position 9,17,25,... (first column is 1)

=== Members names ===
* Private class functions (functions that cannot be called outside the class) should be preceded with two underscores.
* Protected functions (functions that can only be called by the class or derived classes) should be preceded with one underscore.
<pre>
def __private_function(self):
pass

def _protected_function(self):
pass
</pre>

=== Callbacks ===

Names of callbacks should be prefixed by 'cb_'. For example, <code>cb_my_callback</code>.

<code>pylint</code> does not check that arguments are used when methods are named in this way. This is useful to avoid the <code>pylint</code> warning: 'W0613: Unused argument <arg>'.

=== Imports ===
The top module is called gramps, and it has following submodules:
* gen
* cli
* gui
* plugins
The other dirs should not contain code, or are for testing.

Within a submodule, only relative imports are allowed of the own submodule (so starting with . or with a module of the own directory), and absolute imports of other submodules (so starting with <code>gramps.</code>)

{{man note|Important:|files in the gen submodule are '''not''' allowed to import files from the other submodules. So <code>gen</code> should be self-contained.}}

== Class headers ==
* Each class should have a simple header to help mark it in the file. This is not used for documentation - it is used to help find the class when multiple classes exist in the same file.
<pre>
#------------------------------------------------------------
#
# MyClass
#
#------------------------------------------------------------
</pre>

== Docstrings ==
* Python provides a docstrings to document classes and functions. If the class is a class used by others (such as the [http://www.gramps-project.org/docs/gen/gen_lib.html#module-gen.lib gen lib] classes), the docstrings should follow the restructuredtext ([http://docutils.sourceforge.net/docs/user/rst/quickstart.html#structure rst]) format. This allows us to extract [http://www.gramps-project.org/docs/ API] documentation [[Devhelp#See_also|using Sphinx]], a documentation generator for Python code.

* Aside from adding doc strings to classes and functions, also the api generating rst files must be edited so as to extract the documentation. These files are in the [https://github.com/gramps-project/gramps/tree/master/docs docs directory], for info read the [https://github.com/gramps-project/gramps/blob/master/docs/README.txt /docs/README.txt] file.

:More info
:* [http://www.sphinx-doc.org/en/stable/markup/ Sphinx for python]
:* [http://www.sphinx-doc.org/en/stable/rest.html doc with Sphinx]

Classes that are not core reusable classes do not have to follow this format (although we encourage you do), but should be documented using docstrings.
<pre>
class MyClass:
"""
MyClass is a sample class.
"""

def my_function(self):
"""
The my_function task serves no purpose whatsoever.
"""
pass
</pre>

== Black ==
Gramps CI checks for code formatting compliance using [https://github.com/psf/black Black].

Black can be installed as a [https://pypi.org/project/black/ Python PIP package,] as a plugin/integration to many IDEs, or as a [https://github.com/psf/black/releases/ standalone tool] on the system. Follow the [https://black.readthedocs.io/en/stable/usage_and_configuration/the_basics.html usage instructions] on the Black docs to validate your file changes. Doing this prior to creating the Pull Request ensures that it will pass the lint check.

If code in a PR violates formatting rules the PR fails the CI check, and cannot be merged. Code which requires changes is shown in the Checks tab in the Lint panel. Make changes required to make the lint check pass. Sometimes the changes are not visible because they are white space violations, so look carefully. When using Black locally, use the same version as the CI system to ensure formatting consistency.

== Pylint ==
* Run <code>pylint</code> on your code before checking in.
* New files shall have a Pylint score of 9 or higher, but not enforced by CI tools as Black formatting is.
* Any changes to existing files with a Pylint score lower than 9 shall not reduce the Pylint score. It is expected that over time, this policy will cause all files to eventually have a score of 9 or higher.

Note that you must run <code>pylint</code> in the <code>gramps</code> directory. If import errors still occur, add a PYTHONPATH. Example usage:
me@laptop:~/programs/master/src$ PYTHONPATH=plugins/lib/ pylint --reports=y plugins/mapservices/googlemap.py
Set reports to '''n''' to have less output. Information on the meaning of codes can be found here:
* [http://pylint-messages.wikidot.com/all-codes All codes, PyLint 1.1.0] Messages: and what they're trying to tell you
* [https://pylint.readthedocs.io/en/stable/user_guide/messages Pylint current stable] documentation - now generally has a bit more detail that the older version

== Best practices ==
* Maintain good code hygiene by following coding guidelines and running code analysis and formatting tools locally

* Always develop with [[Coding_for_translation|language translation]] in mind

* Reduce dependencies (imports) between files.

* Think on [[Accessibility]].

[[Category:Developers/General]]
[[Category:Developers/Quality Assurance]]

Programming guidelines

2026-04-09T16:38:39Z

Codefarmer: move punctuation within URL

In a multi-programmer environment, it is important to follow common coding guidelines to make sure the code remains maintainable.

== Coding style ==

=== PEP8 ===
* Write [https://www.python.org/dev/peps/pep-0008/ PEP 8] compatible code! This is important to have a consistent, readable codebase.
** it is not explicit in PEP8, but we like a space after a comma

=== Tabs ===
* Do not use TABs. Use space characters. In Gramps we use 4 spaces for indentation. This does not mean you must set your TAB stops to 4. TABs and indents are not the same thing. Most editors have a configuration option to set indentation and TAB stops. Be careful to just set the '''indentation''' to 4, which automatically means it has to be '''spaces'''. TABs are still necessary, in Makefiles for example, and they '''have to''' be equivalent to 8 spaces, '''always'''. To summarize:
** uses spaces, no TABs
** indentation is 4
** TAB stops (if any) are at position 9,17,25,... (first column is 1)

=== Members names ===
* Private class functions (functions that cannot be called outside the class) should be preceded with two underscores.
* Protected functions (functions that can only be called by the class or derived classes) should be preceded with one underscore.
<pre>
def __private_function(self):
pass

def _protected_function(self):
pass
</pre>

=== Callbacks ===

Names of callbacks should be prefixed by 'cb_'. For example, <code>cb_my_callback</code>.

<code>pylint</code> does not check that arguments are used when methods are named in this way. This is useful to avoid the <code>pylint</code> warning: 'W0613: Unused argument <arg>'.

=== Imports ===
The top module is called gramps, and it has following submodules:
* gen
* cli
* gui
* plugins
The other dirs should not contain code, or are for testing.

Within a submodule, only relative imports are allowed of the own submodule (so starting with . or with a module of the own directory), and absolute imports of other submodules (so starting with <code>gramps.</code>)

{{man note|Important:|files in the gen submodule are '''not''' allowed to import files from the other submodules. So <code>gen</code> should be self-contained.}}

== Class headers ==
* Each class should have a simple header to help mark it in the file. This is not used for documentation - it is used to help find the class when multiple classes exist in the same file.
<pre>
#------------------------------------------------------------
#
# MyClass
#
#------------------------------------------------------------
</pre>

== Docstrings ==
* Python provides a docstrings to document classes and functions. If the class is a class used by others (such as the [http://www.gramps-project.org/docs/gen/gen_lib.html#module-gen.lib gen lib] classes), the docstrings should follow the restructuredtext ([http://docutils.sourceforge.net/docs/user/rst/quickstart.html#structure rst]) format. This allows us to extract [http://www.gramps-project.org/docs/ API] documentation [[Devhelp#See_also|using Sphinx]], a documentation generator for Python code.

* Aside from adding doc strings to classes and functions, also the api generating rst files must be edited so as to extract the documentation. These files are in the [https://github.com/gramps-project/gramps/tree/master/docs docs directory], for info read the [https://github.com/gramps-project/gramps/blob/master/docs/README.txt /docs/README.txt] file.

:More info
:* [http://www.sphinx-doc.org/en/stable/markup/ Sphinx for python]
:* [http://www.sphinx-doc.org/en/stable/rest.html doc with Sphinx]

Classes that are not core reusable classes do not have to follow this format (although we encourage you do), but should be documented using docstrings.
<pre>
class MyClass:
"""
MyClass is a sample class.
"""

def my_function(self):
"""
The my_function task serves no purpose whatsoever.
"""
pass
</pre>

== Black ==
Gramps CI checks for code formatting compliance using [https://github.com/psf/black Black].

Black can be installed as a [https://github.com/psf/black/releases/ standalone tool] on the system, as a [https://pypi.org/project/black/ Python PIP package,] or as a plugin/integration to many IDEs. Follow the [https://black.readthedocs.io/en/stable/usage_and_configuration/the_basics.html usage instructions] on the Black docs to validate your file changes. Doing this prior to creating the Pull Request ensures that it will pass the lint check.

If code in a PR violates formatting rules the PR fails the CI check, and cannot be merged. Code which requires changes is shown in the Checks tab in the Lint panel. Make changes required to make the lint check pass. Sometimes the changes are not visible because they are white space violations, so look carefully. When using Black locally, use the same version as the CI system to ensure formatting consistency.

== Pylint ==
* Run <code>pylint</code> on your code before checking in.
* New files shall have a Pylint score of 9 or higher, but not enforced by CI tools as Black formatting is.
* Any changes to existing files with a Pylint score lower than 9 shall not reduce the Pylint score. It is expected that over time, this policy will cause all files to eventually have a score of 9 or higher.

Note that you must run <code>pylint</code> in the <code>gramps</code> directory. If import errors still occur, add a PYTHONPATH. Example usage:
me@laptop:~/programs/master/src$ PYTHONPATH=plugins/lib/ pylint --reports=y plugins/mapservices/googlemap.py
Set reports to '''n''' to have less output. Information on the meaning of codes can be found here:
* [http://pylint-messages.wikidot.com/all-codes All codes, PyLint 1.1.0] Messages: and what they're trying to tell you
* [https://pylint.readthedocs.io/en/stable/user_guide/messages Pylint current stable] documentation - now generally has a bit more detail that the older version

== Best practices ==
* Maintain good code hygiene by following coding guidelines and running code analysis and formatting tools locally

* Always develop with [[Coding_for_translation|language translation]] in mind

* Reduce dependencies (imports) between files.

* Think on [[Accessibility]].

[[Category:Developers/General]]
[[Category:Developers/Quality Assurance]]

Programming guidelines

2026-04-09T16:17:08Z

Codefarmer: Elaborate on usage of Black

In a multi-programmer environment, it is important to follow common coding guidelines to make sure the code remains maintainable.

== Coding style ==

=== PEP8 ===
* Write [https://www.python.org/dev/peps/pep-0008/ PEP 8] compatible code! This is important to have a consistent, readable codebase.
** it is not explicit in PEP8, but we like a space after a comma

=== Tabs ===
* Do not use TABs. Use space characters. In Gramps we use 4 spaces for indentation. This does not mean you must set your TAB stops to 4. TABs and indents are not the same thing. Most editors have a configuration option to set indentation and TAB stops. Be careful to just set the '''indentation''' to 4, which automatically means it has to be '''spaces'''. TABs are still necessary, in Makefiles for example, and they '''have to''' be equivalent to 8 spaces, '''always'''. To summarize:
** uses spaces, no TABs
** indentation is 4
** TAB stops (if any) are at position 9,17,25,... (first column is 1)

=== Members names ===
* Private class functions (functions that cannot be called outside the class) should be preceded with two underscores.
* Protected functions (functions that can only be called by the class or derived classes) should be preceded with one underscore.
<pre>
def __private_function(self):
pass

def _protected_function(self):
pass
</pre>

=== Callbacks ===

Names of callbacks should be prefixed by 'cb_'. For example, <code>cb_my_callback</code>.

<code>pylint</code> does not check that arguments are used when methods are named in this way. This is useful to avoid the <code>pylint</code> warning: 'W0613: Unused argument <arg>'.

=== Imports ===
The top module is called gramps, and it has following submodules:
* gen
* cli
* gui
* plugins
The other dirs should not contain code, or are for testing.

Within a submodule, only relative imports are allowed of the own submodule (so starting with . or with a module of the own directory), and absolute imports of other submodules (so starting with <code>gramps.</code>)

{{man note|Important:|files in the gen submodule are '''not''' allowed to import files from the other submodules. So <code>gen</code> should be self-contained.}}

== Class headers ==
* Each class should have a simple header to help mark it in the file. This is not used for documentation - it is used to help find the class when multiple classes exist in the same file.
<pre>
#------------------------------------------------------------
#
# MyClass
#
#------------------------------------------------------------
</pre>

== Docstrings ==
* Python provides a docstrings to document classes and functions. If the class is a class used by others (such as the [http://www.gramps-project.org/docs/gen/gen_lib.html#module-gen.lib gen lib] classes), the docstrings should follow the restructuredtext ([http://docutils.sourceforge.net/docs/user/rst/quickstart.html#structure rst]) format. This allows us to extract [http://www.gramps-project.org/docs/ API] documentation [[Devhelp#See_also|using Sphinx]], a documentation generator for Python code.

* Aside from adding doc strings to classes and functions, also the api generating rst files must be edited so as to extract the documentation. These files are in the [https://github.com/gramps-project/gramps/tree/master/docs docs directory], for info read the [https://github.com/gramps-project/gramps/blob/master/docs/README.txt /docs/README.txt] file.

:More info
:* [http://www.sphinx-doc.org/en/stable/markup/ Sphinx for python]
:* [http://www.sphinx-doc.org/en/stable/rest.html doc with Sphinx]

Classes that are not core reusable classes do not have to follow this format (although we encourage you do), but should be documented using docstrings.
<pre>
class MyClass:
"""
MyClass is a sample class.
"""

def my_function(self):
"""
The my_function task serves no purpose whatsoever.
"""
pass
</pre>

== Black ==
Gramps CI checks for code formatting compliance using [https://github.com/psf/black Black].

Black can be installed as a [https://github.com/psf/black/releases/ standalone tool] on the system, as a [https://pypi.org/project/black/ Python PIP package], or as a plugin/integration to many IDEs. Follow the [https://black.readthedocs.io/en/stable/usage_and_configuration/the_basics.html usage instructions] on the Black docs to validate your file changes. Doing this prior to creating the Pull Request ensures that it will pass the lint check.

If code in a PR violates formatting rules the PR fails the CI check, and cannot be merged. Code which requires changes is shown in the Checks tab in the Lint panel. Make changes required to make the lint check pass. Sometimes the changes are not visible because they are white space violations, so look carefully. When using Black locally, use the same version as the CI system to ensure formatting consistency.

== Pylint ==
* Run <code>pylint</code> on your code before checking in.
* New files shall have a Pylint score of 9 or higher, but not enforced by CI tools as Black formatting is.
* Any changes to existing files with a Pylint score lower than 9 shall not reduce the Pylint score. It is expected that over time, this policy will cause all files to eventually have a score of 9 or higher.

Note that you must run <code>pylint</code> in the <code>gramps</code> directory. If import errors still occur, add a PYTHONPATH. Example usage:
me@laptop:~/programs/master/src$ PYTHONPATH=plugins/lib/ pylint --reports=y plugins/mapservices/googlemap.py
Set reports to '''n''' to have less output. Information on the meaning of codes can be found here:
* [http://pylint-messages.wikidot.com/all-codes All codes, PyLint 1.1.0] Messages: and what they're trying to tell you
* [https://pylint.readthedocs.io/en/stable/user_guide/messages Pylint current stable] documentation - now generally has a bit more detail that the older version

== Best practices ==
* Maintain good code hygiene by following coding guidelines and running code analysis and formatting tools locally

* Always develop with [[Coding_for_translation|language translation]] in mind

* Reduce dependencies (imports) between files.

* Think on [[Accessibility]].

[[Category:Developers/General]]
[[Category:Developers/Quality Assurance]]

Addon:Graph View

2026-04-08T15:58:05Z

Codefarmer: GraphViz configuration for PortableApps installation

{{languages|Addon:Graph View}}
{{Third-party addon}}
[[File:Graph-View-addon-example-60.png|450px|thumb|right|"Graph View" - addon - In action showing both ancestors and descendant trees]]
'''{{man label|Graph View}}''' is an interactive {{icon|ance}} {{man label|[[Gramps_{{man version}}_Wiki_Manual_-_Categories#Charts_Category|Charts]]}} category view addon that presents a navigable ancestors and descendant tree using the current active person as a starting point. Clicking another person in the family tree will make that person the active person and will redraw the family tree based on them.

== Usage ==

From the {{icon|ance}} {{man label|Charts}} category view select the '''Graph View''' icon or select {{man menu|View > Graph View}} from the menu.

In general the Graph View is:
* Interactive, the view redraws in response to changes made to a person or family.
* The active person is highlighted.
* Clicking on another person will redraw the family tree based on that person.
* Clicking the active person will show the parent family of the active person, thereby allowing previous generations to be shown.
* A right mouse click on a person or family node shows the person or family editor as appropriate.
* Able to show both ancestors and descendant trees (adjustable from the Graph View toolbar).
* Graph view can be panned by using mouse click and drag. Select the background of the tree and drag the mouse to pan the view. Also you can use mouse scroll button to pan view in any place of view.
* Connecting full line style represents biological relationships and dashed lines non biological.

=== Graph View Toolbar ===
[[File:Graph-View-addon-toolbar-overview-60.png]]

Graph View has a smaller toolbar of its own with the following options (from left to right):

* {{man button|'''+'''}} button - {{man tooltip|Zoom in}} the view.
* {{man button|'''-'''}} button - {{man tooltip|Zoom out}} the view.
* {{man button|'''1'''}} button - {{man tooltip|Zoom to original}} resets the view to the default size.
* {{man button|'''☐'''}} button - {{man tooltip|Zoom to best fit}} fits the current family tree graph to the displayed area.
* {{man button|'''⏎'''}} button - {{man tooltip|Go to active person}} centering them in the graph area.
* {{man button|Go to bookmark}} button - {{man tooltip|Center view on selected bookmark}} - also shows {{man label|Bookmarks for current graph:}} (who are being display) and {{man label|Other Bookmarks:}} (who are not being displayed) - along with two buttons to {{man button|Add active person}} to bookmarks and {{man button|Edit}} that brings up the {{man label|Organize bookmarks}} dialog.
* {{man button|🔍 Search...}} - typing shows {{man label|Persons from current graph:}} (who are being display) and {{man label|Other persons from database:}} (who are not being displayed) as well as any being able to add or remove directly to bookmarks. {{man tooltip|Search people in the current visible graph and database. Use <{{man button|Ctrl + F}}> to make search entry active.}}
* {{man button|Generations}} - setting to change the generations shown for {{man tooltip|Ancestor generations}} 3 by default and {{man tooltip|Descendants generations}} 10 by default.
* {{man button|Spacing}} - changes the {{man tooltip|Vertical spacing between generations}} (5 default) and {{man tooltip|Horizontal spacing between the generations}} (2 default).
* {{man button|All connected}} - {{man tooltip|Show all connected persons limited by generation restrictions. Works slow, so don't set large generation values.}} ( Limited to 1000 persons, if your family tree has more than that you get the {{man label|[[Addon:Graph_View#Incomplete_graph_warning|Incomplete graph]]}} warning and only the first 1000 connected persons are drawn.)

==== On main Gramps Toolbar ====
On the main Gramps Toolbar you also have:
* {{man button|'''⎙'''(Print)}} button that does not print but instead allows you to save the currently displayed Graph into a dot format file for a later printing. This will save a .gv file and a svg file. You must select a .gv file. ([https://www.reddit.com/r/gramps/comments/jhnj9w/gramps_print_svg_does_not_show_photo/ Gramps Print -SVG does not show photo])
* [[File:Gramps-config.png|34px]] Configure the active view with options shown in the next section.

=== Configure Options ===
Select {{man menu|View > Configure...}} from the menu to change the settings on the following four tabs:

*[[Addon:Graph_View#Layout|Layout]]
*[[Addon:Graph_View#Themes|Themes]]
*[[Addon:Graph_View#Animation|Animation]]
*[[Addon:Graph_View#Search|Search]]

====Layout====
* {{checkbox|1}}{{man label|Show images}} (checkbox selected by default)
* {{checkbox|1}}{{man label|Show IDs}} (checkbox selected by default)
* {{checkbox|1}}{{man label|Show avatars}} (checkbox selected by default)
* {{checkbox|1}}{{man label|Highlight the home person}} (checkbox selected by default)
* {{checkbox|0}}{{man label|Show full dates}} (checkbox unselected by default)
* {{checkbox|0}}{{man label|Show places}} (checkbox unselected by default)
* {{man label|Placeformat:}}
** '''Default'''
** Full
* {{checkbox|0}}{{man label|Show tags}} (checkbox unselected by default)
* {{man label|Time Direction:}}
** '''Vertical: Top to Bottom'''
** Vertical: Bottom to Top
** Horizontal: Left to Right
** Horizontal: Right to Left
* {{man label|Limit number of people displayed (use 0 for unlimited):}} (<code>1000</code> default) - lets users set or disable a limit to the number of individuals that may be shown on an {{man button|[[Addon:Graph_View#Graph_View_Toolbar|All connected]]}} chart. If you see the {{man label|[[Addon:Graph_View#Incomplete_graph_warning|Incomplete graph warning]]}} dialog then change this to suit you. [https://github.com/gramps-project/addons-source/pull/635]
{{-}}

====Themes====
* {{man label|Person theme:}}
**'''Default'''
** Image on right side
** Image on left side
* {{man label|Path color to home person:}} '''<code>#000000</code>'''(default)
* {{man label|Font:}} shows the default that can be changed by selecting from the
** {{man label|Pick a Font}} dialog
* {{man label|Avatars style:}} for person nodes.
** ''Custom'' - adds four more popup entries to allow you to select your own avatar images:
*** {{man label|Male avatar:}} ''File selector''
*** {{man label|Female avatar:}} ''File selector''
*** {{man label|Unknown avatar:}} ''File selector''
*** {{man label|Other avatar:}} ''File selector''
** '''Dark (default)'''
** ''Light''
** ''Cartoon''
** ''Modern''
** ''Updated''
** ''Generic (dark)''
** ''Generic (grey)''
** ''Generic (light)''
[[File:Graph-View Avatar set.png|471px|thumb|right|Graph View - Avatar styles (Left to right: '''Dark''' / '''Light''' / '''Cartoon''')]]
* {{man label|Active person border size:}} <code>3</code>(default)
* {{man label|Person border size:}} <code>1</code>(default)
{{-}}

====Animation====
*{{checkbox|1}}{{man label|Show animation}} (checkbox selected by default)
**{{man label|Animation speed (1..5 and 5 is the slower):}} (default is 3)
**{{man label|Animation count (0..8 use 0 to turn off):}} (default is 4)
{{-}}
====Search====
*{{checkbox|1}}{{man label|Search in all database}} (checkbox selected by default)
*{{checkbox|1}}{{man label|Show person images}} (checkbox selected by default)
*{{checkbox|1}}{{man label|Show bookmarked first}} (checkbox selected by default)
{{-}}

===Context menus===
Graph view has three [https://en.wikipedia.org/wiki/Context_menu context menus] that allow the following:
*[[#Empty_section|Empty section]]
*[[#Person_node|Person node]]
*[[#Family_node|Family node]]

{{-}}
====Empty section====
[[File:GraphView-empty-context menu-52.png|thumb|450px|Right click menu shown when selecting an empty section of the chart.]]
Right-click an empty section of the Graph View to offer the following display options:
* {{checkbox|1}}{{man menu|Show images}} - Display thumbnails or avatars
* {{checkbox|1}}{{man menu|Highlight the home person}} - set the background of the Home Person to green
* {{checkbox|0}}{{man menu|Show full dates}} - format the birth and death date as only the year or as the complete date
* {{checkbox|0}}{{man menu|Show places}} - show or hide birth and death places
* {{checkbox|0}}{{man menu|Show tags}} - show color markers on tagged Persons and Families
* {{checkbox|1}}{{man menu|Show animation}} - after redraws, wiggle the Active Person to draw focus
* {{man menu|Lines type}} - choose the style of lines connecting People and Families
** {{man menu|''Direct''}}
** {{man menu|'''Curves'''}} (default)
** {{man menu|''Ortho''}}
* {{man menu|About Graph View}} - this help wiki webpage
{{-}}

====Person node====
[[File:GraphView-person-node-context-menu-52.png|thumb|450px|Right click menu shown when selecting a Person on the chart.]]
Right-click a person (node) to show a context menu offering the following options for the indicated person:

<hr>
* {{man menu|Edit}}
* {{man menu|Copy}}
* {{man menu|Delete}}
<hr>
* {{man menu|Events}}
* {{man menu|Tags}}
* {{man menu|Spouses}}
* {{man menu|Siblings}}
* {{man menu|Children}}
* {{man menu|Parents}}
* {{man menu|Related}} - shows people sharing an event
<hr>
* {{man menu|Set as home person}}
* {{man menu|Show path to home person}} - changes the view to show how these two people connect to their common ancestor
* {{man menu|Add to bookmarks}}
<hr>
* {{man menu|[[Gramps_{{man version}}_Wiki_Manual_-_Gramplets#Quick_View|Quick View]]}}
* {{man menu|[[Addon:Web_Connect_Pack|Web Connection]]}}
<hr>
* {{man menu|About Graph View}}
{{-}}

====Family node====
[[File:GraphView-family-node-context-menu-52.png|thumb|450px|Right click menu shown when selecting a Family (node) on the chart.]]
Right click a family (node) to add or delete a spouse or child.

* {{man menu|Edit}}
* {{man menu|Delete}}
<hr>
* {{man menu|Events}}
* {{man menu|Tags}}
* {{man menu|Spouses}}
* {{man menu|Children}}
<hr>
* {{man menu|[[Gramps_{{man version}}_Wiki_Manual_-_Gramplets#Quick_View|Quick View]]}}
<hr>
* {{man menu|About Graph View}}
<hr>
{{-}}

==={{man label|Incomplete graph}} warning ===
[[File:Incomplete-graph-warning-graphview-addon-60.png|thumb|450px|right]]

''This graph would contain at least {people_count} people, which exceeds the limit of {people_limit} people. For performance reasons, at least {people_missing} people won't be shown. You can change this limit in the view configuration.''

The limit may be removed or changed by setting the [[Addon:Graph_View#Layout|Layout]] tabs {{man label|Limit number of people displayed (use 0 for unlimited):}} option.


{{-}}

== Prerequisites ==
Before '''Graph View''' can be used you will need the following installed:
* [[Output_formats#Graphviz|Graphviz]]. If you can run the Gramps [[Gramps_{{man version}}_Wiki_Manual_-_Reports_-_part_5|Graph reports]] then you already have this installed.
* [https://wiki.gnome.org/Projects/GObjectIntrospection Goocanvas2 or gir1.2-goocanvas] (Gramps 4.x or greater)
** [https://wiki.gnome.org/Attic/PyGoocanvas PyGoocanvas] (Gramps 3.x)
* [https://wiki.gnome.org/action/show/Projects/GooCanvas Goocanvas]

=== Windows ===
These are already installed if you are using the Gramps All In One installer eg: <code>GrampsAIOxxxxx.exe</code>. If you are using the Gramps v6.0.6 PortableApps installer, GraphViz is installed but not configured. Execute these steps once after installing to fix that:

# Open a command prompt
# Change to the GrampsPortable\App\Gramps folder, e.g. <code>cd C:\GrampsPortable\App\Gramps</code>
# Ask dot to configure plugins and write a configuration file by executing: <code>lib\dot.exe -c</code>
# Launch GrampsPortable and switch to the GraphView and you should see a chart.

=== Linux ===

All of these should be available in common Linux distributions.

For example,

;Debian
Packages <code>Goocanvas</code> and <code>PyGoocanvas</code> as <code>libgoocanvas3</code> and <code>python-pygoocanvas</code>.

Note: As of May 2020 the required packages for Debian Testing are <code>gir1.2-goocanvas-2.0</code> and <code>libgoocanvas-2.0-9</code> from the official repositories.

Please make sure to download these for the proper architecture, like amd64 for 64-bit PCs (Intel included).

;Fedora
Try package <code>goocanvas2-devel</code>.

;Opensuse
You may need to install <code>typelib-1_0-GooCanvas-2_0</code> as mentioned in issue {{bug|8076}}.

=== macOS ===
These are already installed if you are using the Gramps All In One installer eg: <code>Gramps-Intel-xxxxx.dmg</code> or <code>Gramps-Arm-xxxxx.dmg</code>

== Issues ==

You can see related issues at [https://gramps-project.org/bugs/search.php?tag_string=GraphView bug tracker].
* {{bug|8054#c44291}} - print options.
* {{bug|9806}} - Subprocess on [GraphView] can generate a memory issue.
* {{bug|8054}} - Better label positioning in Graphview.
* [https://gramps-project.org/bugs/view.php?id=8964 8964: Enable filter on GraphView] Feature Request.
* [https://github.com/gramps-project/addons-source/pull/459 [GraphView] add custom avatars #459].
**[https://gramps.discourse.group/t/customizable-avatars-for-graphview/696 Themed avatar discussion].
* {{bug|14120}} - GraphView configuration for PortableApp installers. This has been [https://portableapps.com/comment/263547#comment-263547 reported to the PortableApps team].

==See also==
* [[Addon:AvatarGenerator]] - allows you to add and remove one or several images for a selected set of filtered people.

[[Category:Addons]]
[[Category:Plugins]]
[[Category:Developers/General]]
[[Category:Views]]
[[Category:Prerequisites|G]]

Addons development

2026-01-30T06:48:52Z

Codefarmer: Remove hyperlink so commands are easier to copy in HTTPS protocol section

{{man tip|Information on developing Gramps addons|If you are looking for addons to install, visit: [[Third-party Addons]]}}
{{man warn|Note that this article anticipates that most addons will be developed under Linux.|([[Getting started with Gramps development|Linux is the principal development platform.]]) While it is possible to do so under Windows or MacOS, some of the steps will differ and the documented processes have not been as thoroughly reviewed. So developer beware. See [[Portal:Developers]]}}
{{man note|More upto date information:|* https://github.com/gramps-project/addons-source/blob/maintenance/gramps{{Stable_branch}}/CONTRIBUTING.md 
* https://github.com/gramps-project/addons-source/blob/maintenance/gramps{{Stable_branch}}/MAINTAINERS.md}}
If you are developing a [[Third-party Addons|Third-party Addon]]; this page documents the API, methods, and best practices for Gramps 4.2 and later.

==What can addons extend?==
Addons for Gramps can extend the program in many different ways. You can add any of the following [https://github.com/gramps-project/gramps/blob/master/gramps/gen/plug/_pluginreg.py types] of addons:


* '''Importer''' (IMPORT) - adds additional file format import options to Gramps
* '''Exporter''' (EXPORT) - adds additional file format export options to Gramps
* '''[[Gramps_Glossary#gramplet|Gramplet]]''' (GRAMPLET) - adds a new interactive interface section to a Gramps view mode, which can be activated by right-clicking on the dashboard View or from the menu of the Sidebar/Bottombar in the other view categories.
* '''Gramps [[Gramps_Glossary#viewmode|View ''(mode)'']]''' (VIEW) - adds a new view mode to the list of views available within a [[Gramps_Glossary#view|View Category]]
* '''[[Map_Services|Map Service]]''' (MAPSERVICE) - adds new mapping options to Gramps
* '''Plugin lib''' (GENERAL) - libraries that are present giving extra functionality. Can add, replace and or modifies builtin Gramps options.
* '''[[Gramps_{{man version}}_Wiki_Manual_-_Reports_-_part_8#Quick_Views|Quickreport'''/'''Quickview]]''' (QUICKREPORT) - a view that you can run by right-clicking on object, or if a person quickview, then through the Quick View Gramplet
* '''[[Gramps_{{man version}}_Wiki_Manual_-_Reports_-_part_1|Report]]''' (REPORT) - adds a new output report / includes '''Website''' - output a static genealogy website based on your Gramps Family Tree data.
* '''[[Gramps_{{man version}}_Wiki_Manual_-_Filters#Add_Rule_dialog|Rule]]''' (RULE) - adds new [[Gramps_Glossary#filter|filter]] rules. {{new|5.1}}
* '''[[Gramps_{{man version}}_Wiki_Manual_-_Tools|Tool]]''' (TOOL) - adds a utility that helps process data from your family tree.
* '''Doc creator''' (DOCGEN)
* '''Relationships''' (RECALC)
* '''Sidebar''' (SIDEBAR)
* '''[[Database_Backends|Database]]''' (DATABASE) - add support for another database backend. {{new|5.0}}
* '''Thumbnailer''' (THUMBNAILER) {{new|5.2}}
* '''Citation formatter''' (CITE) {{new|5.2}}

==Writing an addon==
Writing an addon is fairly straightforward if you have just a little bit of Python experience. And sharing your addon is the right thing to do. The general steps to writing an addon and sharing your own addons are:

# [[#Develop_your_addon|Develop your addon]]
# [[#Create_a_Gramps_Plugin_Registration_file|Create a Gramps Plugin Registration file (.gpr.py)]]
# [[#internationalization|Invite translation of your addon]] into multiple natural languages
# [[#Package_your_addon|Package your addon]]
# [[#List_and_document_your_addon_on_the_wiki|Document your addon]] and publish it to the addon list
# [[#List_your_addon_in_the_Gramps_Plugin_Manager|Register your addon with the Plugin Manager]]
# [[#Announce_the_addon|Announce it on the Gramps Forum]] - Let users know it exist and how to use it.
# [[#Support_it_through_issue_tracker|Support it through the issue tracker]]
# [[#Maintain_the_code_as_Gramps_continues_to_evolve|Maintain the code]] as Gramps continues to evolve

We'll now expand upon each of these steps individually.

== Develop your addon ==

The [http://github.com/gramps-project/addons-source addons-source] repository holds the source code for the addons with branches holding the version for different gramps. If you are working on an addon for gramps for the current Gramps {{man version}} public release, be sure to use the maintenance/gramps{{Stable_branch}} git branch, as the default is master branch for the developmental pre-release. (Currently gramps 6.1, which is not the typical target for addons.)

Example commands are shown below referring to the public release rather than the master branch.

The developers are currently merging changes to the most recent maintenance branch into master as necessary, so you don't have to do anything for that unless you are in a hurry.

The [http://github.com/gramps-project/addons-source addons-source] git repository has the following structure, with the code for each addon in its own folder:

* /addons-source
** /''IndividualNameOfAddon1''
** /''IndividualNameOfAddon2''
** ...

The [http://github.com/gramps-project/addons addons] git repository holds built versions of the addons for each release of Gramps, and has the following structure:

* /addons
** [https://github.com/gramps-project/addons/tree/master/gramps42 /gramps42]
*** /download
*** /listings
** [https://github.com/gramps-project/addons/tree/master/gramps50 /gramps50]
*** /download
*** /listings
** [https://github.com/gramps-project/addons/tree/master/gramps51 /gramps51]
*** /download
*** /listings
** [https://github.com/gramps-project/addons/tree/master/gramps52 /gramps52]
*** /download
*** /listings
** [https://github.com/gramps-project/addons/tree/master/gramps{{Stable_branch}} /gramps{{Stable_branch}}]
*** /download
*** /listings

=== Get a local copy of Gramps and its addons ===

These steps show how to download the addon sources.

# Get an https://github.com/join account if you don't already have one.
# Request GIT write access for the https://github.com/gramps-project/addons-source project by emailing the [[Contact#Mailing_lists|gramps-devel mailing list]]
See also [[Brief_introduction_to_Git|git introduction]] for instructions on installing git and getting basic settings configured. Also [https://help.github.com/articles/generating-an-ssh-key/ Connecting to GitHub with SSH] will help with setting up credentials for GitHub.
To fully build and advertise a new addon will require local copies of the three repositories, the 'addons-source', 'addons' and the main Gramps source 'gramps'.

This wiki assumes that all three git repositories local locations are put into the same base directory and named with the repository names in order for the make.py script commands to work as shown. From the base directory, run the following commands to create a copy of each repository. If you want to use SSH;

git clone git@github.com:gramps-project/addons-source.git addons-source
git clone git@github.com:gramps-project/addons.git addons
git clone git@github.com:gramps-project/gramps.git gramps

or if you want to use the HTTPS protocol:

git clone <nowiki>https://github.com/gramps-project/addons-source.git</nowiki> addons-source
git clone <nowiki>https://github.com/gramps-project/addons.git</nowiki> addons
git clone <nowiki>https://github.com/gramps-project/gramps.git</nowiki> gramps

To switch to a local copy of the gramps{{Stable_branch}} maintenance branch:

cd addons-source
git checkout -b gramps{{Stable_branch}} origin/maintenance/gramps{{Stable_branch}}

or to work in the master branch:

cd addons-source
git checkout -b gramps61 origin/master

=== Other prerequisites ===
{{man warn|These instructions, the make.py script etc.|are designed to operate in a Linux environment. {{man menu|They won't work on Windows without modifications.}}}}
* Gramps uses Python version 3.2 or higher. You must have at least that version installed. If you have installed Gramps 4.2 or higher on your Linux system already, then a sufficient version of Python will be present. If you have more than one version of Python installed, then you must use the correct version for these scripts. On some systems, both Python 2.x and 3.x are installed. It is possible that the normal invocation of <code>python</code> starts up Python 2.x, and that to start up Python 3.x requires invoking with <code>python3</code> or <code>python3.4</code> etc. You can test the version by <code>python –version</code> or <code>python3 –version</code>. If this is so, replace any usage of 'python' in the examples below with the appropriate invocation.
* The make.py used in construction of the addons requires that the LANGUAGE environment variable be set to 'en_US.UTF-8'.
* The make.py used in construction of the addons requires that the GRAMPSPATH environment variable be set to your path to the Gramps source tree.
* intltool must be installed;
: <code>sudo apt-get install intltool</code>

For example if your home directory is '/home/name' and you use the suggested path names, use
: <code>GRAMPSPATH=/home/name/gramps LANGUAGE='en_US.UTF-8' python3 make.py ...</code>
to replace the <code>./make.py</code> in the examples below.

=== Create your addon subdirectory ===
* Make a new project directory in addons-source:
: <code>mkdir NewProjectName</code>

===Follow the development API for your tool===
Create your NewProjectName.py and NewProjectName.gpr.py files.

Follow the development API for your tool, [[Report-writing_tutorial|report]], view, or [[Gramplets development]]. Place all of your associated .py, .glade, etc. files in this directory. For general information on Gramps development see [[Portal:Developers]] and [[Writing a plugin|Writing a Plugin]] specifically.

=== Test your addon as you develop ===

{{man warn|{{bug|10436}} Symlinks to folders in gramps plugin dir are not scanned}}

To test your addon as you develop it is suggested that you copy your NewProjectName plugin into your Gramps user plugin directory from your addon development directory, prior to testing. Or just edit in the Gramps user plugin directory until it is ready to publish, then copy back to your addon development directory.

Your installed Gramps will search this folder (and subdirectories) for .gpr.py files, and add them to the plugin list.

If you have code that you want to share between addons, you don't need to do anything special. Gramps adds each directory in which a .gpr.py is found onto the PYTHONPATH which is searched when you perform an import. Thus "import NewProjectName" will work from another addon. You should always make sure you name your addons with a name appropriate for Python imports.

=== Commit your changes ===
To commit your changes so that others can see your addon source.

* Remove the files using the ''clean'' command that should not be added to GitHub (eg files(template.pot/ locale etc)):
: <code>./make.py gramps{{Stable_branch}} clean NewProjectName</code>
* Add the project to the repository:
: <code>git add NewProjectName</code>
* Commit it with an appropriate message
: <code>git commit -m "A message describing what this addon is"</code>

Before committing additional edits to your addon, you should:

* to make sure that outside changes do not affect your commit
: <code>git pull --rebase</code>
* only the files you changed should be in this list
: <code>git status</code>
* Commit it with an appropriate message
: <code>git commit -m "A message describing the changes"</code>

If you have been given 'push' rights to GitHub 'gramps-project/addons-source', and when you are sure you are done and want to publish to the repository:

* to make sure that outside changes do not affect your commit
: <code>git pull --rebase</code>
: <code>git push origin gramps{{Stable_branch}}</code>

Also you may want to [[Addons_development#Package_your_addon |Package your addon]] so it can be downloaded via the plugin manager.

=== Config ===

Some addons may want to have persistent data (data settings that remain between sessions). You can handle this yourself, or you can use Gramps' builtin configure system.

At the top of the source file of your addon, you would do this:

from config import config as configman
config = configman.register_manager("grampletname")
# register the values to save:
config.register("section.option-name1", value1)
config.register("section.option-name2", value2)
...
# load an existing file, if one:
config.load()
# save it, it case it didn't exist:
config.save()

This will create the file "grampletname.ini" and put in the same directory as the addon. If the config file already exists, it remains intact. The natural location for <code>.ini</code> files would be in the directory in which the addon is installed. (Using the main <code>gramps.ini</code> file for addon preferences could potentially lead to a conflict between addons.) Other locations and file formats are possible. [https://gramps.discourse.group/t/add-option-for-boolean-options-in-gramplet/6371/19 The Gramps architect recommends leaving this decision to the addon developer].

In the addon, you can then:

x = config.get("section.option-name1")
config.set("section.option-name1", 3)

and when this code is exiting, you might want to save the config. In a Gramplet that would be:

def on_save(self):
config.save()

If your code is a system-level file, then you might want to save the config in the Gramps system folder:

config = configman.register_manager("system", use_config_path=True)

This, however, would be rare; most .ini files would go into the plugins directory.

In other code that might use this config file, you would do this:

from config import config as configman
config = configman.get_manager("grampletname")
x = config.get("section.option-name1")

=== Localization ===

For general help on translations in Gramps, see [[Coding for translation]]. However, that will only use translations that come with Gramps, or allows you to contribute translations to the Gramps core. To have your own managed translations that will be packaged with your addon, read the rest of this page.
Note that these instructions will only work for Python strings, if you have a glade file, it will not get translated.

For any addon which you have translations into other languages, you will need to add a way to retrieve the translation. You need to add this to the top of your NewProjectName.py file:

from gramps.gen.const import GRAMPS_LOCALE as glocale
_ = glocale.get_addon_translator(__file__).gettext

Then you can use the standard "_()" function to translate phrases in your addon.

You can use one of a few different types of translation functions:

# gettext
# lgettext
# ngettext
# lngettext
# sgettext

These have become obsolete in Gramps 4; gettext, ngettext, and sgettext always return translated strings in unicode for consistent portability between Python 2 and Python3.

See the [http://docs.python.org/3/library/gettext.html#the-gnutranslations-class python documentation] for documentation of gettext and ngettext. The "l" versions return the string encoded according to the [http://docs.python.org/3/library/locale.html#locale.setlocale currently set locale]; the "u" versions return unicode strings in Python2 and are not available in Python 3.

'''sgettext''' is a Gramps extension that filters out clarifying comments for translators, such as
_("Remaining names | rest")
Where "rest" is the English string that we want to present and "Remaining names" is a hint for translators.

==== Commands to compile translations ====

To build and compile translations for all projects to their download/Addon.addon.tgz files:

: <code>python3 make.py gramps{{Stable_branch}} build all</code>

To compile translations for all projects :

: <code>python3 make.py gramps{{Stable_branch}} compile all</code>

== Create a Gramps Plugin Registration file ==

First, create the NewProjectName.gpr.py file. The registration takes this general form:

<pre>
register(PTYPE,
gramps_target_version = "6.0",
version = "1.0.0",
ATTR = value,
)
</pre>

[https://github.com/gramps-project/gramps/blob/master/gramps/gen/plug/_pluginreg.py#L76 PTYPE] values include: TOOL, GRAMPLET, REPORT, QUICKVIEW (formerly QUICKREPORT), IMPORT, EXPORT, DOCGEN, GENERAL, MAPSERVICE, VIEW, RELCALC, SIDEBAR, DATABASE, RULE, THUMBNAILER, and CITE.

ATTR depends on the PTYPE. But you must have '''gramps_target_version''' and addon '''version'''. '''gramps_target_version''' should be a string of the form "X.Y" version number matching Gramps X major, Y minor integer. '''version''' is a string of the form "X.Y.Z" representing the version of your addon. X, Y, and Z should all be integers.

Be sure to include attributes for author name(s) and email(s) in the form of an array of comma-separated strings.

There is an additional set of attributes, '''maintainers''' and '''maintainers_email'''. {{new|5.2}} If you, the author, are also the maintainer it will be identical to the author attributes, but you may also designate a maintainer, in which case the maintainer will become the primary point of contact.

Here is a sample Tool GPR file:

<pre>
register(TOOL,
id = 'AttachSource',
name = _("Attach Source"),
description = _("Attaches a shared source to multiple objects."),
version = '1.0.0',
gramps_target_version = '6.0',
status = STABLE,
fname = 'AttachSourceTool.py',
authors = ["Douglas S. Blank"],
authors_email = ["doug.blank@gmail.com"],
maintainers = ["Douglas S. Blank"],
maintainers_email = ["doug.blank@gmail.com"],
category = TOOL_DBPROC,
toolclass = 'AttachSourceWindow',
optionclass = 'AttachSourceOptions',
tool_modes = [TOOL_MODE_GUI]
)
</pre>

You can see examples of the kinds of addons [https://github.com/gramps-project/gramps/plugins here] (for example, see [https://github.com/gramps-project/gramps/plugins/drawreport/drawplugins.gpr.py gramps/plugins/drawreport/drawplugins.gpr.py]) and see the full documentation in the [https://github.com/gramps-project/gramps/blob/3f0db9303f29811b43325c30149c8844c7ce24b6/gramps/gen/plug/_pluginreg.py#L23 master/gramps/gen/plug/_pluginreg.py] comments and docstrings.

Note that this .gpr.py will automatically use translations if you have them (see below). That is, the function "_" is predefined to use your locale translations; you only need to mark the text with _("TEXT") and include a translation of "TEXT" in your translation file. For example, in the above example, _("Attach Source") is marked for translation. If you have developed and packaged your addon with translation support, then that phrase will be converted into the user's language.

=== Report plugins ===
The possible report categories are ([https://github.com/gramps-project/gramps/blob/892fc270592095192947097d22a72834d5c70447/gramps/gen/plug/_pluginreg.py#L141-L149 gen/plug/_pluginreg.py]):
<pre>
#possible report categories
CATEGORY_TEXT = 0
CATEGORY_DRAW = 1
CATEGORY_CODE = 2
CATEGORY_WEB = 3
CATEGORY_BOOK = 4
CATEGORY_GRAPHVIZ = 5
CATEGORY_TREE = 6
REPORT_CAT = [ CATEGORY_TEXT, CATEGORY_DRAW, CATEGORY_CODE,
CATEGORY_WEB, CATEGORY_BOOK, CATEGORY_GRAPHVIZ, CATEGORY_TREE]
</pre>

Each report category has a set of standards and interface. The categories CATEGORY_TEXT and CATEGORY_DRAW use the Document interface of Gramps. See also [[Report API]] for a draft view on this.

The application programming interface or API for reports is treated at [[Report-writing_tutorial]]. For general information on Gramps development see [[Portal:Developers]] and [[Writing a plugin|Writing a Plugin]] specifically.

=== General plugins ===

The plugin framework also allows you to create generic plugins for use. This includes the ability to create libraries of functions, and plugins of your own design.

==== Example: A library of functions ====

In this example, a file name library.py will be imported at time of registration (when Gramps starts):

<pre>
# file: library.gpr.py

register(GENERAL,
id = 'My Library',
name = _("My Library"),
description = _("Provides a library for doing something."),
version = '1.0',
gramps_target_version = '6.0',
status = STABLE,
fname = 'library.py',
load_on_reg = True,
)
</pre>

The code in the file library.py will be imported when Gramps begins. You can access the loaded module in other code by issuing an "import library" as Python keeps track of files already imported. However, the amount of useful code that you can run when the program is imported is limited. You might like to have the code do something that requires a dbstate or uistate object, and neither of these is available when just importing a file.

If "load_on_reg" was not True, then this code would be unavailable until manually loaded. There is no automatic mechanism in Gramps to load GENERAL plugins automatically.

In addition to importing a file at startup, one can also run a single function inside a GENERAL plugin, and it will be passed the dbstate, the uistate, and the plugin data. The function must be called "load_on_reg", and take those three parameters, like this:

<pre>
# file: library.py

def load_on_reg(dbstate, uistate, plugin):
"""
Runs when plugin is registered.
"""
print("Hello World!")
</pre>

Here, you could connect signals to the dbstate, open windows, etc.

Another example of what one can do with the plugin interface is to create a general purpose plugin framework for use by other plugins. Here is the basis for a plugin system that:

* allows plugins to list data files
* allows the plugin to process all of the data files

First, the gpr.py file:

<pre>

register(GENERAL,
id = "ID",
category = "CATEGORY",
load_on_reg = True,
process = "FUNCTION_NAME",
)
</pre>

This example uses three new features:

# GENERAL plugins can have a category
# GENERAL plugins can have a load_on_reg function that returns data
# GENERAL plugins can have a function (called "process") which will process the data

If you (or someone else) create additional general plugins of this category, and they follow your load_on_reg data format API, then they could be used just like your original data. For example, here is an additional general plugin in the 'WEBSTUFF' category:

<pre>
# anew.gpr.py

register(GENERAL,
id = 'a new plugin',
category = "WEBSTUFF",
version = '1.0',
gramps_target_version = '6.0',
data = ["a", "b", "c"],
)
</pre>

This doesn't have load_on_reg = True, nor does it have a fname or process, but it does set the data directly in the .gpr.py file. Then we have the following results:

<pre>
>>> from gui.pluginmanager import GuiPluginManager
>>> PLUGMAN = GuiPluginManager.get_instance()
>>> PLUGMAN.get_plugin_data('WEBSTUFF')
["a", "b", "c", "Stylesheet.css", "Another.css"]
>>> PLUGMAN.process_plugin_data('WEBSTUFF')
["A", "B", "C", "STYLESHEET.CSS", "ANOTHER.CSS"]
</pre>

=== Registered GENERAL Categories ===

The following are the published secondary plugins API's (type GENERAL, with the following categories):

==== WEBSTUFF ====

A sample gpr.py file:

<pre>
# stylesheet.gpr.py

register(GENERAL,
id = 'system stylesheets',
category = "WEBSTUFF",
name = _("CSS Stylesheets"),
description = _("Provides a collection of stylesheets for the web"),
version = '1.0',
gramps_target_version = '6.0',
fname = "stylesheet.py",
load_on_reg = True,
process = "process_list",
)
</pre>

Here is the associated program:

<pre>
# file: stylesheet.py

def load_on_reg(dbstate, uistate, plugin):
"""
Runs when plugin is registered.
"""
return ["Stylesheet.css", "Another.css"]

def process_list(files):
return [file.upper() for file in files]
</pre>

==== Filters ====

For example:

<pre>
register(GENERAL,
category="Filters",
...
load_on_reg = True
)
</pre>

<pre>
def load_on_reg(dbstate, uistate, plugin):
# returns a function that takes a namespace, 'Person', 'Family', etc.

def filters(namespace):
print("Ok...", plugin.category, namespace, uistate)
# return a Filter object here
return filters
</pre>



== List the Prerequistes your addon depends on ==

''In your gpr file, you can have a line like:

<code>depends_on = ["libwebconnect"],</code>

which is a list of plug-in identifier's from other gpr files. This example will ensure that [[Addon:Web_Connect_Pack#Prerequisites|libwebconnect]] is loaded before your addon. If that ID can't be found, or you have a cycle (circular import), then your addons won't be loaded. The Gramps architect summarizes: "The depends_on list is used to specify other plugins which the plugin depends on. These will be installed automatically."

example code used in the Addon:Web_Connect_Pack that references libwebconnect Prerequistes [https://github.com/gramps-project/addons-source/blob/1304b65a7d758bfe17339c26260473ac3e9c4061/RUWebConnectPack/RUWebPack.gpr.py#L17 RUWebPack.gpr.py#L17]

This means that common Prerequisites can be shared between addons. So that code can be maintained in its own gpr/addon file instead of synchronizing the maintenance of multiple copies across various silos.

Additional requirements properties were implemented in the [[Gramplets_development#Register_Options|Registration Options]] to specify prerequisites for plug-ins: [https://github.com/gramps-project/gramps/blob/0f8d4ecd429431b4df64910962f8764af9ff1766/gramps/gen/plug/_pluginreg.py#L689-L719 requires_mod (modules), requires_gi (GObject introspection) and requires_exe (executable).] {{new|5.2}}



== Get translators to translate your addon into multiple languages ==

If you [[#Localization|designed for localization]], the addon will begin supporting a single language. Make your addon inviting for volunteers to translate it into their native language.
* Initialize and update the <code>template.pot</code> for your addon:
: <code>cd ~/addons-source</code>
: <code>./make.py gramps{{Stable_branch}} init NewProjectName</code>
* You should edit the header of <code>template.pot</code> with your information, so it gets copied to individual language files.
* Initialize a language for your addon (say French, fr):
: <code>./make.py gramps{{Stable_branch}} init NewProjectName fr</code>
* Update it from gramps and other addons:
: <code>./make.py gramps{{Stable_branch}} update NewProjectName fr</code>
* Edit the translations file manually:
: <code>/NewProjectName/po/fr-local.po</code>
* Compile the language:
: <code>./make.py gramps{{Stable_branch}} compile NewProjectName</code>
* Add or update your local language file, and commit changes:
: <code>git add NewProjectName/po/fr-local.po</code>
: <code>git commit NewProjectName/po/fr-local.po -m "Added fr po file"</code>
* If you have been given 'push' rights to GitHub 'gramps-project/addons-source', then;
: <code>git push origin gramps{{Stable_branch}}</code>

{{man tip|From Gramps 6.x translations can be done on Weblate. This is experimental. Initial testing has appeared successful, but please let us know if you notice any problems. The Weblate Addons component contains aggregated translations for every addon.|https://hosted.weblate.org/projects/gramps-project/addons/}}

== Package your addon ==

To create a downloadable package:

: <code>./make.py gramps{{Stable_branch}} build NewProjectName</code> or
: <code>./make.py gramps61 build NewProjectName</code> for the master branch.

This will automatically include the following files in your build:

* *.py
* *.glade
* *.xml
* *.txt
* locale/*/LC_MESSAGES/*.mo

Starting with Gramp 5.0, if you have additional files beyond those listed above, you should create a MANIFEST file in the root of your addon folder listing the files (or pattern) one per line, like this sample MANIFEST file. Include the Addon folder name in each line.

<pre>
Addon/README.md
Addon/extra_dir/*
Addon/help_files/docs/help.html
</pre>

{{man note|Note:|Running the command <code>make.py xxx build</code> will increment the third number in your dotted version number of all addons in the <code>*.gpr.py</code> file. Consider this number to be a "build number".}}

This will leave your 'addons-source' with untracked changes according to git. You should delete the 'NewProjectName/locale' directory. The updated 'NewProjectName/NewProjectName.gpr.py ' is ready to add and commit the next time you make other changes.
: <code>rm –rf –v 'NewProjectName/locale'</code>

Then add the package to GitHub:

<pre> cd '~/addons'
git add gramps{{Stable_branch}}/download/NewProjectName.addon.tgz
git commit -m "Added new plugin: NewProjectName"</pre>
or (for the master branch);
<pre> cd '~/addons'
git add gramps61/download/NewProjectName.addon.tgz
git commit -m " Added new plugin: NewProjectName"</pre>

== List your addon in the Gramps Plugin Manager==

{{man warn|Gramps needs to have been built|Make sure you have already built gramps{{Stable_branch}} or master. Change to the appropriate git branch in your gramps directory, and run <code>python3 setup.py build</code> See [[Linux:Build_from_source]]}}

To create a listing:

: <code>cd '~/gramps-addons'</code> or wherever you have built your addon
: <code>GRAMPSPATH=path/to/your/gramps/install ./make.py gramps{{Stable_branch}} listing NewProjectName</code>
or (for the master branch);
: <code>cd '~/gramps-addons'</code> or wherever you have built your addon
: <code>GRAMPSPATH=path/to/your/gramps/install ./make.py gramps61 listing NewProjectName</code>

That will create a series of files in the <tt>../listings/</tt> directory.

Then add the updated listing to GitHub:

<pre> cd '~/addons'
git add gramps{{Stable_branch}}/listings/*
git commit -m "Added new plugin to listings: NewProjectName"</pre>
or (for the master branch);
<pre> cd '~/addons'
git add gramps61/listings/*
git commit -m " Added new plugin to listings: NewProjectName"</pre>

== List and document your addon on the wiki==

===List your addon===
Add a short description of your addon to the Addons list by editing the current release listing eg: [[6.0_Addons]] or if the addon is meant for a future release [[6.1_Addons]] when available.

==== Example addon template ====
Examine the listing for other addons and refer to the [[Addon list legend]] for details of on the meaning of each columns.
<pre>
|- 
|
|
|
|
|
|
|
|
|-
</pre>

===Document your addon===
Document the addon in the wiki using the page name format of {{man menu|Addon:NewProjectName}} examine the other addon support pages for the general format to use.
{{man tip|Hint on creating a new wiki page.|To create a new wiki page use the search box to search for the name of your page that doesn't exist then on the search results page you will be provided with a link to create the new page, by selecting and you can add your content}}

====Example addon article====
Consider including the following information:

<pre>

{{Third-party plugin}}


== Usage ==

=== Configure Options ===

==Features==

== Prerequisites ==

== Issues ==


[[Category:Addons]]
[[Category:Plugins]]
[[Category:Developers/General]]
</pre>

== Announce the addon ==
Join the [[Contact#Forum|Gramps Forum]] and announce it to the users with general information on why you created and how to use it.

== Support it through issue tracker ==

Become a user on the [https://gramps-project.org/bugs/view_all_bug_page.php Gramps MantisBT (Mantis BugTracker)].
and please check it regularly. There is no automated notification of issues (and possible feature requests) related to your addon when reported by users.

Users tend to not understand coding and they make assumptions. So be kind and guiding if a report is ambiguous or inaccurate. A negative remark from an addon developer or anyone can be very discouraging.

== Maintain the code as Gramps continues to evolve ==

{{man tip|When submitting an update the patch part of the version number MAJOR.MINOR.PATCH is updated during the addon build process e.g. 1.1.3 to 1.1.4|This means when your plugin has become part of the default gramps addons there is no need to run `make` yourself as it is part of the regular addon build process. You can find this step in [https://github.com/gramps-project/addons-source/blob/master/make.py#L125 addons-source/make.py].[https://gramps.discourse.group/t/should-addons-pr-include-version-number-update/2591]}}

Remember that Gramps addons exist for many reasons and there are many Gramps developers that do support addons in various ways (translations, triage, keeping in sync with master, download infrastructure, etc).

Some reasons why the addons exist; they provide:
* A quick way for anyone to share their work; the Gramps-project has never denied adding a addon.
* A method to continuously update and develop a stand-alone component, often before being officially accepted.
* A place for controversial plugins that will never be accepted into core, but are loved by many users (eg, Data Entry Gramplet).
* A place for experimental components to live.

== Example code adding common enhancements ==
* Copy all the Gramplet's output to a system clipboard via context pop-up menu : Enhancement request {{bug|11573}}, [https://github.com/gramps-project/gramps/pull/1014/commits/72012e13b4ca15caca4b7f36fdb9702c1fd470fd example pull]
* add a custom [[Gramps_Glossary#viewmode|View Mode]] toolbar icon via the <code>.gpr.py</code> : [https://github.com/gramps-project/gramps/pull/1017 Pull 1017 Discussion], [https://github.com/gramps-project/gramps/pull/1017/commits/76e41d546d6ec519dd78fbe07f663135b5c79351 example Pull]

= Resources =
* [[Brief_introduction_to_Git|Git introduction]]
* [[Getting started with Gramps development]]
* [[Portal:Developers]]
* [https://gramps-project.org/docs/gen/gen_plug.html?highlight=include_in_listing#module-gramps.gen.plug._pluginreg gramps.gen.plug._pluginreg Registration Module]
* [https://github.com/gramps-project/gramps/blob/master/gramps/gen/plug/_pluginreg.py#L55 PluginData in _pluginreg.py]

;Gramps Addons site for Gramps 4.2 and newer
* https://github.com/gramps-project/addons-source - Source code (Git)
* https://github.com/gramps-project/addons - downloadable .tgz files
;Gramps Addons site for Gramps 4.1 and older
* For 4.1.x and earlier, see [[Addons development old]].

= Addon Development Tutorials and Samples =

* [[Gramplets development|Develop an Addon Gramplet]] (add a [https://gramps.discourse.group/t/looking-for-an-example-of-a-gramplet-with-a-custom-filter-configuration-option/5967 custom filtering option])
* [[Develop_an_Addon_Rule|Develop an Addon Rule]] for custom filters
* [[Develop_an_Addon_Tool|Develop an Addon Tool]]
* [[Quick_Views|Develop an Addon Quick View]]
* Develop an Addon Report ([[Report-writing_tutorial|tutorial]], [https://gramps.discourse.group/t/sample-report-for-new-developers/3046 samples])
* [[Adapt_a_builtin_Report|Adapt a builtin Report]]

[[Category:Developers/General]]
[[Category:Developers/Tutorials]]
[[Category:Plugins]]
[[Category:Reports]]
[[Category:Gramplets]]
[[Category:Addons|*]]

Brief introduction to Git

2026-01-30T06:42:50Z

Codefarmer: SSH isn't required; link to Git's download instructions; minor re-wording

{{man tip|The development source code of Gramps is stored in the Git repository at GitHub.|https://github.com/gramps-project/gramps/}}
The Gramps project uses the [https://en.wikipedia.org/wiki/Git Git] version control system to help synchronize changes to source code from various developers, tracking changes, managing releases, etc. You are probably here because you want to do one of two things with Git; either:
* Download the latest maintenance source version or the development version, or else
* [[Brief_introduction_to_Git#Send_your_contribution_without_rights_to_push|Submit a Pull Request (PR)]] with the changes (if you don't have write access) or upload your changes (if you have write access to the repository).

== Install Git on your system ==
Follow steps on Git's web site to [https://git-scm.com/install/ install Git], then [[#Configure_Git_settings|configure your Git settings]].
===Linux===
* Debian/Ubuntu: <code>sudo apt-get install git</code>
* Fedora: <code>yum install git-core</code>
===Microsoft-Windows===
* Microsoft-Windows: Download git from here https://git-scm.com/download/win

===Apple Mac OS X===
* '''Mac OS X (Intel)''': Download git from here https://git-scm.com/download/mac
* '''Mac OS X (PPC)''': Although the git download is called '<code>[https://sourceforge.net/projects/git-osx-installer/files/ git-2.xx.x-intel-universal-mavericks.dmg]</code>', implying that this is a universal binary, in fact only the installer is universal, the binary to be installed in actually intel only. On a PPC you will need to build git manually. Follow the instructions here: http://jnorthr.wordpress.com/2013/03/29/building-a-git-client-1-8-2-on-apple-imac-ppc-osx-10-5-8/. I think you will also need some additional tools like 'msgfmt'. I don't think this is installed by the Apple development tool Xcode, but fortunately I have it either via fink which I installed some time ago, or via MacPorts which I installed more recently.

: Mac OS X (PPC) Eclipse. If you are using Eclipse on a PPC, then there may be missing components for installing the latest version of EGit, depending on your version of Eclipse. If you have the Helios version of Eclipse, then you will not be able to install the latest EGit because you will get ''requires 'org.eclipse.team.core 3.6.100' but it could not be found''. Installing EGit version 2.0 from http://download.eclipse.org/egit/updates-2.0 should work if you uncheck the EGit Import Support feature when selecting what to install. You will obviously lose the Import Support feature. See [http://stackoverflow.com/questions/15281273/dependency-fail-installing-egit-on-eclipse-indigo here]. You will probably need to do ''git config core.filemode false'' to get round [https://bugs.eclipse.org/bugs/show_bug.cgi?id=307560 this bug] as suggested [http://stackoverflow.com/questions/1257592/how-do-i-remove-files-saying-old-mode-100755-new-mode-100644-from-unstaged-cha here].

If you use Eclipse then will need to locally ignore the Eclipse files as suggested at section 4.2 [https://www.vogella.com/tutorials/EclipseGit/article.html#create-gitignore-file here].

cd ~/
touch .gitignore
echo ".metadata" >> .gitignore
echo ".project" >> .gitignore
echo ".pydevproject" >> .gitignore
echo "windows" >> .gitignore

=== Configure Git settings ===

Git includes your name and email address in commits. To configure them, use the following commands:
git config --global user.name "John Smith"
git config --global user.email john@example.com

Git will automatically convert line endings for you. Use the following settings:
git config --global core.autocrlf true # Windows
git config --global core.autocrlf input # Linux/Mac

Git can invoke your favorite editor for commit messages, rebasing etc.
git config --global core.editor "'C:\Program Files (x86)\Notepad++\notepad++.exe' -multiInst -notabbar -nosession -noPlugin" # Windows
git config --global core.editor "vim" # Linux

== Obtaining a copy of the Gramps repository ==

The description below is for a single working folder at <code>~/Gramps</code>. If you are working on a plugin, the folder name should be <code>addons-source</code> at the <nowiki>https://github.com/gramps-project/addons-source.git</nowiki>

===Using HTTPS Protocol===
To obtain a copy of the Gramps repository, type the following in the command line (doesn't require a GitHub account):
git clone <nowiki>https://github.com/gramps-project/gramps.git</nowiki> Gramps

You should see the downloading progress reported in your terminal.

===Using SSH Protocol===
If you have a GitHub account, use you can ssh if you wish, or continue to use HTTPS protocol with your GitHub credentials or a Personal Access Token:
git clone <nowiki>git@github.com:gramps-project/gramps.git</nowiki> Gramps

You will need a [https://help.github.com/articles/generating-ssh-keys/ SSH Key] in order to authenticate using this method. '''Before you accept any host keys, make sure you [https://help.github.com/articles/what-are-github-s-ssh-key-fingerprints/ verify the SSH fingerprint]''' of github.com.

You can check your connection by:
ssh -T git@github.com
which should return:
Hi <name>! You've successfully authenticated, but GitHub does not provide shell access.

Once the clone is complete, you have a local copy of the Gramps code with Git configured to use this as the 'origin'. You can see this by:
git remote -v
which should return:
origin <nowiki>https://github.com/gramps-project/gramps.git</nowiki> (fetch)
origin <nowiki>https://github.com/gramps-project/gramps.git</nowiki> (push)

If you have 'push rights' to the Gramps repository, (members of the 'developers' group have this), then you are good to go. If not, then you will have to establish your own github account and use that for a place to publish your contributions. This is not needed until (or unless) you desire to contribute more than a simple patch to Gramps.

You should sign up for an account on https://github.com. GitHub is free to use for public and open source projects like Gramps.
You should create a repository on github that can receive your pushed contributions. The examples below assume that is also called 'gramps'. See https://help.github.com/articles/creating-a-new-repository/

Once you have that set up, you should set up a second remote tied to your local repository.
My personal arrangement is to change the name of the original tie to the remote Gramps github repository to 'upstream' and make the tie to my personal github repository 'origin':
git remote set-url --push upstream <nowiki>cannot_push</nowiki>
git remote set-url --fetch upstream <nowiki>https://github.com/gramps-project/gramps.git</nowiki>
git remote set-url --push origin <nowiki>https://github.com/my-name/gramps.git</nowiki>
git remote set-url --fetch origin <nowiki>https://github.com/my-name/gramps.git</nowiki>
When done, you can check the results:
git remote -v
which should return:
origin <nowiki>https://github.com/my-name/gramps.git</nowiki> (fetch)
origin <nowiki>https://github.com/my-name/gramps.git</nowiki> (push)
upstream <nowiki>https://github.com/gramps-project/gramps.git</nowiki> (fetch)
upstream <nowiki>cannot_push</nowiki> (push)

== Branches ==
Branches are the particular group of code sources associated with a Gramps version, enhancement, bug fix etc.
When making changes to Gramps, it is important to understand where you are starting from (which version of Gramps) and what you are trying to do.

=== Types of branches ===
When you clone the Gramps repository, a branch called ''master'' will be created for you. This contains the latest development version of Gramps. Gramps maintains different branches in several categories:

* ''master'' - There is only one ''master'' branch. All new feature development happens in the ''master'' branch. New releases never come from the ''master'' branch.

* ''maintenance'' - There are many maintenance branches, though usually only one or two are active. A maintenance branch is created from the ''master'' branch when all the features for a release are complete. New features are not committed to maintenance branches. Releases only come from active maintenance branches; a branch is no longer active when no further releases are planned for it. Inactive branches should not have any changes committed to them. The purpose of maintenance branches is to allow the line of code to stabilize while new features are added in the ''master'' branch. In order to prevent regressions (fixed bugs reoccurring in later releases) the current maintenance branch is regularly merged into the ''master'' branch.

* ''geps'' - These are meant for development of [[Portal:Enhancement_Proposals|Gramps Enhancement Proposals]]. Most of the time GEPS are developed in the ''master'' branch. Occasionally a GEP will require extensive reworking or long periods when the code base is ususable. In these cases a branch in ''geps'' can be used as a temporary development area. Once the hard work is done the change should be merged into the trunk and the ''geps'' branch should be removed. ''geps'' branches should follow the naming convention ''gep-<###>-<descriptive text>'' e.g. ''gep-013-server''. Please read the [[#Working with development branches]] section for help with managing these branches.

Tags are created for each Gramps release. The first two digits of the Gramps version number are reserved to indicate the maintenance branch the code came from. The last digit indicates the revision from that maintenance branch. For example, 5.0.4 would indicate the 5th release from the 5.0 branch (5.0.0, 5.0.1, 5.0.2, 5.0.3, 5.0.4).

Here is a hypothetical example:
Imagine that the current version of Gramps is 8.3.2. A new series of features has been added in the ''master'' branch and are ready for release. A new maintenance branch is created from the ''master'' branch named 8.4 (or possibly 9.0 depending on the nature of the new features). New features continue to be added in the ''master'' branch that will not be included in the 8.4 series of releases, but will be included in the 8.5 series. Bug fixes continue to occur in the 8.4 branch until the code is deemed worthy of release. At that time, a release is tagged from the 8.4 maintenance branch and named 8.4.0. Some time after the release of 8.4.0, some bugs are found and fixed in the 8.4 maintenance branch. Those bug fixes are released as 8.4.1.

== Stable version ==

There are several versions of the Gramps source code in Git. The development branch for small changes and bug fixes is
''maintenance/gramps{{Stable_branch}}''

By default, the remote server you cloned the Gramps repository from is called ''origin'', unless you changed the setup as described above. In that case it is ''upstream''.

To see a list of branches on the server, type:

git remote show upstream

To create a local branch which tracks a branch on the server, use:

git checkout -b gramps{{Stable_branch}} upstream/maintenance/gramps{{Stable_branch}}

{{man warn|1=Warning|2=This sets the name of the local branch to "gramps{{Stable_branch}}" (not "maintenance/gramps{{Stable_branch}}"). This may cause problems when you come to "push" your changes back to the server, depending on the "push.default" configuration settings (see below). You can change the name of the local branch by "git branch -m old new" i.e.
git branch -m gramps{{Stable_branch}} maintenance/gramps{{Stable_branch}}}}

This is known as a "tracking" branch.

To list the available branches, type:

git branch

The current branch is marked by an asterisk.

To switch to another branch, type:

git checkout <branch>

To look at any stable release version, and create a new local branch off of it, type:

git checkout <tag> -b <new_local_branch_name>

The following configuration option simplifies pushing a branch back to the server:

git config --global push.default upstream

You can then use:

git push

{{man warn|1=Warning|2=This will push committed changes from '''all''' local branches, not just the one that is currently checked-out. If you want to ensure that only one branch is pushed, then use:
git push origin gramps{{Stable_branch}}:maintenance/gramps{{Stable_branch}}}}

While it is certainly possible to do your contributions directly in the particular branch you start from, whether it be 'master' 'maintenance/gramps{{Stable_branch}}' or something else, it is more usual to create a branch of your own for each significant change. That way you can work on each separately, and change from one to the other without getting the changes intermixed.

For example if you are creating a new report you might want to call the branch 'gen-report'. If you are basing this off of the 'master' branch, then you would start by:
git checkout master # this ensures your work is based on master branch
git checkout -b gen-report # this creates a new branch 'gen-report' based on master but separate.
You can create many such branches and switch between them with 'git checkout <yourbranch>' as long as you save your work via 'commit' (described below) before making the switch.

===Alternative approach===
For an alternative approach see [[Brief_introduction_to_Git#Multiple_Working_Folders|Multiple Working Folders]].

== Basic Work Flow ==

The basic work flow after you've checked out the repository is update, develop, commit, update again, push.
To update the current checked out Gramps branch (master in this case) from Gramps github, run

git pull --rebase upstream master
If you are working on a branch of your own creation ('mybranch'), based off of master, and currently have 'mybranch' checked out, I prefer to run
git fetch upstream # copies the latest stuff from Gramps on github
git rebase upstream/master # shift my work to be 'on top' of other peoples work

As a general rule ''always'' use <tt>git pull --rebase</tt> to avoid creating unnecessary merge commits. Note that one must have no uncommitted edits on that branch when running <tt>git pull</tt>.

The differences between "git pull" and git pull --rebase" is explained well [http://stackoverflow.com/a/3357174/2615612 here].

You make your changes next with your preferred editor, debugging the code locally.

To see exactly what you have changed from the original (master in this case):
git diff master
To see changes since your last commit:
git diff

To review your change files before a commit, type:

git status

To stage and commit your changes locally, use the following commands:

git add * # the '*' adds every changed file to the stage, or you can specify a single file
git commit

Which will bring up the default $EDITOR (or the editor you setup with 'git config' above) to create a commit message. If you are fixing a bug, the first line of the commit message should be the bug number and title, otherwise a brief statement of purpose. Skip a line and describe what you did.

* All developers should read Gramps [[Committing policies]]

If the commit is a minor change that can be described entirely in the subject, you can instead use:

git commit -am "message describing the nature of the change"

Try to keep your commits digestible and understandable. A large changeset can be broken into several commits that "tell a story" about how the changeset moves the program from its old behavior to its new one.

To push your changes to the Gramps repository, you need to have cloned the Gramps source code with ssh, and have push access to the Gramps repository (the Gramps admins can give you this, [[Contact|Brian Matherly or Nick Hall]]). If you don't have push access continue in the next section below. First update again to make sure that you can fast-forward the repository, then push:

git pull --rebase
git push

If someone else has made changes that interfere with yours, you will get a conflict error when you pull. You will have to resolve that conflict and re-commit (you can use <tt>git commit --amend</tt> if it affects only the last ''unpushed'' commit) before git will push successfully.

Since uploading is a potentially dangerous operation, most people do not obtain write access to the git repository. You can use one of two approaches to this, either make a 'patch' (useful for small bug fixes), or you can make a 'Pull Request' (PR).

See the [[Brief_introduction_to_Git#Making_a_patchfile|make a patchfile]] or [[Brief_introduction_to_Git#Making_a_PR|Making a PR]] sections for details.

:Also see: [[Getting started with Gramps master]].

=== Making a patchfile ===
When dealing with a patch, you create a new bug on the [https://www.gramps-project.org/bugs bug tracker] and attach a patch to it.

The [https://www.gramps-project.org/bugs bug tracker] has a drop down at the top right to allow a choice among the projects under the Gramps Bugtracker; the default project shown is '''All Projects'''. Choose the project '''Gramps''' and submit an issue.

A patchfile is a text file with your changes which can be sent by email to somebody, or posted/uploaded to the bug tracker (against a bug you are fixing or a feature request which you are solving for instance), etc...

These instructions tell how to make a patchfile against the ''master'' branch, so that your changes are added to the next major release of Gramps. (To make a patchfile against a branch the process is similar, with some slight changes.)

First create a new branch to work in:

git checkout -b fix

Then use your favorite editor to change whatever file(s) you want. Add the files you have changed to the staging area and commit them.

Obtain the latest changes from the server.

git checkout master
git pull --rebase

Next, rebase your fix again the ''master'' branch. This will ensure that your patch will apply cleanly.

git rebase master fix

This will leave you in the fix branch.

Finally, create a patchfile, using:

git format-patch master --stdout > fix.patch

You now have a patchfile that can be sent by email, or attached to a bug report. The patch can be applied using the 'git apply' command.


=== Making a Pull Request (PR) on Github ===

If your changes or submission is more substantial, (or you will be making lots of them), you are encouraged to use the PR (Pull Request) method of making submissions. PRs allow the developers to easily see your proposed changes, download them and test them outside of the main code base, and see the results of automated testing. Github also has a comments area for each PR that allows you to describe in detail what you are trying to achieve, and for others to respond to your work.

To make a PR, you must first 'push' your work to a publicly view-able repository. We will continue to assume that github is used for this, and that you have your own account set up with a 'gramps' (or 'addons-source') repository as your remote 'origin', as was described earlier.

Again, to minimize the chance of collisions with other peoples work;
git checkout mybranch # unless you are already there
git fetch upstream # copies the latest stuff from Gramps on github
git rebase upstream/master # shift my work to be 'on top' of other peoples work
If you have done multiple commits while working on you code and they don't really make sense separately or contain intermediate attempts that are not reflected in the final result, you should probably clean up your work. There are several ways to do this, but I like to use the 'interactive rebase'. Start with:
git log
which will list all the commits starting with the most recent. The list is potentially enormous, but you probably will only need to look at the first screen or so. (Type 'q' to quit) An example log is shown:
commit defcda798145769f89189b95b202d5d0067f59c1
Author: prculley <paulxxxx@gmail.com>
Date: Sat Dec 8 11:08:48 2016 -0600
messed up and need to fix this
commit 2359633198ef50072d2bb6ca25f923718fab02d8
Author: prculley <paulxxxx@gmail.com>
Date: Wed Dec 7 11:52:21 2016 -0600
bug 8333; fix merge issue with Person Tree View
commit 5ad32042c6f808918cbbf540091e52e4ac4a9b28
Author: Paul Franklin <pfxxxx@gmail.com>
Date: Wed Dec 21 22:24:48 2016 -0800
move two methods down slightly (to better check a forthcoming change)
Find the first commit ''after'' your own commits and copy (at least) the first 5-6 characters of the long hash string.
Then do an interactive rebase;
git rebase -i 5ad320
Something like the following should appear in your editor with your commits at the top:
pick 2359633 bug 8333; fix merge issue with Person Tree View
pick defcda7 messed up and need to fix this
#
# Rebase 5ad3204..defcda7 onto 5ad3204 (2 command(s))
#
# Commands:
# p, pick = use commit
# r, reword = use commit, but edit the commit message
# e, edit = use commit, but stop for amending
# s, squash = use commit, but meld into previous commit
# f, fixup = like "squash", but discard this commit's log message
# x, exec = run command (the rest of the line) using shell
# d, drop = remove commit
#
# These lines can be re-ordered; they are executed from top to bottom.
#
# If you remove a line here THAT COMMIT WILL BE LOST.
#
# However, if you remove everything, the rebase will be aborted.
#
# Note that empty commits are commented out
In the example above, I want to merge the two commits into a single one, and keep only the original commit message. So I use the 'f' option on the second pick (change the 'pick defcda7' to 'f defcda7'), save the file and exit the editor.

Once that is complete, you can finally push the results to github at your own account:
git push origin mybranch

The next stop is at github itself. Grab your web browser and navigate to your account and your repository and the 'branches' tab <nowiki>https://github.com/yourname/gramps/branches</nowiki>. You should see your newly 'pushed' branch ('mybranch') listed with a 'New Pull Request' button on the right.

You can then fill out the PR form. You might have to select the Gramps 'base' branch you are basing on if it is different than 'master', this will be evident if you see "Can’t automatically merge". Add any comments you have on your work. And push the 'Create Pull Request' button.

====Send your contribution without rights to push====

You can [https://help.github.com/articles/fork-a-repo/ fork] the Gramps repository and create a [https://help.github.com/articles/using-pull-requests/ pull request]. Otherwise check it into Git if you obtained the [[#Obtaining_a_copy_of_the_Gramps_repository|permission to do push]].

Since syncing a fork can create unwanted commits, you may need to [https://github.com/edx/edx-platform/wiki/How-to-Rebase-a-Pull-Request rebase] your pull request first. Remember to replace edx and master with the actual names of the remote repository (upstream) and the branch you're working on.

* [[Brief_introduction_to_Git#Making_a_Pull_Request_.28PR.29_on_Github|Making a Pull Request (PR) on Github]]

====To PR or not to PR====

Note from Nick Hall - 27 Feb 2024

Generally pull requests are preferred, but there are a few exceptions:

* Translations. Before Weblate, a translation maintainer was allowed to commit translation updates directly without a PR. This is still the case for addons. The reason behind this was that it was unlikely that the PR would be reviewed.
* Package maintenance. We allow package maintainers to make changes in the directory related to the package that they maintain.
* Releases. PRs are not required for commits relating to a release.
* Branch merges. I don’t make a PR when merging bug fixes from a maintenance branch into the master branch.

== Working with development branches ==

Creating branches with Git is quick and easy.

Here is a quick crib sheet:

=== Creating a branch ===

To create a branch from the ''master'' branch:

git checkout master
git branch gep-014-fab-feature

To make this branch available on the server use:

git push origin gep-014-fab-feature

=== Merging changes from the branch back into the ''master'' branch ===

When you are ready to merge your changes back into the ''master'' branch:

git rebase master
git checkout master
git merge gep-014-fab-feature
git push

=== Removing branches ===

It is important that branches are removed once they have been merged into the trunk or have been abandoned. To remove a branch:

git branch -d gep-014-fab-feature

To remove a branch from the server, use:

git push origin :gep-014-fab-feature

The developers reserve the right to remove branches that have been dormant for more than 1 year.

=== Applying a fix to another branch ===

If you write a fix for an old maintenance branch, you may need to also apply it to the current maintenance branch.

To apply a commit from the gramps42 branch to the gramps50 branch:
git checkout gramps50
git cherry-pick fix

Then you may have to fix things that could not be applied due to conflicts. The patch program would mark the conflicts with the <<<<<<, ======, and >>>>>> signs. You will then need to push your changes.

If you apply a small fix that applies cleanly to another branch, it can be done like this (assuming you've just committed the fix to gramps42 in a single commit):
git checkout gramps50
git diff gramps42^ gramps42 | git apply
If `git apply' fails, nothing will be changed in the working copy, and you can try to resolve the conflicts by cherry-picking, or manually saving the diff result, using the "patch" program, and resolving the conflicts.

=== Searching in a specific branch ===
The GUI search in GitHub only indexes the active branch in the code base. If you want to search for a string in a specific branch, use Git instead of the GUI.

Using issue {{bug|13345}} as an example, the following examples show how to search for a term in various branches. The output shows that v5.1.3 introduced a change related to that string:

> git grep "Default Person" master
master:NEWS:* Change GUI references to ‘Home Person’ instead of ‘Default Person’
master:po/pl.po:#~ “active person to the Default Person.”

> git grep "Default Person" v5.2.3
v5.2.3:NEWS:* Change GUI references to ‘Home Person’ instead of ‘Default Person’
v5.2.3:po/pl.po:#~ “active person to the Default Person.”

> git grep "Default Person" v5.1.6
v5.1.6:NEWS:* Change GUI references to ‘Home Person’ instead of ‘Default Person’
v5.1.6:po/pl.po:#~ “active person to the Default Person.”

> git grep "Default Person" v5.1.2
v5.1.2:po/pl.po:#~ “active person to the Default Person.”

> git grep "Default Person" v5.1.3
v5.1.3:NEWS:* Change GUI references to ‘Home Person’ instead of ‘Default Person’
v5.1.3:po/pl.po:#~ “active person to the Default Person.”

There are several options you can use with the grep command which you can see by adding “–help”.

=== Workflow ===

Before switching to another branch it is useful to remove untracked files created by the build process. You can do this with the following command:

git clean -dxf

== Useful Tips ==

=== Getting help ===

Git has excellent man pages. You can view the manual page for a Git command, by using one of the following:

git help <verb>
git <verb> --help
man git-<verb>

For example, to get help on the 'git log' command, type:

git help log

=== Configuration settings ===

You can set your default editor with:

git config --global core.editor <editor>

To enable colored command line output, use:

git config --global color.ui auto

=== Saving uncommitted work while you do something in another branch ===
Sometimes you are not ready to commit your work but you still want to do work in another branch.
You may want to read up on:
git worktree # used to have another copy of the repository in another directory of your machine.
git stash # used to temporarily 'stash' uncommitted work on a 'stack'
git stash pop # used to 'pop' the latest stashed item (can also be used to move uncommitted files to another branch if you forgot to switch before editing
git stash -p # interactive selection of stash items (if you want to stash some uncommitted work, but not other)

=== Checking out someone else's PR to test ===
On the github page for the PR, next to the 'Merge Pull Request' button, is a hotlink for 'command line instructions'; it gives the actual 'git checkout' line for this.

=== Making merges (when there are rebase conflicts) easier ===
A tool which shows a 3-way merge can be helpful in determining what needs to be done. First configure git for the tool of choice (kdiff3 for windows shown here):
git config --global merge.tool kdiff3
git config --global mergetool.kdiff3.cmd "C:/Program Files/KDiff3/kdiff3.exe" # Windows
git config --global --add mergetool.kdiff3.trustExitCode false
Then when a merge conflict comes up you can:
git mergetool
=== Some procedural recommendations ===

# Always do <code>git pull --rebase</code> before pushing changes to the server. If necessary get advice about handling conflicts.
# Always do <code>git status</code> and look for staged files that are unexpected or unintended. This is a *very important* sanity check.

;And here are a couple of incidental suggestions

* Avoid grouping unrelated changes; better to divide into separate commits for the following reasons: a better log entry; easier troubleshooting/reverting. (and probably more).

* Similar to above, it may be better to make small incremental changes than one big one (if possible). Interim changes should not introduce breakage, of course. For instance, if you change code in gramps/ and do associated translation changes in po/, you might want to commit the changes in po/ in a commit following the commit(s) with the changes in gramps/.

* logs are important -- please give some thought to the log message. All developers should read the [[Committing policies]].

=== Browse Git ===

An alternative to the command line tools to view the Git repository is the [https://github.com/gramps-project/gramps online interface].

== Multiple Working Folders ==
{{man note|Multiple Working Folders|This type of setup is uncommon.}}
Using a single working folder as described above entails context switching when developing across multiple branches. For example:
* develop and test changes on the gramps41 branch,
* commit or stash the changes,
* clean to remove untracked files created by the development process,
* checkout the master 'branch',
* build (python setup.py build),
* cherry pick the changes from the gramps41 branch into the master 'branch',
* test and if necessary develop the changes to master,
* commit or stash the changes.

If the changes are all OK, then they can pushed to the GitHub repository.

An alternative is to clone the GitHub repository for each branch, but although git saves local disk space by using hard links for locally cloned repositories, keeping the local repositories in sync is complex.

The problem is well explained [https://www.finik.net/2010/10/24/multiple-working-folders-with-single-git-repository/ here] as is the solution, which is to create copies of the working directories only.

This can be done using either the builtin <code>git worktree</code> command since Git 2.5.0 or by a script that is in the git 'contrib' directory [http://nuclearsquid.com/writings/git-new-workdir/ git-new-workdir] for older versions of Git. Note that <code>git worktree</code> supports windows out of the box.

===git-new-workdir===

Assuming that the directory structure would be:
~
+-Gramps
+-repository
+-.git
+- etc
+-gramps34
+-gramps40
+-gramps41
+-gramps42
+-gramps50
+-gramps51
+-gramps52
+-master

The approach would be:
* clone from the GitHub repository:

mkdir Gramps
cd Gramps
mkdir repository
cd repository
git clone git@github.com:gramps-project/gramps.git

* then create the various working copies:

# git-new-workdir path/to/repository path/to/new/workingdir branch
git-new-workdir ~/Gramps/repository ~/Gramps/gramps34 maintenance/gramps34
git-new-workdir ~/Gramps/repository ~/Gramps/gramps40 maintenance/gramps40
git-new-workdir ~/Gramps/repository ~/Gramps/gramps41 maintenance/gramps41
git-new-workdir ~/Gramps/repository ~/Gramps/gramps42 maintenance/gramps42
git-new-workdir ~/Gramps/repository ~/Gramps/gramps50 maintenance/gramps50
git-new-workdir ~/Gramps/repository ~/Gramps/gramps51 maintenance/gramps51
git-new-workdir ~/Gramps/repository ~/Gramps/gramps52 maintenance/gramps52
git-new-workdir ~/Gramps/repository ~/Gramps/master master

You will then need to build the source, but this only needs to be done once, and the 'clean' step is not needed. See [[Getting_started_with_Gramps_development#Run_Gramps_from_the_source| Run from source]] and [[Running_a_development_version_of_Gramps| running]] which describes the process for 'gramps 3.4 and before' as well as after. For example:

cd ~/Gramps/gramps41
python setup.py build

===git worktree===

{{stub}}

Although from Git 2.5 (Q2 2015) a replacement for contrib/workdir/git-new-workdir was [http://stackoverflow.com/questions/6270193/multiple-working-directories-with-git/30185564#30185564 builtin] to git, it is recommended that you use the 'recipe' above instead of the builtin, in order to ensure that the repository is in the right place, and in view of the warning below.

WARNING. Using the builtin 'git worktree' may not be supported by Eclipse (as at Dec 2017), see [https://bugs.eclipse.org/bugs/show_bug.cgi?id=477475 Bug 477475 - git 2.5 worktree support].

== git2cl ==
The Gramps project does not keep a ChangeLog file under source control. All change history is captured by git automatically when it is committed. A ChangeLog file is generated from the git commit logs before each release using [[Brief_introduction_to_SVN#How_to_use_git2cl|git2cl]]. Developers should take care to make useful commit log messages when committing changes to git. Please read the [[Committing policies]] for details.

=== How to use git2cl ===

Starting with Gramps 3.0.0, we no longer have a <tt>ChangeLog</tt> file.

Instead, the list of changes is generated automatically using the standard <tt>git2cl</tt> script.

Note that <tt>git2cl</tt> is not included in the base installation of Git. With a Debian-based distro such as Ubuntu, you can get <tt>git2cl</tt> as follows:

sudo apt-get install git2cl

There typically are two <tt>ChangeLog</tt> files needed for releases; one in the main directory, and one in the <tt>po</tt> directory. You can generate these files with the following commands:

git log gramps-4.0.1.. --pretty --numstat --summary --no-merges | git2cl > ChangeLog
git log gramps-4.0.1.. --pretty --numstat --summary --no-merges -- po | git2cl > po/ChangeLog

== External links ==

*[http://git-scm.com/ Git]
*[http://git-scm.com/book Git Book]
*[https://help.github.com/articles/generating-ssh-keys/ GitHub SSH Keys]
*[https://help.github.com/articles/what-are-github-s-ssh-key-fingerprints/ GitHub SSH Key Fingerprints]

[[Category:Developers/General|B]]

Addon:MediaBrowserGramplet

2025-08-20T19:11:26Z

Codefarmer: Incorrect help URL fixed with bug 13959

{{Third-party addon}}
[[File:MediaBrowserGramplet-detached-example-51.png|right|thumb|450px|Media "Browser Gramplet" - detached - example]]
The Media {{man label|Browser Gramplet}} addon shows details of a person linked media objects.

== Usage ==
* Appears under the name '''Browser''' Gramplet in the context menu to '''Add a gramplet'''
* gramplet can be added to the following categories: People, Relationships, Charts, Geography

==Issues==
* Github code [https://github.com/gramps-project/addons-source/tree/master/MediaBrowser MediaBrowser]

[[Category:Addons]]
[[Category:Plugins]]
[[Category:Gramplets]]
[[Category:Media]]

Gramps for Windows with MSYS2

2024-12-07T18:55:15Z

Codefarmer: Actually remove WinXP reference

{{man warn|1=Warning|2=Do not open your existing databases with the master branch, it might destroy your data, and will make it impossible to use the data in the stable version {{stable_branch}}. To try it out, export your database to a gramps xml file, eg <code>test_master.gramps</code>, create a new family tree in the master branch, and import this xml file. Alternatively you can [[Gramps_for_Windows_with_MSYS2#Keep_your_GRAMPSHOME_separate|Keep your GRAMPSHOME separate]]}}

How to use MSYS2 to run latest Gramps development version from source in 64-bit Windows.

==Install MSYS2==

From the MSYS2 home page https://www.msys2.org/ download the latest MSYS2 64-bit installer( msys2-x86_64-YYYYMMDD.exe ) from [https://repo.msys2.org/distrib/x86_64/ https://repo.msys2.org/distrib/x86_64/] and run it.

Install it in short path like <code>C:\msys64</code>

At the end of install select to run mingw64 shell eg: use the '''MSYS2 MINGW64''' shortcut.

===Update MSYS2===
First keep running the following command(multiple times) until it has updated the list of packages and updated all core packages nothing else to do:

<pre>
pacman -Syuu
</pre>

If core packages are updated you must close the mingw64 shell (forcefully with close button, not just typing exit on it) and then restart the mingw64 shell from the shortcut. Following a core update, run the update command again to update non-core packages.

===Install Gramps dependencies===
Start mingw64 shell and use '''pacman''' package manager to download and install Gramps dependencies

<pre>
pacman -S mingw-w64-x86_64-python3-bsddb3 mingw-w64-x86_64-gexiv2 mingw-w64-x86_64-ghostscript mingw-w64-x86_64-python3-cairo mingw-w64-x86_64-python3-gobject mingw-w64-x86_64-python3-icu mingw-w64-x86_64-iso-codes mingw-w64-x86_64-hunspell mingw-w64-x86_64-hunspell-en mingw-w64-x86_64-enchant
</pre>

To handle the following warning '''No intltool or version < 0.25.0, build_intl is aborting''' during the build later, install:
pacman -S perl-XML-Parser
pacman -S intltool

You will also need the following to run the test:
<pre>
pacman -S mingw-w64-x86_64-python3-lxml
pacman -S mingw-w64-x86_64-python3-jsonschema
</pre>
Some additional (optional) items needed for certain addons.
<pre>
pacman -S mingw-w64-x86_64-gtkspell3
pacman -S mingw-w64-x86_64-geocode-glib
pacman -S mingw-w64-x86_64-python3-pillow
</pre>

Install Git and Gcc.
<pre>
pacman -S msys/git
pacman -S msys/gcc
</pre>

The Genealogical Symbols preferences tab needs Python Fontconfig version 0.5 so we need to build it.
From a suitable build directory (I use ~/build)
<pre>
git clone https://github.com/Vayn/python-fontconfig.git
cd python-fontconfig/
git checkout e1b1751f52167184e0c
python3 setup.py install
</pre>

Install Graphviz. To run the Graph View addon also install goocanvas.
(If you run into a problem try the alternate instructions to install [[Gramps_for_Windows_with_MSYS2#Issue|Graphviz]])
<pre>
pacman -S mingw-w64-x86_64-graphviz
pacman -S mingw-w64-x86_64-goocanvas
</pre>

Install osmgpsmap for the Geography Views with the following command:
<pre>
pacman -S mingw-w64-x86_64-osm-gps-map
</pre>

==Install Gramps==
===Prepare source===
Create directory to store Gramps source in and go to it
<pre>
mkdir ~/grampsdev
cd ~/grampsdev
</pre>

===Download source===
Download Gramps master branch from source repository
<pre>
git init
git remote add -t master -f origin https://github.com/gramps-project/gramps.git
git checkout master
</pre>
Check which Gramps version is used
<pre>
git describe
</pre>
it should return something like:
<blockquote>
v5.0.0-alpha1-1024-g0919763f1
</blockquote>
===Setup source===
Before using Gramps you must set-it up.
 You just use '''setup build''' command not '''install''' one
<pre>
python3 setup.py build
</pre>
==Run Gramps==
Start mingw64 shell and go to directory where Gramps source reside
<pre>
cd ~/grampsdev
</pre>
Use python3 to start Gramps
 To check gramps version use "v" flag
<pre>
python3 Gramps.py -v
</pre>
It should return something like:
<pre>
Gramps Settings:
----------------
python : 3.5.3
gramps : 5.0.0-alpha1-0919763f1
gtk++ : 3.22.9
pygobject : 3.22.0
pango : 1.40.3
cairo : 1.15.4
pycairo : 1.1.10
osmgpsmap : 1.0
GExiv2 : 0.10
ICU : 57.1
PyICU : 1.9.3
o.s. : win32

Non-python dependencies:
------------------------
Graphviz : Graphviz not in system PATH
Ghostscr. : 9.20
</pre>
Run Gramps
<pre>
python3 Gramps.py
</pre>
==Building and updating MSYS2/MinGW packages==
===Install build tools===
<pre>
pacman -S --needed --noconfirm base-devel mingw-w64-x86_64-toolchain
</pre>
[https://github.com/Alexpux/MINGW-packages MINGW-packages recipes] are on GitHub so you can use git to clone it. If instead you want to access recipe one by one you can download it with Subversion so install it first
<pre>
pacman -S subversion
</pre>
We need a place to download and build from source code so we will create folder called "build" inside our home folder
<pre>
mkdir ~/build
</pre>
To prevent pacman to upgrade packages we rebuilt for our needs we can assign them to group '''gramps_fixed''' and add them to IgnoreGroup list.
Open in text editor file ''etc/pacman.conf'' (C:\MSYS2\etc\pacman.conf) and add line ''IgnoreGroup = gramps_fixed'' to ''options'' section.
<pre>
[options]
IgnoreGroup = gramps_fixed
</pre>
===db===
GrampsAIO uses Oracle Berkeley DB version 6.0.30 but MSYS2 have it at version 6.0.19 and most probably never update it to a newer version.
 Gramps will ask permission to downgrade database version at import of any family tree created with GrampsAIO bundle. To prevent that build right version of DB.
 ''Hard way'' (it can take some time to finish)
<pre>
cd ~/build
svn checkout https://github.com/bpisoj/MINGW-packages/branches/gramps5/mingw-w64-db
cd mingw-w64-db
MINGW_INSTALLS=mingw64 makepkg-mingw -sLf
pacman -U mingw-w64-x86_64-db-6.0.30-1-any.pkg.tar.zst
</pre>
'''The easy way doesn't work anymore! This is because the recent versions of Python have changed and we have to rebuild.'''
 Start ''msys2 shell'' and type (easy way):
<pre>
cd ~/build
wget https://github.com/bpisoj/MINGW-packages/releases/download/v5.0/mingw-w64-x86_64-db-6.0.30-1-any.pkg.tar.xz
pacman -U mingw-w64-x86_64-db-6.0.30-1-any.pkg.tar.xz
</pre>

===bsddb3===
As db version is changed then we have to rebuild Python bindings for Oracle Berkeley DB
 From ''msys2 shell'' (easy way):
<pre>
cd ~/build
wget https://github.com/bpisoj/MINGW-packages/releases/download/v5.0/mingw-w64-x86_64-python3-bsddb3-6.1.0-3.1-any.pkg.tar.xz
pacman -U mingw-w64-x86_64-python3-bsddb3-6.1.0-3.1-any.pkg.tar.xz
</pre>
Or hard way:
<pre>
cd ~/build
svn checkout https://github.com/bpisoj/MINGW-packages/branches/gramps5/mingw-w64-python-bsddb3
cd mingw-w64-python-bsddb3
MINGW_INSTALLS=mingw64 makepkg-mingw -sLf
pacman -U mingw-w64-x86_64-python3-bsddb3-6.1.0-3.1-any.pkg.tar.xz
</pre>

===gtk3===
[https://www.gtk.org/ GTK+] since version 3.20 drag-and-drop code has been rearchitected to move the drag cancel animation and most input handling into GDK, thereby dropping most of the platform-dependent code out of GTK (MSYS2 version of GTK is currently 3.22.10). This change is not yet present in Windows port of code so we have to use older GTK version 3.18 where it still works.
 Latest in gtk-3.18 branch is gtk-3.18.9 (previous versions of this branch have working dnd but have other bugs) so we build that.
* Easy way:
<pre>
cd ~/build
wget https://github.com/bpisoj/MINGW-packages/releases/download/v5.0/mingw-w64-x86_64-gtk3-3.18.9-1-any.pkg.tar.xz
pacman -U mingw-w64-x86_64-gtk3-3.18.9-1-any.pkg.tar.xz
</pre>
* Hard Way:
<pre>
cd ~/build
svn checkout https://github.com/bpisoj/MINGW-packages/branches/gramps5/mingw-w64-gtk3
cd mingw-w64-gtk3
MINGW_INSTALLS=mingw64 makepkg-mingw -sLf
pacman -U mingw-w64-x86_64-gtk3-3.18.9-1-any.pkg.tar.xz
</pre>

===graphviz===

As of 2019.09.17 package mingw-w64-osm-gps-map is available so all you have to do is:

<pre>
pacman -S mingw-w64-x86_64-graphviz
</pre>

Previously Graphviz was in MSYS2 MINGW-packages git repository but was not build-able at that time (2017-03-26) so it is not available via pacman.
We build latest version from Graphviz git repository by manually patching code in process so we can't yet provide PKGBUILD
* Easy way
As we use simple archive not real packages we need to make care that dependencies are satisfied
<pre>
pacman -S --needed mingw-w64-x86_64-cairo mingw-w64-x86_64-devil mingw-w64-x86_64-expat mingw-w64-x86_64-freetype mingw-w64-x86_64-glib2 mingw-w64-x86_64-gtk2 mingw-w64-x86_64-gtkglext mingw-w64-x86_64-fontconfig mingw-w64-x86_64-freeglut mingw-w64-x86_64-libglade mingw-w64-x86_64-libgd mingw-w64-x86_64-libpng mingw-w64-x86_64-libsystre mingw-w64-x86_64-pango mingw-w64-x86_64-poppler mingw-w64-x86_64-zlib mingw-w64-x86_64-libtool
</pre>
Next we download prebuilt archive and extract it
<pre>
cd ~/build
wget https://github.com/bpisoj/MINGW-packages/releases/download/v5.0/win64_graphviz_20170323.1842.tar.xz
tar xfv win64_graphviz_20170323.1842.tar.xz -C /
</pre>
After successful install we first need to configure it (from mingw64 shell)
<pre>
dot -c
</pre>
If no error is displayed everything is working fine and Graphviz registered their plugins.
We can check version with
<pre>
dot -V

dot - graphviz version 2.41.20170323.1842 (20170323.1842)
</pre>
<pre>
winpty dot -v

dot - graphviz version 2.41.20170323.1842 (20170323.1842)
libdir = "C:\MSYS2\mingw64\bin"
Activated plugin library: libgvplugin_dot_layout-6.dll
Using layout: dot:dot_layout
Activated plugin library: libgvplugin_core-6.dll
Using render: dot:core
Using device: dot:dot:core
The plugin configuration file: C:\MSYS2\mingw64\bin\config6
was successfully loaded.
render : cairo dot fig gd map pic pov ps svg tk vml vrml xdot
layout : circo dot fdp neato nop nop1 nop2 osage patchwork sfdp twopi
textlayout : textlayout
device : bmp canon cmap cmapx cmapx_np dot eps fig gd gd2 gif gv ico imap
imap_np ismap jpe jpeg jpg pdf pic plain plain-ext png pov ps ps2
svg svgz tga tif tiff tk vml vmlz vrml wbmp xdot xdot1.2 xdot1.4
loadimage : (lib) bmp eps gd gd2 gif ico jpe jpeg jpg pdf png ps svg xbm
</pre>
* Hard way (TODO)
====pygraphviz====
Needed for NetworkChart report (Third-party addon)
* Easy way:
<pre>
cd ~/build
wget https://github.com/bpisoj/MINGW-packages/releases/download/v5.0/mingw-w64-x86_64-python3-pygraphviz-1.4rc1-1-any.pkg.tar.xz
pacman -U mingw-w64-x86_64-python3-pygraphviz-1.4rc1-1-any.pkg.tar.xz
</pre>
* Hard way
download https://gramps-project.org/wiki/images/2/2b/Pygraphviz-1.4rc1.zip [[:File:Pygraphviz-1.4rc1.zip|(source here)]]

Unzip it into <code>~/build/pygraphviz-1.4rc1/</code>
<pre>
cd ~/build/pygraphviz-1.4rc1
MINGW_INSTALLS=mingw64 makepkg-mingw -sLf
pacman -U mingw-w64-x86_64-python3-pygraphviz-1.4rc1-0.0-any.pkg.tar.xz
</pre>
For NetworkChart report to work install also networkx package
<pre>
pacman -S mingw-w64-x86_64-python3-networkx
</pre>
For NetworkChart report to work install also pydotplus
<pre>
pip3 install pydotplus
</pre>

===osmgpsmap===
As of 2019.02.08 package mingw-w64-osm-gps-map is available so all you have to do is
<pre>
pacman -S mingw-w64-x86_64-osm-gps-map
</pre>
 Start '''msys2 shell''' (always build package recipes from msys2 shell)
Hard way:
<pre>
cd ~/build
svn checkout https://github.com/Alexpux/MINGW-packages/trunk/mingw-w64-osm-gps-map
cd mingw-w64-osm-gps-map
MINGW_INSTALLS=mingw64 makepkg-mingw -sLf
pacman -U mingw-w64-x86_64-osm-gps-map-1.1.0-2-any.pkg.tar.xz
</pre>

==Issue==
===Graphviz===
* No Graphviz see: [https://github.com/Alexpux/MINGW-packages/issues/737 MSYS2:Package request: graphviz]
** Marked as WIP see: https://github.com/Alexpux/MINGW-packages/tree/master/mingw-w64-graphviz

====Alternate method using Windows version of Graphviz====
Tested alternate method to use Windows version of Graphviz[http://felsin9.de/nnis/ghc-vis/installing-windows/]
{{man warn|Warning it is not advised for users to mix various libraries like the following it is a direct way to dll hell.|This way Gramps will use graphviz libs instead of MSYS2 ones and they are older and in much way incompatible with rest of Gramps dependencies. until Graphviz becomes available from MSYS2 directly this is an alternate method.}}

Download the current GraphViz ZIP archive from https://www.graphviz.org/download/ and extract it to C:\graphviz, so that it directly contains the directories bin, lib, share and so on.

From the msys2 prompt type:
<pre>
echo 'export PATH=/c/graphviz/bin:$PATH' >> ~/.bashrc
source ~/.bashrc
</pre>
Then type:

python3 Gramps.py -v

and Graphviz will be listed.

<pre>Non-python dependencies:
------------------------
Graphviz : 2.38
</pre>

==Install Python pip==
To install a working version of pip use the following steps:

<pre>
mkdir ~/scripts
cd ~/scripts
curl -O 'https://bootstrap.pypa.io/get-pip.py'
./get-pip.py
</pre>

Test that it works:

pip3 --version

If that succeeds you can now remove the installation script if wanted:

rm get-pip.py

==Keep your [[Gramps_{{man version}}_Wiki_Manual_-_Command_Line#GRAMPSHOME|GRAMPSHOME]] separate==
To keep your test family trees separate from your personal family trees you may want to use your MSYS2 home directory which you can set from mingw64 shell either:

On each run like:

GRAMPSHOME=~ python3 Gramps.py

If you want it persistent:

echo 'export GRAMPSHOME=~' >> ~/.profile
source ~/.profile

==See also==
* [[Running a development version of Gramps]]
* [https://sourceforge.net/p/gramps/mailman/message/35346200/ Gramps on WSL (Win10/Ubuntu 14.04/VcXsvr)]

[[Category:GEPS|M]]
[[Category:Developers/General]]

Gramps for Windows with MSYS2

2024-12-07T18:54:28Z

Codefarmer: Remove obsolete references to 32-bit build and Windows XP

{{man warn|1=Warning|2=Do not open your existing databases with the master branch, it might destroy your data, and will make it impossible to use the data in the stable version {{stable_branch}}. To try it out, export your database to a gramps xml file, eg <code>test_master.gramps</code>, create a new family tree in the master branch, and import this xml file. Alternatively you can [[Gramps_for_Windows_with_MSYS2#Keep_your_GRAMPSHOME_separate|Keep your GRAMPSHOME separate]]}}

How to use MSYS2 to run latest Gramps development version from source in 64-bit Windows.

==Install MSYS2==

{{man note|Installation restrictions|MSYS2 can't be installed on [https://en.wikipedia.org/wiki/File_Allocation_Table FAT* formatted disk partitions]. Current MSYS2 can't be installed on Windows XP anymore.}}

From the MSYS2 home page https://www.msys2.org/ download the latest MSYS2 64-bit installer( msys2-x86_64-YYYYMMDD.exe ) from [https://repo.msys2.org/distrib/x86_64/ https://repo.msys2.org/distrib/x86_64/] and run it.

Install it in short path like <code>C:\msys64</code>

At the end of install select to run mingw64 shell eg: use the '''MSYS2 MINGW64''' shortcut.

===Update MSYS2===
First keep running the following command(multiple times) until it has updated the list of packages and updated all core packages nothing else to do:

<pre>
pacman -Syuu
</pre>

If core packages are updated you must close the mingw64 shell (forcefully with close button, not just typing exit on it) and then restart the mingw64 shell from the shortcut. Following a core update, run the update command again to update non-core packages.

===Install Gramps dependencies===
Start mingw64 shell and use '''pacman''' package manager to download and install Gramps dependencies

<pre>
pacman -S mingw-w64-x86_64-python3-bsddb3 mingw-w64-x86_64-gexiv2 mingw-w64-x86_64-ghostscript mingw-w64-x86_64-python3-cairo mingw-w64-x86_64-python3-gobject mingw-w64-x86_64-python3-icu mingw-w64-x86_64-iso-codes mingw-w64-x86_64-hunspell mingw-w64-x86_64-hunspell-en mingw-w64-x86_64-enchant
</pre>

To handle the following warning '''No intltool or version < 0.25.0, build_intl is aborting''' during the build later, install:
pacman -S perl-XML-Parser
pacman -S intltool

You will also need the following to run the test:
<pre>
pacman -S mingw-w64-x86_64-python3-lxml
pacman -S mingw-w64-x86_64-python3-jsonschema
</pre>
Some additional (optional) items needed for certain addons.
<pre>
pacman -S mingw-w64-x86_64-gtkspell3
pacman -S mingw-w64-x86_64-geocode-glib
pacman -S mingw-w64-x86_64-python3-pillow
</pre>

Install Git and Gcc.
<pre>
pacman -S msys/git
pacman -S msys/gcc
</pre>

The Genealogical Symbols preferences tab needs Python Fontconfig version 0.5 so we need to build it.
From a suitable build directory (I use ~/build)
<pre>
git clone https://github.com/Vayn/python-fontconfig.git
cd python-fontconfig/
git checkout e1b1751f52167184e0c
python3 setup.py install
</pre>

Install Graphviz. To run the Graph View addon also install goocanvas.
(If you run into a problem try the alternate instructions to install [[Gramps_for_Windows_with_MSYS2#Issue|Graphviz]])
<pre>
pacman -S mingw-w64-x86_64-graphviz
pacman -S mingw-w64-x86_64-goocanvas
</pre>

Install osmgpsmap for the Geography Views with the following command:
<pre>
pacman -S mingw-w64-x86_64-osm-gps-map
</pre>

==Install Gramps==
===Prepare source===
Create directory to store Gramps source in and go to it
<pre>
mkdir ~/grampsdev
cd ~/grampsdev
</pre>

===Download source===
Download Gramps master branch from source repository
<pre>
git init
git remote add -t master -f origin https://github.com/gramps-project/gramps.git
git checkout master
</pre>
Check which Gramps version is used
<pre>
git describe
</pre>
it should return something like:
<blockquote>
v5.0.0-alpha1-1024-g0919763f1
</blockquote>
===Setup source===
Before using Gramps you must set-it up.
 You just use '''setup build''' command not '''install''' one
<pre>
python3 setup.py build
</pre>
==Run Gramps==
Start mingw64 shell and go to directory where Gramps source reside
<pre>
cd ~/grampsdev
</pre>
Use python3 to start Gramps
 To check gramps version use "v" flag
<pre>
python3 Gramps.py -v
</pre>
It should return something like:
<pre>
Gramps Settings:
----------------
python : 3.5.3
gramps : 5.0.0-alpha1-0919763f1
gtk++ : 3.22.9
pygobject : 3.22.0
pango : 1.40.3
cairo : 1.15.4
pycairo : 1.1.10
osmgpsmap : 1.0
GExiv2 : 0.10
ICU : 57.1
PyICU : 1.9.3
o.s. : win32

Non-python dependencies:
------------------------
Graphviz : Graphviz not in system PATH
Ghostscr. : 9.20
</pre>
Run Gramps
<pre>
python3 Gramps.py
</pre>
==Building and updating MSYS2/MinGW packages==
===Install build tools===
<pre>
pacman -S --needed --noconfirm base-devel mingw-w64-x86_64-toolchain
</pre>
[https://github.com/Alexpux/MINGW-packages MINGW-packages recipes] are on GitHub so you can use git to clone it. If instead you want to access recipe one by one you can download it with Subversion so install it first
<pre>
pacman -S subversion
</pre>
We need a place to download and build from source code so we will create folder called "build" inside our home folder
<pre>
mkdir ~/build
</pre>
To prevent pacman to upgrade packages we rebuilt for our needs we can assign them to group '''gramps_fixed''' and add them to IgnoreGroup list.
Open in text editor file ''etc/pacman.conf'' (C:\MSYS2\etc\pacman.conf) and add line ''IgnoreGroup = gramps_fixed'' to ''options'' section.
<pre>
[options]
IgnoreGroup = gramps_fixed
</pre>
===db===
GrampsAIO uses Oracle Berkeley DB version 6.0.30 but MSYS2 have it at version 6.0.19 and most probably never update it to a newer version.
 Gramps will ask permission to downgrade database version at import of any family tree created with GrampsAIO bundle. To prevent that build right version of DB.
 ''Hard way'' (it can take some time to finish)
<pre>
cd ~/build
svn checkout https://github.com/bpisoj/MINGW-packages/branches/gramps5/mingw-w64-db
cd mingw-w64-db
MINGW_INSTALLS=mingw64 makepkg-mingw -sLf
pacman -U mingw-w64-x86_64-db-6.0.30-1-any.pkg.tar.zst
</pre>
'''The easy way doesn't work anymore! This is because the recent versions of Python have changed and we have to rebuild.'''
 Start ''msys2 shell'' and type (easy way):
<pre>
cd ~/build
wget https://github.com/bpisoj/MINGW-packages/releases/download/v5.0/mingw-w64-x86_64-db-6.0.30-1-any.pkg.tar.xz
pacman -U mingw-w64-x86_64-db-6.0.30-1-any.pkg.tar.xz
</pre>

===bsddb3===
As db version is changed then we have to rebuild Python bindings for Oracle Berkeley DB
 From ''msys2 shell'' (easy way):
<pre>
cd ~/build
wget https://github.com/bpisoj/MINGW-packages/releases/download/v5.0/mingw-w64-x86_64-python3-bsddb3-6.1.0-3.1-any.pkg.tar.xz
pacman -U mingw-w64-x86_64-python3-bsddb3-6.1.0-3.1-any.pkg.tar.xz
</pre>
Or hard way:
<pre>
cd ~/build
svn checkout https://github.com/bpisoj/MINGW-packages/branches/gramps5/mingw-w64-python-bsddb3
cd mingw-w64-python-bsddb3
MINGW_INSTALLS=mingw64 makepkg-mingw -sLf
pacman -U mingw-w64-x86_64-python3-bsddb3-6.1.0-3.1-any.pkg.tar.xz
</pre>

===gtk3===
[https://www.gtk.org/ GTK+] since version 3.20 drag-and-drop code has been rearchitected to move the drag cancel animation and most input handling into GDK, thereby dropping most of the platform-dependent code out of GTK (MSYS2 version of GTK is currently 3.22.10). This change is not yet present in Windows port of code so we have to use older GTK version 3.18 where it still works.
 Latest in gtk-3.18 branch is gtk-3.18.9 (previous versions of this branch have working dnd but have other bugs) so we build that.
* Easy way:
<pre>
cd ~/build
wget https://github.com/bpisoj/MINGW-packages/releases/download/v5.0/mingw-w64-x86_64-gtk3-3.18.9-1-any.pkg.tar.xz
pacman -U mingw-w64-x86_64-gtk3-3.18.9-1-any.pkg.tar.xz
</pre>
* Hard Way:
<pre>
cd ~/build
svn checkout https://github.com/bpisoj/MINGW-packages/branches/gramps5/mingw-w64-gtk3
cd mingw-w64-gtk3
MINGW_INSTALLS=mingw64 makepkg-mingw -sLf
pacman -U mingw-w64-x86_64-gtk3-3.18.9-1-any.pkg.tar.xz
</pre>

===graphviz===

As of 2019.09.17 package mingw-w64-osm-gps-map is available so all you have to do is:

<pre>
pacman -S mingw-w64-x86_64-graphviz
</pre>

Previously Graphviz was in MSYS2 MINGW-packages git repository but was not build-able at that time (2017-03-26) so it is not available via pacman.
We build latest version from Graphviz git repository by manually patching code in process so we can't yet provide PKGBUILD
* Easy way
As we use simple archive not real packages we need to make care that dependencies are satisfied
<pre>
pacman -S --needed mingw-w64-x86_64-cairo mingw-w64-x86_64-devil mingw-w64-x86_64-expat mingw-w64-x86_64-freetype mingw-w64-x86_64-glib2 mingw-w64-x86_64-gtk2 mingw-w64-x86_64-gtkglext mingw-w64-x86_64-fontconfig mingw-w64-x86_64-freeglut mingw-w64-x86_64-libglade mingw-w64-x86_64-libgd mingw-w64-x86_64-libpng mingw-w64-x86_64-libsystre mingw-w64-x86_64-pango mingw-w64-x86_64-poppler mingw-w64-x86_64-zlib mingw-w64-x86_64-libtool
</pre>
Next we download prebuilt archive and extract it
<pre>
cd ~/build
wget https://github.com/bpisoj/MINGW-packages/releases/download/v5.0/win64_graphviz_20170323.1842.tar.xz
tar xfv win64_graphviz_20170323.1842.tar.xz -C /
</pre>
After successful install we first need to configure it (from mingw64 shell)
<pre>
dot -c
</pre>
If no error is displayed everything is working fine and Graphviz registered their plugins.
We can check version with
<pre>
dot -V

dot - graphviz version 2.41.20170323.1842 (20170323.1842)
</pre>
<pre>
winpty dot -v

dot - graphviz version 2.41.20170323.1842 (20170323.1842)
libdir = "C:\MSYS2\mingw64\bin"
Activated plugin library: libgvplugin_dot_layout-6.dll
Using layout: dot:dot_layout
Activated plugin library: libgvplugin_core-6.dll
Using render: dot:core
Using device: dot:dot:core
The plugin configuration file: C:\MSYS2\mingw64\bin\config6
was successfully loaded.
render : cairo dot fig gd map pic pov ps svg tk vml vrml xdot
layout : circo dot fdp neato nop nop1 nop2 osage patchwork sfdp twopi
textlayout : textlayout
device : bmp canon cmap cmapx cmapx_np dot eps fig gd gd2 gif gv ico imap
imap_np ismap jpe jpeg jpg pdf pic plain plain-ext png pov ps ps2
svg svgz tga tif tiff tk vml vmlz vrml wbmp xdot xdot1.2 xdot1.4
loadimage : (lib) bmp eps gd gd2 gif ico jpe jpeg jpg pdf png ps svg xbm
</pre>
* Hard way (TODO)
====pygraphviz====
Needed for NetworkChart report (Third-party addon)
* Easy way:
<pre>
cd ~/build
wget https://github.com/bpisoj/MINGW-packages/releases/download/v5.0/mingw-w64-x86_64-python3-pygraphviz-1.4rc1-1-any.pkg.tar.xz
pacman -U mingw-w64-x86_64-python3-pygraphviz-1.4rc1-1-any.pkg.tar.xz
</pre>
* Hard way
download https://gramps-project.org/wiki/images/2/2b/Pygraphviz-1.4rc1.zip [[:File:Pygraphviz-1.4rc1.zip|(source here)]]

Unzip it into <code>~/build/pygraphviz-1.4rc1/</code>
<pre>
cd ~/build/pygraphviz-1.4rc1
MINGW_INSTALLS=mingw64 makepkg-mingw -sLf
pacman -U mingw-w64-x86_64-python3-pygraphviz-1.4rc1-0.0-any.pkg.tar.xz
</pre>
For NetworkChart report to work install also networkx package
<pre>
pacman -S mingw-w64-x86_64-python3-networkx
</pre>
For NetworkChart report to work install also pydotplus
<pre>
pip3 install pydotplus
</pre>

===osmgpsmap===
As of 2019.02.08 package mingw-w64-osm-gps-map is available so all you have to do is
<pre>
pacman -S mingw-w64-x86_64-osm-gps-map
</pre>
 Start '''msys2 shell''' (always build package recipes from msys2 shell)
Hard way:
<pre>
cd ~/build
svn checkout https://github.com/Alexpux/MINGW-packages/trunk/mingw-w64-osm-gps-map
cd mingw-w64-osm-gps-map
MINGW_INSTALLS=mingw64 makepkg-mingw -sLf
pacman -U mingw-w64-x86_64-osm-gps-map-1.1.0-2-any.pkg.tar.xz
</pre>

==Issue==
===Graphviz===
* No Graphviz see: [https://github.com/Alexpux/MINGW-packages/issues/737 MSYS2:Package request: graphviz]
** Marked as WIP see: https://github.com/Alexpux/MINGW-packages/tree/master/mingw-w64-graphviz

====Alternate method using Windows version of Graphviz====
Tested alternate method to use Windows version of Graphviz[http://felsin9.de/nnis/ghc-vis/installing-windows/]
{{man warn|Warning it is not advised for users to mix various libraries like the following it is a direct way to dll hell.|This way Gramps will use graphviz libs instead of MSYS2 ones and they are older and in much way incompatible with rest of Gramps dependencies. until Graphviz becomes available from MSYS2 directly this is an alternate method.}}

Download the current GraphViz ZIP archive from https://www.graphviz.org/download/ and extract it to C:\graphviz, so that it directly contains the directories bin, lib, share and so on.

From the msys2 prompt type:
<pre>
echo 'export PATH=/c/graphviz/bin:$PATH' >> ~/.bashrc
source ~/.bashrc
</pre>
Then type:

python3 Gramps.py -v

and Graphviz will be listed.

<pre>Non-python dependencies:
------------------------
Graphviz : 2.38
</pre>

==Install Python pip==
To install a working version of pip use the following steps:

<pre>
mkdir ~/scripts
cd ~/scripts
curl -O 'https://bootstrap.pypa.io/get-pip.py'
./get-pip.py
</pre>

Test that it works:

pip3 --version

If that succeeds you can now remove the installation script if wanted:

rm get-pip.py

==Keep your [[Gramps_{{man version}}_Wiki_Manual_-_Command_Line#GRAMPSHOME|GRAMPSHOME]] separate==
To keep your test family trees separate from your personal family trees you may want to use your MSYS2 home directory which you can set from mingw64 shell either:

On each run like:

GRAMPSHOME=~ python3 Gramps.py

If you want it persistent:

echo 'export GRAMPSHOME=~' >> ~/.profile
source ~/.profile

==See also==
* [[Running a development version of Gramps]]
* [https://sourceforge.net/p/gramps/mailman/message/35346200/ Gramps on WSL (Win10/Ubuntu 14.04/VcXsvr)]

[[Category:GEPS|M]]
[[Category:Developers/General]]

Programming guidelines

2024-11-07T03:57:05Z

Codefarmer: Clarify that pylint is not enforced by CI, while still encouraging its use. Remove parentheses for simplicity and emphasis.

In a multi-programmer environment, it is important to follow common coding guidelines to make sure the code remains maintainable.

== Coding style ==

=== PEP8 ===
* Write [https://www.python.org/dev/peps/pep-0008/ PEP 8] compatible code! This is important to have a consistent, readable codebase.
** it is not explicit in PEP8, but we like a space after a comma

=== Tabs ===
* Do not use TABs. Use space characters. In Gramps we use 4 spaces for indentation. This does not mean you must set your TAB stops to 4. TABs and indents are not the same thing. Most editors have a configuration option to set indentation and TAB stops. Be careful to just set the '''indentation''' to 4, which automatically means it has to be '''spaces'''. TABs are still necessary, in Makefiles for example, and they '''have to''' be equivalent to 8 spaces, '''always'''. To summarize:
** uses spaces, no TABs
** indentation is 4
** TAB stops (if any) are at position 9,17,25,... (first column is 1)

=== Members names ===
* Private class functions (functions that cannot be called outside the class) should be preceded with two underscores.
* Protected functions (functions that can only be called by the class or derived classes) should be preceded with one underscore.
<pre>
def __private_function(self):
pass

def _protected_function(self):
pass
</pre>

=== Callbacks ===

Names of callbacks should be prefixed by 'cb_'. For example, <code>cb_my_callback</code>.

<code>pylint</code> does not check that arguments are used when methods are named in this way. This is useful to avoid the <code>pylint</code> warning: 'W0613: Unused argument <arg>'.

=== Imports ===
The top module is called gramps, and it has following submodules:
* gen
* cli
* gui
* plugins
The other dirs should not contain code, or are for testing.

Within a submodule, only relative imports are allowed of the own submodule (so starting with . or with a module of the own directory), and absolute imports of other submodules (so starting with <code>gramps.</code>)

{{man note|Important:|files in the gen submodule are '''not''' allowed to import files from the other submodules. So <code>gen</code> should be self-contained.}}

== Class headers ==
* Each class should have a simple header to help mark it in the file. This is not used for documentation - it is used to help find the class when multiple classes exist in the same file.
<pre>
#------------------------------------------------------------
#
# MyClass
#
#------------------------------------------------------------
</pre>

== Docstrings ==
* Python provides a docstrings to document classes and functions. If the class is a class used by others (such as the [http://www.gramps-project.org/docs/gen/gen_lib.html#module-gen.lib gen lib] classes), the docstrings should follow the restructuredtext ([http://docutils.sourceforge.net/docs/user/rst/quickstart.html#structure rst]) format. This allows us to extract [http://www.gramps-project.org/docs/ API] documentation [[Devhelp#See_also|using Sphinx]], a documentation generator for Python code.

* Aside from adding doc strings to classes and functions, also the api generating rst files must be edited so as to extract the documentation. These files are in the [https://github.com/gramps-project/gramps/tree/master/docs docs directory], for info read the [https://github.com/gramps-project/gramps/blob/master/docs/README.txt /docs/README.txt] file.

:More info
:* [http://www.sphinx-doc.org/en/stable/markup/ Sphinx for python]
:* [http://www.sphinx-doc.org/en/stable/rest.html doc with Sphinx]

Classes that are not core reusable classes do not have to follow this format (although we encourage you do), but should be documented using docstrings.
<pre>
class MyClass:
"""
MyClass is a sample class.
"""

def my_function(self):
"""
The my_function task serves no purpose whatsoever.
"""
pass
</pre>

== Black ==
Gramps CI checks for code formatting compliance using [https://github.com/psf/black Black]. When a PR fails the check, code which requires changes is shown in the Checks tab in the Lint panel. You may update the code manually to make it pass, or integrate Black formatter with your preferred editor to ensure that the check will pass. When using Black locally, use the same version as the CI system to ensure formatting consistency.

== Pylint ==
* Run <code>pylint</code> on your code before checking in.
* New files shall have a Pylint score of 9 or higher, but not enforced by CI tools as Black formatting is.
* Any changes to existing files with a Pylint score lower than 9 shall not reduce the Pylint score. It is expected that over time, this policy will cause all files to eventually have a score of 9 or higher.

Note that you must run <code>pylint</code> in the <code>gramps</code> directory. If import errors still occur, add a PYTHONPATH. Example usage:
me@laptop:~/programs/master/src$ PYTHONPATH=plugins/lib/ pylint --reports=y plugins/mapservices/googlemap.py
Set reports to '''n''' to have less output. Information on the meaning of codes can be found here:
* [http://pylint-messages.wikidot.com/all-codes All codes, PyLint 1.1.0] Messages: and what they're trying to tell you
* [https://pylint.readthedocs.io/en/stable/user_guide/messages Pylint current stable] documentation - now generally has a bit more detail that the older version

== Best practices ==
* Maintain good code hygiene by following coding guidelines and running code analysis and formatting tools locally

* Always develop with [[Coding_for_translation|language translation]] in mind

* Reduce dependencies (imports) between files.

* Think on [[Accessibility]].

[[Category:Developers/General]]
[[Category:Developers/Quality Assurance]]

Gramplets development

2024-10-07T13:50:34Z

Codefarmer: Typo fix

{{man tip|This section contains technical details about programming Gramplets and is intended for Developers.|'''If you are interested in using Gramplets, please see the [[Gramps_{{man version}}_Wiki_Manual_-_Gramplets|user manual section on gramplets]]'''.}}

A '''Gramplet''' is a [[Addon_list_legend#Type|type of Gramps plugin]]. Gramplets are mini-views designed to be composited with other Gramplets or Views to create a way to see your Family Tree that is just right for you. In fact, Gramplets can be made to do just about anything that you want.

[[File:DashboardCategory-DashboardView-default-gramplets-52.png|450px|thumb|right|Default Gramplets on Dashboard - With Example Family Tree Open]]
[[File:Dashboard-category-view-first-open-no-family-tree-loaded-52.png|450px|thumb|right|Default Gramplets on Dashboard - No Family Tree Loaded]]

= Gramplet Interface =

Gramplet only operate after being added to a view. Add (or remove and restore) to the [[Gramps_{{man version}}_Wiki_Manual_-_Main_Window#Bottombar_and_Sidebar|sidebar or bottombar]] of a view by clicking the {{man button|&or;}} (''Down Arrowhead'' button) also known as the '''Gramplet Bar Menu''' at the far top right of the bars titles, and then using one of the options from the drop-down menu. In the Dashboard view, this menu is accessed by right-clicking in-between gramplets in the main view.

Gramplet can dramatically degrade the performance of Gramps. Some Gramplets consume huge amounts of memory, processor power and move a lot of data through storage. Don't keep a Gramplet active when it isn't being used!

When the view is not active or Gramplet tab is not the foremost in the splitbar, the Gramplet is inactive. A detached (undocked) Gramplet is always active.

The user interface for a Gramplet is left completely to the discretion of the developer. Detach/undock a Gramplet to reveal the "Help" button. Explore the Configure options after adding a Gramplet.

== Are Gramplets and 'plug-ins' the same thing? ==
There are many [[Addon_list_legend#Type|types of plugins]]. The 6 most common are:

# '''Reports''': output for printing or display
# '''Tools''': a method for processing data
# '''Quick View''': a list of details based on the current object
# '''Importer''': reads a file into your current tree
# '''Exporter''': writes a file from your current tree
# '''Gramplets''': interactive views for moving, analysing, displaying, etc.

There are two plugin directories: a global/system one, and a private/personal one. You can easily create a plugin by simply putting a file in plugins folder of your [[Gramps_{{man version}}_Wiki_Manual_-_User_Directory|User Directory]] (usually in ''<code>.gramps/grampsxx/plugins/gramplet/</code>'' ).

== Hello World ==

In teaching programming, a common "first program" is to write a program that says "Hello World".

Let us jump right in and take a look at such a gramplet named ''HelloWorld.py'':

Create a python file named ''HelloWorld.py'' and add the following content:
<pre>
# File: HelloWorld.py
def init(gui):
gui.set_text("Hello world!")
</pre>

And create another python file named ''HelloWorld.gpr.py'' with the following content:

<pre>
# File: HelloWorld.gpr.py
register(GRAMPLET,
id="Hello World Gramplet",
name=_("Hello World Gramplet"),
description = _("a program that says 'Hello World'"),
status = STABLE,
version="0.0.1",
fname="HelloWorld.py",
height = 20,
gramplet = 'init',
gramplet_title=_("Sample Gramplet"),
gramps_target_version="5.2",
help_url="Sample Gramplet"
)
</pre>

You can read more about the gpr.py file in [[Addons_development#Create_a_Gramps_Plugin_Registration_file|Addons development]] and the [https://github.com/gramps-project/gramps/blob/master/gramps/gen/plug/_pluginreg.py source code implementation].

If you place these files in '''your personal [[Gramps_{{man version}}_Wiki_Manual_-_User_Directory|user plugins directory]]''' (usually in ''.gramps/grampsxx/plugins/gramplet/'' ), and then restart Gramps, you will be able to create this Gramplet. On the '''Dashboard Category View''', right-click in an open area and select the "Hello World Gramplet". You should then see:

[[File:HelloWorldGramplet-example-shown-embeded-on-DashboardCategory-52.png|thumb|450px|left|Hello World Gramplet - example (shown embedded on Dashboard Category View / Context menu "Add a gramplet" also shown)]]

{{-}}

=== Explanation ===

The main work of a Gramplet is performed in a function, or a class. In this very simple example, a function <code>init</code> is defined that takes a single argument, <code>gui</code>. The function simply sets the gui's text area to be "Hello World!", and that's it. It does this just once, and never changes.

Before a plugin can be used, it needs to be "registered". You call the register function with a number of named-arguments. There are a number of named-arguments that you can provide, including: name, height, content, title, expand, state, and data. We will explore those in detail, below.

== Hello World, with Class ==

Here is the same functionality again, but this time as a class:

<pre>
# File: HelloWorld2.py
from gramps.gen.plug import Gramplet

class HelloWorldGramplet(Gramplet):
def init(self):
self.set_text("Hello world!")
</pre>

<pre>
# File: HelloWorld2.gpr.py
register(GRAMPLET,
id="Hello World2 Gramplet",
name=_("Hello World2 Gramplet"),
description = _("a program that says 'Hello World'"),
version="0.0.1",
gramps_target_version="5.2",
status = STABLE,
fname="HelloWorld2.py",
height = 20,
gramplet = 'HelloWorldGramplet',
gramplet_title=_("Sample Gramplet"),
help_url="5.2_Addons#Addon_List"
)
</pre>

This is the '''recommended method''' of creating a Gramplet. The following details describe the properties and methods of this class.

== Register Options ==

* '''<code>GRAMPLET</code>''': the first argument is the keyword GRAMPLET
* '''<code>id</code>''': the identifying name of the gramplet, unique among all plugins
* '''<code>name</code>''': the translated gramplet's name
* '''<code>height</code>''': the minimum (or maximum) height of the gramplet in normal mode
* '''<code>fname</code>''': the name of your gramplet file
* '''<code>gramplet</code>''': the name of the function or class in fname that creates the gramplet
* '''<code>gramplet_title</code>''': the default gramplet title; user changeable in ''Configure View''
* '''<code>status</code>''': STABLE or UNSTABLE for Gramps 5.1 version. EXPERIMENTAL, BETA {{new|5.2.0}}
* '''<code>audience</code>''': ALL, DEVELOPER, EXPERT {{new|5.2.0}}
* '''<code>version</code>''': a string with 2 dots (such as "1.23.14") representing the version number
* '''<code>gramps_target_version</code>''': a string with 2 dots representing the version of Gramps for which this gramplet was written. Only gramplets matching the installed version will be available for installation.

At the bare minimum, you need to have the above 11 options when registering your Gramplets.

Optionally, you are encouraged to use the following, if known:

* '''<code>detached_width</code>''': the size in pixels of the minimum and default detached height
* '''<code>detached_height</code>''': the size in pixels of the minimum and default detached height
* '''<code>expand</code>''': whether or not the Gramplet should expand to fill the column, if it can
* '''<code>description</code>''': a description of the Gramplet
* '''<code>authors</code>''': List (comma separated strings) of authors of the plugin, default=[]
* '''<code>authors_email</code>''': List of emails of the authors (in the same order as the '''<code>authors</code>''' list) of the plugin, default=[]
* '''<code>maintainers</code>''': List of maintainers of the plugin, default=[] {{new|5.2.0}}
* '''<code>maintainers_email</code>''': List of emails of the maintainers (in the same order as the '''<code>maintainers</code>''' list) of the plugin, default=[] {{new|5.2.0}}
* '''<code>requires_mod</code>''': specifies python modules that the addon requires. If you want to allow Gramps to try to install a module using pip, then it should be pure python. {{new|5.2.0}}
* '''<code>requires_gi</code>''': specifies GObject introspection modules that are required. Gramps cannot install these {{new|5.2.0}}
* '''<code>requires_exe</code>''': specifies executables that must be present in the PATH. Again, the user must install these themselves {{new|5.2.0}}
* '''<code>help_url</code>''': the title of the wiki page that describes the plugin. If the help_url starts with <code>http://</code> (or the secure <code>https://</code> {{new|5.2.0}}) then that fully qualified URL will be used as is. Otherwise, the paths will be interpreted as relative to <code>http://gramps-project.org/wiki/index.php?title=</code> base URL. The base URL will be prepended to the '''help_url''' and may get a language extension (such as <code>/nl</code> ) appended at the end, if the operating language is one of '''nl''' '''fr''' '''sq''' '''mk''' '''de''' '''fi''' '''ru''' '''sk'''. You should '''''not''''' use the <code>_(</code> <code>)</code> translate function around the '''<code>help_url</code>''' string, unless you specifically intend to create web pages named with the translated string.

== Core Methods ==

The class-based gramplet utilizes the following methods:

* '''<code>init()</code>''': run once, on construction
* '''<code>main()</code>''': run once per update
* '''<code>update()</code>''': don't change this, it calls main
* '''<code>active_changed()</code>''': run when active-changed is triggered
* '''<code>db_changed()</code>''': run when db-changed is triggered
* '''<code>set_tooltip(TEXT)</code>''' - tooltip for gramplet

Don't call main directly; use the update method.

In the <code>db_changed</code> method, you should connect all of the signals that will trigger an update. That typically looks like:

<pre>
def db_changed(self):
self.dbstate.db.connect('person-add', self.update)
self.dbstate.db.connect('person-delete', self.update)
self.dbstate.db.connect('person-update', self.update)
self.dbstate.db.connect('family-add', self.update)
self.dbstate.db.connect('family-delete', self.update)
self.dbstate.db.connect('family-update', self.update)
</pre>

The method <code>main()</code> can be written as a normal Python method, or it can be written to run nicely in parallel with other Gramps code. To make it run nicely in parallel, you should issue a '''<code>yield True</code>''' every once in a while. For example:

<pre>
def main(self):
for i in range(5000):
if i % 500 == 0:
yield True
yield False
</pre>

The '''True''' means that there is more to do; '''False''' means that there is nothing left to do.

=== See also ===
* [https://github.com/gramps-project/gramps/blob/d84282c496385ffc874d90a692f7d2628d314be7/gramps/gui/displaystate.py#L422 '''<code>DisplayState(Callback)</code>'''] class for additional signals. (Including Custom Filters, Gramplet display and other updates.)

== Textual Output Methods ==

The most common kinds of Gramplets are text-based. There are a number of methods to assist with handling this text.

* '''set_text(TEXT)''' - clear and set text to TEXT
* '''append_text(TEXT, scroll_to=POSITION)'''
** POSITION is 'begin' (top), 'end' (bottom) or 'start' (start of append)
* '''clear_text()''' - clears all text
* '''set_use_markup(BOOLEAN-VALUE)'''
* '''render_text(TEXT)''' - for use with A, B, I, U, and TT tags
** A for creating links; use tag '''HREF="url"''' for URLs, and '''WIKI="name"''' for pages on the wiki
** B for bold
** I for italics
** U for underlined
** TT for a fixed-width, typewriter font
* '''link(TEXT, LINK-TYPE, DATA)''' -
** TEXT can be any text
** LINK-TYPE is:
*** 'Person' - and DATA is a person handle
*** 'PersonList' - and DATA is a list of handles
*** 'Family' - and DATA is a family handle
*** 'Surname' - and DATA is a person
*** 'Given' -
*** 'Filter' - and DATA is either:
**** 'all people' -
**** 'males' - all males
**** 'females' - all females
**** 'people with unknown gender' - people marked as unknown
**** 'people with incomplete names' - people who have a missing surname or given name
**** 'people with missing birth dates' - people who have missing birth dates
**** 'disconnected people' - people with no parents and no children
**** 'all families' - all families
**** 'unique surnames' - list of all unique surnames
**** 'people with media' - people who have media
**** 'media references' - all of the media
**** 'unique media' -
**** 'missing media' - media for which the file does not exist
**** 'media by size' -
**** 'list of people'-
*** 'URL' - and DATA is a URL
*** 'WIKI' - and DATA is a wiki page
*** 'Attribute' - and DATA is an attribute (eg, 'Nickname')
* '''no_wrap()''' - turn word wrap off DEPRECATED
* '''set_wrap(BOOL)''' - change word wrap

=== Using Tags ===

Tags are the manner in which you format the text.

<pre>
tag = self.gui.buffer.create_tag("fixed")
tag.set_property("font", "Courier 8")
...
start, end = self.gui.buffer.get_bounds()
self.gui.buffer.apply_tag_by_name("fixed", start, end)
self.append_text("", scroll_to="begin")
</pre>

==GUI Interface==
* [[Gramplets_development#Widget_Gramplet_example|Widget Gramplet example]]
* [[Gramplets_development#Cairo_Clock_Example|Cairo Clock Example]]
{{stub}}

===Widget Gramplet example===
Occasionally, you might have to dive down to the graphical objects that compose a Gramplet.

* gui
** gui.buffer
** gui.textview
** '''gui.get_container_widget()'''

If you wanted to put an arbitrary gtk object into the main area of a Gramplet, then you need to replace the standard textview object with your own. Here is the basic structure:

<pre>
# File: Widget.py
from gettext import gettext as _
from gramps.gen.plug import Gramplet
from gi.repository import Gtk

class WidgetGramplet(Gramplet):
def init(self):
self.gui.WIDGET = ### Some Widget Constructor ###
self.gui.get_container_widget().remove(self.gui.textview)
self.gui.get_container_widget().add_with_viewport(self.gui.WIDGET)
self.gui.WIDGET.show()
</pre>

<pre>
# File: Widget.gpr.py

register(GRAMPLET,
id= "Widget Gramplet",
name=_("Widget Gramplet"),
description = _("Widget Gramplet example"),
authors = ["John Smith","Sam Jones"],
authors_email = ["jsmith@example.com","user@noemail.invalid"],
height=100,
expand=False,
gramplet = 'WidgetGramplet',
gramplet_title=_("Widget"),
version = '0.0.1',
gramps_target_version = "5.2",
fname="Widget.py",
)
</pre>

====Gramps 3.x and older====
<pre>
# File: Widget.py
from gettext import gettext as _
from gramps.gen.plug import Gramplet
import gtk

class WidgetGramplet(Gramplet):
def init(self):
self.gui.WIDGET = ### Some Widget Constructor ###
self.gui.get_container_widget().remove(self.gui.textview)
self.gui.get_container_widget().add_with_viewport(self.gui.WIDGET)
self.gui.WIDGET.show()
</pre>

<pre>
# File: Widget.gpr.py
register(GRAMPLET,
id= "Widget Gramplet",
name=_("Widget Gramplet"),
height=100,
expand=False,
fname="Widget.py",
gramplet = "WidgetGramplet",
gramps_target_version = "3.4",
gramplet_title=_("Widget"),
)
</pre>

===Cairo Clock Example===

[[File:ClockGramplet-addon-example-50.png|thumb|400px|right|Clock Gramplet - shown detached (Gramps 5.0.0)]]

In fact, with Python, GTK, and cairo, you can make your own widgets that do pretty much anything and look very nice.

Here is an example adding a Cairo Clock (which really keeps time)
* With GTK+3 & Gramps 5.1
** Github code: [https://github.com/gramps-project/addons-source/tree/maintenance/gramps51/ClockGramplet ClockGramplet]
** Manual Download: [https://github.com/gramps-project/addons/blob/master/gramps51/download/ClockGramplet.addon.tgz?raw=true ClockGramplet.addon.tgz]
{{-}}

== GUI Options ==

* '''add_option(OPTION)'''
** OPTION is one of the menu options in [https://github.com/gramps-project/gramps/tree/master/gramps/gen/plug/menu gramps/gen/plug/menu] eg:
*** NumberOption
*** EnumeratedListOption
*** StringOption
*** ColorOption
*** TextOption
*** BooleanOption
*** FilterOption
*** PersonOption
*** FamilyOption
*** NoteOption
*** MediaOption
*** PersonListOption
*** PlaceListOption
*** SurnameColorOption
*** DestinationOption
*** StyleOption
*** BooleanListOption
* '''build_options()'''
* '''save_options()'''
* '''get_option_widget(TEXT)'''
* '''get_option(TEXT)'''

== Predefined Properties ==

There are a number of preset properties:

* dbstate
** dbstate.db
*** dbstate.db.connect(SIGNAL, METHOD)
*** dbstate.db.get_person_from_handle(HANDLE)
*** dbstate.get_active_person()
* uistate

== Persistence ==

* gui
** gui.data
* '''on_load()'''
* '''on_save()'''
* '''save_text_to_data()'''
* '''load_data_to_text()'''

== Advanced Settings ==

* '''force_update''': set True to have the gramplet update, even when minimized

Calling the update() method of a gramplet causes its main() method to be called repeatedly in the background until it returns False.

Most gramplets will contain a main() method that runs quickly and always returns False.

Gramplets that have more intensive processing will use the main() method as a generator which will be run multiple times in the background. It will return True until it has finished processing then it will return False.

This background task can be controlled with the pause() and resume() methods. Additionally there is an interrupt() method which will cancel execution of the background task, and update_all() which will run the entire task in the foreground immediately.

A background task will continue to run '''even if the gramplet is no longer active'''.

Gramplets that should be updated in response to changes in the database should connect to the appropriate signals.

Gramplets such as a news gramplet could be updated by adding a refresh button or running the update() method at regular intervals.

== Learning More ==

To learn more about writing a Gramplet, it is suggested to look at the existing Gramplets. You can see a complete list of the Gramplet source code here:

* [https://github.com/gramps-project/gramps/tree/master/gramps/plugins/gramplet Gramps Master (development fork) Gramplets]
* '''[https://github.com/gramps-project/gramps/tree/maintenance/gramps52/gramps/plugins/gramplet Gramps 5.2 Gramplets]'''
* [https://github.com/gramps-project/gramps/tree/maintenance/gramps51/gramps/plugins/gramplet Gramps 5.1 Gramplets]
* [https://github.com/gramps-project/gramps/tree/maintenance/gramps50/gramps/plugins/gramplet Gramps 5.0 Gramplets]
* [https://github.com/gramps-project/gramps/tree/maintenance/gramps42/gramps/plugins/gramplet Gramps 4.2 Gramplets]
* [https://github.com/gramps-project/gramps/tree/maintenance/gramps34/src/plugins Gramps 3.4 Gramplets]

Click on a filename, to view the source code of that Gramplet.

* [https://github.com/gramps-project/gramps/blob/master/gramps/gen/plug/_gramplet.py master/gramps/gen/plug/_gramplet.py] - Base class for non-graphical gramplet code.

= See also =
* [https://www.gramps-project.org/docs/gen/gen_utils.html?module-gramps.gen.utils.callback#gramps.gen.utils.callman.CallbackManager CallbackManager] - a key tool that enables event handling and function execution based on specific triggers or events of a tree database.
* [https://www.gramps-project.org/docs/gen/gen_utils.html?highlight=signals#module-gramps.gen.utils.callback Callback] in <code>signals#module-gramps.gen.utils</code>
* [[Addons development]] - for Gramps 4.2 and later
** [[Addons development old]] - for Gramps 3.2 to 4.1
* [[Writing a plugin]] - for Gramps version 3.2 and earlier
* Discourse support forum : [https://gramps.discourse.group/t/how-can-i-make-a-gpr-py-registration-that-is-compatible-with-4-x-and-5-2/5290 How can I make a .gpr.py registration that is compatible with 4.x and 5,2]

[[Category:Addons]]
[[Category:Developers/General]]
[[Category:Developers/Tutorials]]
[[Category: Plugins]]
[[Category:Gramplets]]

Category:GEPS

2024-08-15T22:02:21Z

Codefarmer: GEPs should not have an apostrophe

'''G'''ramps '''E'''nhancement '''P'''roposal'''s''' (GEPS). This should be a complex/detailed description of a way to make Gramps better.

:Here they are listed in numerical order:
{| class="wikitable sortable" {{Prettytable}}
|+ Gramps Enhancement Proposals (GEPS) - Summary
|-
! GEPS - Title
! Proposed
! Status
! Released
! Note
! Revision Control
|-
| [[GEPS 001: Relationship type event link]]
| 2007
| ?
| ?
| ?
| 
|-
| [[GEPS 002: RelationView Expand and Collapse]]
| 2007
| '''Finished'''
| Gramps 3.0
| -
| 
|-
| [[GEPS 003: Computed Ages and Probably Alive]]
| 2007
| '''Finished'''
| Gramps 3.1
| -
| 
|-
| [[GEPS 004: My Gramps and Gadgets]]
| 2007
| '''Finished'''
| Gramps 3.1
| Called "[[Gramplets|Gramplets View]]"
| 
|-
| [[GEPS 005: Enhanced Plugin Interface]]
| 2007
| ''In progress''
| ?
| See [[GEPS 014: Plugin registration and management]]
| 
|-
| [[GEPS 006: Better Place handling]]
| 2007
| '''Finished'''
| Gramps 3.2 Gramps 3.3 Gramps 4.1
| Place tree view. Locality field added to location. Hierarchical place structure.
| 
|-
| [[GEPS 007: Report Reorganization]]
| 2007
| ?
| ?
| ?
| 
|-
| [[GEPS 008: File Organization]]
| 2008
| '''Finished'''
| Gramps 4.0
| 
| 
|-
| [[GEPS 009: Import Export Merge]]
| 2008
| ?
| ?
| ?
| 
|-
| [[GEPS 010: Relational Backend]]
| 2009
| '''Withdrawn'''
| -
| Related to [[GEPS 013: Gramps Webapp]], [[GEPS 032: Database Backend API]]
| 
|-
| [[GEPS 011: Tagging]]
| 2008 2012
| '''Finished'''
| Gramps 3.3 Gramps 4.1
| Tagging of people, families, media and notes only. Tagging extended to all primary objects.
| 
|-
| [[GEPS 012: Ecosystem definition]]
| 2009
| ?
| ?
| ?
| 
|-
| [[GEPS 013: Gramps Webapp]]
| 2009
| ''In progress''
| ?
| See prototype [http://gramps-connect.org/ gramps-connect.org] You can log into the site, as a: superuser (id=admin, password=gramps) or a regular user (id=admin1, password=gramps) or just view as an anonymous user.
| Current code is now in [https://github.com/gramps-project/gramps/tree/master/gramps/webapp master]
|-
| [[GEPS 014: Plugin registration and management]]
| 2009
| '''Finished'''
| Gramps 3.2.x
| -
| 
|-
| [[GEPS 015: Repository Research Support]]
| 2009
| ?
| ?
| ?
| 
|-
| [[GEPS 016: Enhancing Gramps Processing Speed]]
| 2009
| ?
| ?
| ?
| 
|-
| [[GEPS 017: Flexible gen.lib Interface]]
| 2009
| '''Withdrawn'''
| 
| After building a prototype, it was found to be too slow for general use. Instead, caching BSDDB serialized data seems an easier approach.
| 
|-
| [[GEPS 018: Evidence style sources]]
| 2010
| ''In progress''
| 
| 
| [https://github.com/gramps-project/gramps/tree/geps/gep-018-evidence-style GIT]
|-
| [[GEPS 019: Improved Sidebar and Split Views]]
| 2010
| '''Finished'''
| Gramps 3.3
| -
| 
|-
| [[GEPS 020: Plugin Extensions]]
| 2010
| ?
| ?
| ?
| 
|-
| [[GEPS 021: Additional Name Fields]]
| 2010
| '''Finished'''
| Gramps 3.3
| -
| [https://github.com/gramps-project/gramps/tree/geps/gep-021-name/ GIT]
|-
| [[GEPS 022: Narrative Website Refactor]]
| 2010
| ''In progress''
| ?
| ?
| 
|-
| [[GEPS 023: Storing data from large sources]]
| 2010
| '''Finished'''
| Gramps 3.4
| -
| Code merged into trunk [http://gramps.1791082.n4.nabble.com/GEPS023-merged-into-trunk-td4157519.html] 
|-
| [[GEPS 024: Natural transcription of Records]]
| 2010
| ?
| ?
| ?
| 
|-
| [[GEPS 025: Geography]]
| 2011
| '''Finished'''
| Gramps 3.3
| -
| [http://svn.code.sf.net/p/gramps/code/branches/geps/gep-025-name/ SVN]?
|-
| [[GEPS 026: Replace 'make' for Gramps build]]
| 2012
| '''Finished'''
| Gramps 4.0
| Move Gramps away from using Makefiles and to using setup.py and/or DistUtils[http://sourceforge.net/mailarchive/message.php?msg_id=28984484][http://sourceforge.net/mailarchive/message.php?msg_id=28969888][http://sourceforge.net/mailarchive/message.php?msg_id=27984817]{{bug|2621}}
| [http://svn.code.sf.net/p/gramps/code/branches/geps/gep-026-replace-make/ SVN]
|-

| [[GEPS 027: Gender as an Entry Field]]
| 2012
| 
| 
|  Proposal to make gender selection be decided in an ComboBoxEntry field, to allow for options outside of male, female or unknown
| 
|-
| [[GEPS 028: Media Management]]
| 2012
| 
| 
|  Proposal to make Gramps do more to help media management
| 
|-
| [[GEPS 029: GTK3-GObject introspection Conversion]]
| 2012
| '''Finished'''
| 4.0.0
| Conversion to the new version of GTK using the new python bindings based on introspection.
| [http://svn.code.sf.net/p/gramps/code/branches/geps/gep-029-gtk3/ SVN]
|-
| [[GEPS 030: New Visualization Techniques]]
| 2012
| ''In Progress''
| '''Fan chart'''(Gramps 4.0) '''Descendant Fan View'''(Gramps 4.0) '''2-Way Fan View''' (Gramps 5.0)
| Discussion of new visualization techniques for possible inclusion in Gramps.
| 
|-
| [[GEPS 031: Python 3 support]]
| 2012 2015
| '''Finished''' '''Finished'''
| 4.0.0 4.2.0
| Added support for Python 3. Moved to Python 3 only (Python 2 support dropped)
| 
|-
| [[GEPS 032: Database Backend API]]
| 2013
| '''Finished'''
| Gramps 5.0
| Plug-in replacements for BSDDB. This allows the use of other databases as a backend.
| 
|-
| [[GEPS 033: Abstract Database API]]
| 2014
| ''In Progress''
| 
| Working on for Gramps 4.1
| http://sourceforge.net/u/nick-h/gramps/ci/master/tree/
|-
| [[GEPS 034: Improve usability]]
| 2014
| 
| 
| This GEPS is about changes that would significantly improve the user friendliness of Gramps.
| 
|-
| [[GEPS 035: Attach family events to individuals]]
| 2014
| 
| 
| 
| 
|-
| [[GEPS 036: Extended Alternative Place Name Handling]]
| 2015
| '''Finished'''
| Gramps 4.2
| Citations not added to place names.
| 
|-
| [[GEPS 037: Support GEDCOM X]]
| 2015
| 
| 
| GEDCOM X is a set of open specifications for exchanging the genealogical data essential to the genealogical research process.
| 
|-
| [[GEPS 038: Enhanced Transaction Log]]
| 2015
| 
| 
| Exploration of enhancing a persistent transaction log.
| 
|-
| [[GEPS 039: Genealogical symbols in gramps]]
| 2015
| '''Finished'''
| Gramps 5.1
| Exploration of the possibility to use genealogical symbols in gramps (gui, reports, ...)
| [https://github.com/gramps-project/gramps/tree/geps/gep-039-genealogical-symbols GIT]
|-
| [[GEPS 040: Persona Support]]
| 2016
| 
| 
| Exploration of supporting the persona concept in Gramps
| 
|-
| [[GEPS 041: New Selector]]
| 2016
| 
| 
| Exploring and reviewing current base selector
| 
|-
| [[GEPS 042: Multi-user record locking and editing]]
| 2016
| 
| 
| Explore ability to lock rows, and separate views from editors
| 
|-
| [[GEPS 043: Improving GEDCOM support for Places]]
| 2017
| ''In Progress''
| Working on for Gramps 5.2.0 (master branch)
| 
| 
|-
| [[GEPS 044: Replace Deprecated Gtk.UIManager]]
| 2018
| '''Finished'''
| Gramps 5.1
| 
| 
|-
| [[GEPS 045: Place Model Enhancements]]
| 2019
| ''In discussion''
| Working on for Gramps 5.2.0 (master branch)
| 
| 
|-
| 
| 
| 
| 
| 
| 
|-|}

==Disruptive GEPs==

If a GEP is disruptive, a specific branch is used to develop it. See the ''Brief introduction to Git'' for detailed instructions on [[Brief_introduction_to_Git#Creating_a_branch|creating a branch]].

==Reference==
*[http://sourceforge.net/p/gramps/mailman/message/12554507/ GEPs: Gramps Enhancement Proposals], Jan 19, 2007, By Douglas S. Blank (Original discussion to form GEPs based on an "idea stolen and adapted from Python")

[[Category:Developers/General]]
[[Category:Developers/Roadmap]]

Addon:NoteCleanupTool

2024-07-28T18:06:25Z

Codefarmer: Add issues

{{Third-party plugin}}

[[File:Note_Cleanup_Tool.png|thumb|right|450px|Note Cleanup Tool - example window]]

==What is it For?==

The '''Note Cleanup Tool''' searches your database for notes that contain "HTML tags" and cleans it up. "HTML tags" have meaning to web browsers and other applications, but look like garbage to most people.

The cleanup consists of converting the "HTML tags" to what the Gramps folks call "Styled text" which displays nicely within Gramps and in the various reports that Gramps can generate.

The tool also searches for "links" to web sites and sets them to "Styled Text Links", so that they work properly in reports such as the Gramps ''Narrative Web Site''.

'''Examples of notes that needs cleaning'''
<nowiki> &lt;i&gt;Selected U.S. Naturalization Records&lt;/i&gt;.
Washington D.C.: National Archives and Records Administration.
&lt;p&gt;&lt;a href=&quot;/search/dbextra.aspx?dbid=1629&quot;&gt;
View Full Source Citations&lt;/a&gt;.&lt;/p&gt;

United States of America, Bureau of the Census. Fifteenth Census of the United States, 1930.
Washington, D.C.: National Archives and Records Administration, 1930. T626, 2,667 rolls.</nowiki>

The first note contains some text with ''italics'' as well as a link to a web site. The cleaned note is shown in the lower right pane of the image on the cleanup tool above.
The second dirty note is much simpler, it only contains a bit of ''italics'' text; the tool will remove the <nowiki> and </nowiki> and convert the text in between to ''italics''.

===Where do the "dirty" notes come from?===

The author of this plugin has a lot of data that was imported from http://ancestry.com via GEDCOM. It seems that the ancestry.com software doesn't always do a great job of converting their web pages to notes for GEDCOM export.
The popular '''Family Tree Maker''' software, in conjunction with ancestry.com also seems to have a lot of these "dirty" notes in their GEDCOM exports.
There are probably other ways that dirty notes get into our data, but this tool can help clean it up.

==Usage==

* Once this plugin has been installed
* Select Menu {{man menu|Tools -> Utilities -> Note Cleanup...}}

{{man warn|Warning|Proceeding with this tool may make unexpected changes to your data. While it is possible to '''Undo''' the changes made by this tool, it may be easier to recover from a backup.}}

* The dialog that pops up when you start the tool provides a warning and a short review of the tool usage. Clicking {{man button|Close}} will dismiss the dialog but does nothing else.
* At this point the tool window with three main panes and some buttons should be visible.
* If you want to perform a quick test to see what this tool does, you can press the {{man button|Generate Test Notes}} button. ''This is best performed on a test database, since it actually adds some test notes to the active database.''
* Otherwise you can perform a scan of your data by pressing the {{man button|Search}} button. This does not make '''any''' changes to your data, only performs the search and fills the panes if any dirty notes are found.
** The left pane will contain lists of the results of the search. If nothing appears here, then none of your data is dirty, or any dirty notes already have been edited and styled. There may be up to three lists in the left pane. A list will only be present if there are notes found in that category.
*** The '''Cleaned Notes''' list contains notes that have been edited in some way, and may have ''styles'' applied. This includes converting any web links to a ''styled'' link.
*** The '''Links Only''' list contains notes that have not been edited (no textual changes at all) but have had links converted to ''styled''.
*** The '''Issues''' list contains notes that ''may'' have been edited in some way, but contain ''HTML tags'' that the tool does not recognize.
** The top right pane will show the original unedited text of a note that is selected in the left pane. This cannot be changed.
** The lower right pane will show the proposed changes to the note. If the user wants to make additional changes, they can be made directly in the pane. The editing toolbar directly above the lower left pane can be used to make or correct style changes as well. This toolbar is an abbreviated version of the normal Gramps Note editor toolbar and each icon works the same. Any changes made here are preserved within the tool, but will not affect your data until the {{man button|Save All}} button is pressed (see next below).
* When you have reviewed all the changes made, either by the tool, or manually, you can save your work using the {{man button|Save All}} button. Your data is '''not''' changed until you press this button, but when you do, all the changes are committed to your database.
* If you do not want any changes to be made to your data, or you are done with the tool, you can simply press the {{man button|Close}} button.
* If you want a record of notes that have been found in the search, you can use the {{man button|Export}} button to save a listing to a text file.

==Some Notes==

* If any '''Issues''' are found, the unrecognized "HTML tag" ''will'' be marked up with a {{man menu|yellow highlight}}. The user may want to manually edit each of these in some way. When done, the highlight can be removed by selecting the highlighted region and pressing the "Clear Markup" toolbar button (last button on the right).
* Pressing the {{man button|Search}} button at any time will scan your data again, discarding any proposed automatic or manual changes and producing new lists.
* Double Clicking on a note in a left pane list will bring up the standard Gramps Note Editor. Any changes in that editor followed by pressing the {{man button|OK}} button '''will''' update your database immediately. However, if you later press the {{man button|Save All}} button in the still open Note Cleanup Tool, that data will be overwritten by the Note Cleanup Tool.

==Issues==

* {{bug|12880}} NoteCleanup addon causes error with links in Complete Individual Report when opening ODT file in Libre Office

* All Notes-related issues [https://gramps-project.org/bugs/search.php?project_id=8&sticky=on&sort=last_updated&dir=DESC&hide_status=90&tag_string=notes&match_type=0 tagged notes] on the Gramps Bug Tracker.

[[Category:Addons]]
[[Category:Plugins]]
[[Category:Developers/General]]
[[Category:Tools]]

Addon:GenealogyTree

2024-07-12T15:21:04Z

Codefarmer: Fix typo in package name

{{Third-party plugin}}
[[File:Menu-trees-gramps50.png|450px|right|thumb|Main menu showing all four reports for Addon:GenealogyTree]]
The '''GenealogyTree''' addon creates professional looking trees for the active person in the [[Addon:GenealogyTree#Prerequisites|LaTeX genealogytree (the Pedigree and genealogical tree diagrams package)]] file format. The following reports are available:
* {{man label|[[Addon:GenealogyTree#Ancestor_tree|Ancestor Tree]]}}
* {{man label|[[Addon:GenealogyTree#Descendant_tree|Descendant Tree]]}}
* {{man label|[[Addon:GenealogyTree#Grandparent_tree|Grandparent Tree]]}}
* {{man label|[[Addon:GenealogyTree#Sandclock_tree|Sandclock Tree]]}}
* {{man label|[[Addon:GenealogyTree#Sandclock Tree for a Family|Sandclock Tree for a Family]]}}

== Usage ==
From the menu select {{man menu|Reports > Trees > [Xxxxx] Tree...}} where [Xxxxx] is one of the available reports.

{{man tip|For a large family tree|Make sure to select a large enough paper size in the {{man label|Paper Options}} tab as the reports [[Addon:GenealogyTree#Issues|currently]] do not scale well.}}

* Output is to {{man label|[https://www.latex-project.org/ LaTeX File]}}(<code>*.tex</code>) by default. This format is generally intended for print production and may not be suitable for ''viewing'' the resulting tree chart. Installing an [[Addon:GenealogyTree#Prerequisites|additional program]] to automatically convert to a <code>.pdf</code> format file is highly recommended.

See [[Gramps_{{man version}}_Wiki_Manual_-_Reports_-_part_4#Common_options|Common options]]



== Tree examples ==
Example output for each tree report.
{{-}}
===Ancestor tree===
[[File:GenealogyTree-Addon-AncestorTree-example-50.png|450px|right|thumb|Ancestor tree - example for Addon:GenealogyTree]]

Creates a tree chart showing the ancestors of the active person.
{{-}}

===Descendant tree===
[[File:GenealogyTree-Addon-descendant-example-50.png|450px|right|thumb|Descendant tree - example for Addon:GenealogyTree]]

Creates a tree chart showing the descendants of the active person.
{{-}}

===Grandparent tree===
[[File:GenealogyTree-grandparent-example-50.png|450px|right|thumb|Grandparent tree - example for Addon:GenealogyTree]]
Creates a Grandparent tree for the selected person.
{{-}}

===Sandclock tree===
[[File:GenealogyTree-Addon-sandclock-example-51.png|450px|right|thumb|Sandclock tree - example for Addon:GenealogyTree]]
Creates a Sandclock tree for the selected person.

A sandclock connects ancestors and descendants starting from a single proband (active person).
{{-}}

===Sandclock Tree for a Family===
[[File:GenealogyTree-Addon-sandclock_family-example-51.png|450px|right|thumb|Sandclock Tree for a Family - example for Addon:GenealogyTree]]
Creates a Sandclock tree for the selected family.
{{-}}

== Prerequisites ==
Output is only to {{man label|[[Output_formats#LaTeX|LaTex]] File}} (<code>*.tex</code>) which by default is displayed as plain text with layout annotation in the preferred Text viewing application for your OS unless you have installed a LaTex helper application. The following prerequisite "helper" applications will interpret the layout annotation to view the fully formatted LaTex(*.tex) file or automatically convert it to a <code>pdf</code> file:
* [https://www.tug.org/texlive/ texlive] including the <code>textlive-pictures</code> package which contains [https://ctan.org/pkg/genealogytree LaTeX genealogytree] (the Pedigree and genealogical tree diagrams package)

The <code>texlive-pictures</code> package contains <code>genealogytree</code>.

The <code>texlive-fonts-extra</code> package is required for non-latin fonts.

See specific instructions for your operating system.
* [[Addon:GenealogyTree#Linux|Linux]]
* [[Addon:GenealogyTree#Apple MacOS|Apple MacOS]]
* [[Addon:GenealogyTree#Microsoft Windows|Microsoft Windows]]

===Linux===

====Debian/Ubuntu====

* TeX support, at least 'texlive-base', 'texlive-binaries', 'tex-common', 'luatex' packages
* for internal PDF output file format needs LaTex support (e.g., 'texlive-latex-base' package)
* for genealogytree needs 'texlive-pictures' package
or download and install '[https://www.ctan.org/pkg/genealogytree genealogytree]' for the last version:

<code>$ mkdir -p ~/texmf/tex/latex/genealogytree</code>
or ''/var/lib/texmf'', ''/usr/local/share/texmf''

<code>$ cp ./genealogytree/* ~/texmf/tex/latex/genealogytree</code>

<code>$ texhash ~/texmf</code>

Same for '[https://www.ctan.org/pkg/tcolorbox tcolorbox]', and maybe
for fonts : '[https://www.ctan.org/pkg/libertine libertines]', '[https://www.ctan.org/pkg/mweights mweights], etc ...

<code>$ cp ~/texmf/tex/latex/libertine/map/libertine.map ~/.texmf-var/fonts/map/pdftex/updmap/pdftex.map</code>

<code>$ updmap --enable Map=~/texmf/tex/latex/libertine/map/libertine.map</code>

<code>$ sudo mktexlsr</code>

<code>$ sudo updmap-sys --enable Map=~/texmf/tex/latex/libertine/map/libertine.map</code>

* need 'texlive-latex-extra' (for xkeyval) and 'latex-tools' (for [https://github.com/T-F-S/csvsimple/issues/1 shellesc]) or install the base [http://mirrors.ctan.org/macros/latex/base.zip]!
* can also update '[https://www.ctan.org/pkg/pdftexcmds pdftexcmds]' and '[https://www.ctan.org/pkg/pgf pgf]'

{{stub}}

===Apple MacOS===
Install the MacTeX distribution.
* https://www.tug.org/mactex/
{{stub}}

===Microsoft Windows===

You can enable automatic output to PDF on Microsoft Windows as by default these reports only output to the LaTeX(".tex" extension) file type which are not suitable for viewing.

For our Microsoft Windows TeX/LaTeX environment you will use [https://miktex.org/ MiKTeX] we only need to download the basic installer from:
* https://miktex.org/download/

Start the MiKTeX installer and during install:
* select {{man label|[ ]Install MiKTeX only for me(YOURUSERNAME)}}
* and change {{man label|Install missing packages on-the-fly}} to ''Yes''
after successful installation of MiKTeX do the following once only:

Start the [https://www.howtogeek.com/235101/10-ways-to-open-the-command-prompt-in-windows-10/ Microsoft Windows command console prompt] (cmd.exe) and type:

<code>lualatex --version</code>

If that works then you are ready to have MiKTex install the additional missing packages, start Gramps and create a one of the {{man menu|Reports > Trees > [Xxxxx] Tree...}} reports and for the LaTeX(".tex" extension). Now in the Microsoft Windows command console prompt (cmd.exe) type:

<code>lualatex FILENAME</code>

where FILENAME is full pathname of <code>.tex</code> file you previously create in Gramps. The MiKTeX package manager will then automatically download the missing packages. When all is finished pdf file will be created in directory in which you start this command, along with two other files of the same name but with different extensions (*.log) and (*.aux) which you can ignore.

If everything goes well you will now have an additional {{man label|Output format:}} option in Gramps to output the reports to the PDF(".pdf" extension) format and the builtin LaTex(*.tex) format.

The last optional step is from the Windows StartMenu run the {{man label|MiKTeX Console}} and in {{man label|Settings}} change {{man label|[ ]Always install missing packages on-the-fly}} settings to {{man label|[ ]Ask me}}(recommended) or {{man label|[ ]Never install missing packages on-the-fly}}.

{{man tip|PDF's created automatically with lualatex|are output to the PDF Version 1.5 (Acrobat 6.0)format which has a maximum PDF page size of 200" x 200" inches (508cm x 508cm) so choose your custom paper sizes accordingly or Gramps will show the {{man label|[[Gramps_{{man version}}_Wiki_Manual_-_Error_and_Warning_Reference#Report_could_not_be_created|Report could not be created]]}} dialog}}

==See also==
* Feature request {{bug|10223}} LaTeX genealogytree reports
* https://github.com/gramps-project/gramps/blob/master/gramps/gen/plug/docgen/treedoc.py (creates the *.tex file and checks for the presence of lualatex.exe on Windows or lualatex on Linux )
*[https://sourceforge.net/p/gramps/mailman/message/36223716/ Original instructions for installing PDF output support for Microsoft Windows]
* [https://ctan.org/pkg/genealogytree LaTeX genealogytree] (the Pedigree and genealogical tree diagrams package) - By Prof. Dr. Dr. Thomas F. Sturm, [http://mirrors.ctan.org/macros/latex/contrib/genealogytree/genealogytree.pdf documentation] & examples ([https://github.com/T-F-S/genealogytree github])- CTAN(Comprehensive TeX Archive Network) - Pedigree and genealogical tree diagrams are proven tools to visualize genetic and relational connections between individuals. The naming (“tree”) derives from historical family diagrams. However, even the smallest family entity consisting of two parents and several children is hardly a ‘mathematical’ tree — it is a more general graph. The package provides a set of tools to typeset genealogical trees (i.e., to typeset a set of special graphs for the description of family-like structures). The package uses an autolayout algorithm which can be customized, e.g., to prioritize certain paths.
* Questions tagged [https://tex.stackexchange.com/questions/tagged/genealogytree genealogytree] on tex.stackexchange.com

'''Discussions on Gramps community support forum (Discourse)'''
* [https://gramps.discourse.group/t/recurring-people-not-visible-on-exported-descendant-graph/4328/5 rendering of cousins marrying] and [[Addon:Family_Tree|Family Tree]] addon report as an alternative.

== Issues ==
See issues tagged with [https://gramps-project.org/bugs/tag_view_page.php?tag_id=294 GenealogyTree] on the bugtracker.
* The diagram doesn't scale to fit the page. For a large tree you will have to select a large paper size.
** Only the smallest value on Paper size item will be used
** {{bug|10512}}Sandclock tree generates one page of (possibly) a larger report
* {{bug|10494}} LaTeX report includes full images uncropped
* Help button url does not come here.
* No support for localized month names
* If you install only one of the reports the rest are installed also!

[[Category:Addons]]
[[Category:Plugins]]
[[Category:Developers/General]]

Addons development

2024-06-28T14:09:51Z

Codefarmer: Author and maintainer attributes in plugin registration files

{{man tip|Information on developing Gramps addons|If you are looking for addons to install, visit: [[Third-party Addons]]}}
{{man warn|Note that this article anticipates that most addons will be developed under Linux.|([[Getting started with Gramps development|Linux is the principal development platform.]]) While it is possible to do so under Windows or MacOS, some of the steps will differ and the documented processes have not been as thoroughly reviewed. So developer beware. See [[Portal:Developers]]}}
If you are developing a [[Third-party Addons|Third-party Addon]]; this page documents the API, methods, and best practices for Gramps 4.2 and later.

==What can addons extend?==
Addons for Gramps can extend the program in many different ways. You can add any of the following [https://github.com/gramps-project/gramps/blob/master/gramps/gen/plug/_pluginreg.py types] of addons:


* '''Importer''' (IMPORT) - adds additional file format import options to Gramps
* '''Exporter''' (EXPORT) - adds additional file format export options to Gramps
* '''[[Gramps_Glossary#gramplet|Gramplet]]''' (GRAMPLET) - adds a new interactive interface section to a Gramps view mode, which can be activated by right-clicking on the dashboard View or from the menu of the Sidebar/Bottombar in the other view categories.
* '''Gramps [[Gramps_Glossary#viewmode|View ''(mode)'']]''' (VIEW) - adds a new view mode to the list of views available within a [[Gramps_Glossary#view|View Category]]
* '''[[Map_Services|Map Service]]''' (MAPSERVICE) - adds new mapping options to Gramps
* '''Plugin lib''' (GENERAL) - libraries that are present giving extra functionality. Can add, replace and or modifies built-in Gramps options.
* '''[[Gramps_{{man version}}_Wiki_Manual_-_Reports_-_part_8#Quick_Views|Quickreport'''/'''Quickview]]''' (QUICKREPORT) - a view that you can run by right-clicking on object, or if a person quickview, then through the Quick View Gramplet
* '''[[Gramps_{{man version}}_Wiki_Manual_-_Reports_-_part_1|Report]]''' (REPORT) - adds a new output report / includes '''Website''' - output a static genealogy website based on your Gramps Family Tree data.
* '''[[Gramps_{{man version}}_Wiki_Manual_-_Filters#Add_Rule_dialog|Rule]]''' (RULE) - adds new [[Gramps_Glossary#filter|filter]] rules. {{new|5.1}}
* '''[[Gramps_{{man version}}_Wiki_Manual_-_Tools|Tool]]''' (TOOL) - adds a utility that helps process data from your family tree.
* '''Doc creator''' (DOCGEN)
* '''Relationships''' (RECALC)
* '''Sidebar''' (SIDEBAR)
* '''[[Database_Backends|Database]]''' (DATABASE) - add support for another database backend. {{new|5.0}}
* '''Thumbnailer''' (THUMBNAILER) {{new|5.2}}
* '''Citation formatter''' (CITE) {{new|5.2}}

==Writing an addon==
Writing an addon is fairly straightforward if you have just a little bit of Python experience. And sharing your addon is the right thing to do. The general steps to writing an addon and sharing your own addons are:

# [[#Develop_your_addon|Develop your addon]]
# [[#Create_a_Gramps_Plugin_Registration_file|Create a Gramps Plugin Registration file (.gpr.py)]]
# [[#internationalization|Invite translation of your addon]] into multiple natural languages
# [[#Package_your_addon|Package your addon]]
# [[#List_and_document_your_addon_on_the_wiki|Document your addon]] and publish it to the addon list
# [[#List_your_addon_in_the_Gramps_Plugin_Manager|Register your addon with the Plugin Manager]]
# [[#Announce_the_addon|Announce it on the Gramps Forum]] - Let users know it exist and how to use it.
# [[#Support_it_through_issue_tracker|Support it through the issue tracker]]
# [[#Maintain_the_code_as_Gramps_continues_to_evolve|Maintain the code]] as Gramps continues to evolve

We'll now expand upon each of these steps individually.

== Develop your addon ==

The [http://github.com/gramps-project/addons-source addons-source] repository holds the source code for the addons with branches holding the version for different gramps. If you are working on an addon for gramps for the current Gramps {{man version}} public release, be sure to use the maintenance/gramps52 git branch, as the default is master branch for the developmental pre-release. (Currently gramps 5.3, which is not the typical target for addons.)

Example commands are shown below referring to the public release rather than the master branch.

The developers are currently merging changes to the most recent maintenance branch into master as necessary, so you don't have to do anything for that unless you are in a hurry.

The [http://github.com/gramps-project/addons-source addons-source] git repository has the following structure, with the code for each addon in its own folder:

* /addons-source
** /''IndividualNameOfAddon1''
** /''IndividualNameOfAddon2''
** ...

The [http://github.com/gramps-project/addons addons] git repository holds built versions of the addons for each release of Gramps, and has the following structure:

* /addons
** [https://github.com/gramps-project/addons/tree/master/gramps42 /gramps42]
*** /download
*** /listings
** [https://github.com/gramps-project/addons/tree/master/gramps50 /gramps50]
*** /download
*** /listings
** [https://github.com/gramps-project/addons/tree/master/gramps51 /gramps51]
*** /download
*** /listings
** [https://github.com/gramps-project/addons/tree/master/gramps52 /gramps52]
*** /download
*** /listings

=== Get a local copy of Gramps and its addons ===

These steps show how to download the addon sources.

# Get an https://github.com/join account if you don't already have one.
# Request GIT write access for the https://github.com/gramps-project/addons-source project by emailing the [[Contact#Mailing_lists|gramps-devel mailing list]]
See also [[Brief_introduction_to_Git|git introduction]] for instructions on installing git and getting basic settings configured. Also [https://help.github.com/articles/generating-an-ssh-key/ Connecting to GitHub with SSH] will help with setting up credentials for GitHub.
To fully build and advertise a new addon will require local copies of the three repositories, the 'addons-source', 'addons' and the main Gramps source 'gramps'.

This wiki assumes that all three git repositories local locations are put into the same base directory and named with the repository names in order for the make.py script commands to work as shown. From the base directory, run the following commands to create a copy of each repository. If you want to use SSH;

git clone git@github.com:gramps-project/addons-source.git addons-source
git clone git@github.com:gramps-project/addons.git addons
git clone git@github.com:gramps-project/gramps.git gramps

or if you want to use a web url:

git clone https://github.com/gramps-project/addons-source.git addons-source
git clone https://github.com/gramps-project/addons.git addons
git clone https://github.com/gramps-project/gramps.git gramps

To switch to a local copy of the gramps52 maintenance branch:

cd addons-source
git checkout -b gramps52 origin/maintenance/gramps52

or to work in the master branch:

cd addons-source
git checkout -b gramps53 origin/master

=== Other prerequisites ===
{{man warn|These instructions, the make.py script etc.|are designed to operate in a Linux environment. {{man menu|They won't work on Windows without modifications.}}}}
* Gramps uses Python version 3.2 or higher. You must have at least that version installed. If you have installed Gramps 4.2 or higher on your Linux system already, then a sufficient version of Python will be present. If you have more than one version of Python installed, then you must use the correct version for these scripts. On some systems, both Python 2.x and 3.x are installed. It is possible that the normal invocation of <code>python</code> starts up Python 2.x, and that to start up Python 3.x requires invoking with <code>python3</code> or <code>python3.4</code> etc. You can test the version by <code>python –version</code> or <code>python3 –version</code>. If this is so, replace any usage of 'python' in the examples below with the appropriate invocation.
* The make.py used in construction of the addons requires that the LANGUAGE environment variable be set to 'en_US.UTF-8'.
* The make.py used in construction of the addons requires that the GRAMPSPATH environment variable be set to your path to the Gramps source tree.
* intltool must be installed;
: <code>sudo apt-get install intltool</code>

For example if your home directory is '/home/name' and you use the suggested path names, use
: <code>GRAMPSPATH=/home/name/gramps LANGUAGE='en_US.UTF-8' python3 make.py ...</code>
to replace the <code>./make.py</code> in the examples below.

=== Create your addon subdirectory ===
* Make a new project directory in addons-source:
: <code>mkdir NewProjectName</code>

===Follow the development API for your tool===
Create your NewProjectName.py and NewProjectName.gpr.py files.

Follow the development API for your tool, [[Report-writing_tutorial|report]], view, or [[Gramplets]]. Place all of your associated .py, .glade, etc. files in this directory. For general information on Gramps development see [[Portal:Developers]] and [[Writing a plugin|Writing a Plugin]] specifically.

=== Test your addon as you develop ===

{{man warn|{{bug|10436}} Symlinks to folders in gramps plugin dir are not scanned}}

To test your addon as you develop it is suggested that you copy your NewProjectName plugin into your Gramps user plugin directory from your addon development directory, prior to testing. Or just edit in the Gramps user plugin directory until it is ready to publish, then copy back to your addon development directory.

Your installed Gramps will search this folder (and subdirectories) for .gpr.py files, and add them to the plugin list.

If you have code that you want to share between addons, you don't need to do anything special. Gramps adds each directory in which a .gpr.py is found onto the PYTHONPATH which is searched when you perform an import. Thus "import NewProjectName" will work from another addon. You should always make sure you name your addons with a name appropriate for Python imports.

=== Commit your changes ===
To commit your changes so that others can see your addon source.

* Remove the files using the ''clean'' command that should not be added to GitHub (eg files(template.pot/ locale etc)):
: <code>./make.py gramps52 clean NewProjectName</code>
* Add the project to the repository:
: <code>git add NewProjectName</code>
* Commit it with an appropriate message
: <code>git commit -m "A message describing what this addon is"</code>

Before committing additional edits to your addon, you should:

* to make sure that outside changes do not affect your commit
: <code>git pull --rebase</code>
* only the files you changed should be in this list
: <code>git status</code>
* Commit it with an appropriate message
: <code>git commit -m "A message describing the changes"</code>

If you have been given 'push' rights to GitHub 'gramps-project/addons-source', and when you are sure you are done and want to publish to the repository:

* to make sure that outside changes do not affect your commit
: <code>git pull --rebase</code>
: <code>git push origin gramps52</code>

Also you may want to [[Addons_development#Package_your_addon |Package your addon]] so it can be downloaded via the plugin manager.

=== Config ===

Some addons may want to have persistent data (data settings that remain between sessions). You can handle this yourself, or you can use Gramps' built-in configure system.

At the top of the source file of your addon, you would do this:

from config import config as configman
config = configman.register_manager("grampletname")
# register the values to save:
config.register("section.option-name1", value1)
config.register("section.option-name2", value2)
...
# load an existing file, if one:
config.load()
# save it, it case it didn't exist:
config.save()

This will create the file "grampletname.ini" and put in the same directory as the addon. If the config file already exists, it remains intact.

In the addon, you can then:

x = config.get("section.option-name1")
config.set("section.option-name1", 3)

and when this code is exiting, you might want to save the config. In a Gramplet that would be:

def on_save(self):
config.save()

If your code is a system-level file, then you might want to save the config in the Gramps system folder:

config = configman.register_manager("system", use_config_path=True)

This, however, would be rare; most .ini files would go into the plugins directory.

In other code that might use this config file, you would do this:

from config import config as configman
config = configman.get_manager("grampletname")
x = config.get("section.option-name1")

=== Localization ===

For general help on translations in Gramps, see [[Coding for translation]]. However, that will only use translations that come with Gramps, or allows you to contribute translations to the Gramps core. To have your own managed translations that will be packaged with your addon, read the rest of this page.
Note that these instructions will only work for Python strings, if you have a glade file, it will not get translated.

For any addon which you have translations into other languages, you will need to add a way to retrieve the translation. You need to add this to the top of your NewProjectName.py file:

from gramps.gen.const import GRAMPS_LOCALE as glocale
_ = glocale.get_addon_translator(__file__).gettext

Then you can use the standard "_()" function to translate phrases in your addon.

You can use one of a few different types of translation functions:

# gettext
# lgettext
# ngettext
# lngettext
# sgettext

These have become obsolete in Gramps 4; gettext, ngettext, and sgettext always return translated strings in unicode for consistent portability between Python 2 and Python3.

See the [http://docs.python.org/3/library/gettext.html#the-gnutranslations-class python documentation] for documentation of gettext and ngettext. The "l" versions return the string encoded according to the [http://docs.python.org/3/library/locale.html#locale.setlocale currently set locale]; the "u" versions return unicode strings in Python2 and are not available in Python 3.

'''sgettext''' is a Gramps extension that filters out clarifying comments for translators, such as
_("Remaining names | rest")
Where "rest" is the English string that we want to present and "Remaining names" is a hint for translators.

==== Commands to compile translations ====

To build and compile translations for all projects to their download/Addon.addon.tgz files:

: <code>python3 make.py gramps52 build all</code>

To compile translations for all projects :

: <code>python3 make.py gramps52 compile all</code>

== Create a Gramps Plugin Registration file ==

First, create the NewProjectName.gpr.py file. The registration takes this general form:

<pre>
register(PTYPE,
gramps_target_version = "5.2",
version = "1.0.0",
ATTR = value,
)
</pre>

[https://github.com/gramps-project/gramps/blob/master/gramps/gen/plug/_pluginreg.py#L76 PTYPE] is TOOL, GRAMPLET, REPORT, QUICKVIEW, IMPORT, EXPORT, DOCGEN, GENERAL, MAPSERVICE, VIEW, or RELCALC.

ATTR depends on the PTYPE. But you must have '''gramps_target_version''' and addon '''version'''. '''gramps_target_version''' should be a string of the form "X.Y" version number matching Gramps X major, Y minor integer. '''version''' is a string of the form "X.Y.Z" representing the version of your addon. X, Y, and Z should all be integers.

Be sure to include attributes for author name(s) and email(s) in the form of an array of comma-separated strings. There is an additional set of attributes, '''maintainers''' and '''maintainers_email'''. If you, the author, are also the maintainer it will be identical to the author attributes, but you may also designate a maintainer, in which case the maintainer will become the primary point of contact.

Here is a sample Tool GPR file:

<pre>
register(TOOL,
id = 'AttachSource',
name = _("Attach Source"),
description = _("Attaches a shared source to multiple objects."),
version = '1.0.0',
gramps_target_version = '5.2',
status = STABLE,
fname = 'AttachSourceTool.py',
authors = ["Douglas S. Blank"],
authors_email = ["doug.blank@gmail.com"],
maintainers = ["Douglas S. Blank"],
maintainers_email = ["doug.blank@gmail.com"],
category = TOOL_DBPROC,
toolclass = 'AttachSourceWindow',
optionclass = 'AttachSourceOptions',
tool_modes = [TOOL_MODE_GUI]
)
</pre>

You can see examples of the kinds of addons [https://github.com/gramps-project/gramps/plugins here] (for example, see [https://github.com/gramps-project/gramps/plugins/drawreport/drawplugins.gpr.py gramps/plugins/drawreport/drawplugins.gpr.py]) and see the full documentation in the [https://github.com/gramps-project/gramps/blob/3f0db9303f29811b43325c30149c8844c7ce24b6/gramps/gen/plug/_pluginreg.py#L23 master/gramps/gen/plug/_pluginreg.py] comments and docstrings.

Note that this .gpr.py will automatically use translations if you have them (see below). That is, the function "_" is predefined to use your locale translations; you only need to mark the text with _("TEXT") and include a translation of "TEXT" in your translation file. For example, in the above example, _("Attach Source") is marked for translation. If you have developed and packaged your addon with translation support, then that phrase will be converted into the user's language.

=== Report plugins ===
The possible report categories are ([https://github.com/gramps-project/gramps/blob/892fc270592095192947097d22a72834d5c70447/gramps/gen/plug/_pluginreg.py#L141-L149 gen/plug/_pluginreg.py]):
<pre>
#possible report categories
CATEGORY_TEXT = 0
CATEGORY_DRAW = 1
CATEGORY_CODE = 2
CATEGORY_WEB = 3
CATEGORY_BOOK = 4
CATEGORY_GRAPHVIZ = 5
CATEGORY_TREE = 6
REPORT_CAT = [ CATEGORY_TEXT, CATEGORY_DRAW, CATEGORY_CODE,
CATEGORY_WEB, CATEGORY_BOOK, CATEGORY_GRAPHVIZ, CATEGORY_TREE]
</pre>

Each report category has a set of standards and interface. The categories CATEGORY_TEXT and CATEGORY_DRAW use the Document interface of Gramps. See also [[Report API]] for a draft view on this.

The application programming interface or API for reports is treated at [[Report-writing_tutorial]]. For general information on Gramps development see [[Portal:Developers]] and [[Writing a plugin|Writing a Plugin]] specifically.

=== General plugins ===

The plugin framework also allows you to create generic plugins for use. This includes the ability to create libraries of functions, and plugins of your own design.

==== Example: A library of functions ====

In this example, a file name library.py will be imported at time of registration (when Gramps starts):

<pre>
# file: library.gpr.py

register(GENERAL,
id = 'My Library',
name = _("My Library"),
description = _("Provides a library for doing something."),
version = '1.0',
gramps_target_version = '5.2',
status = STABLE,
fname = 'library.py',
load_on_reg = True,
)
</pre>

The code in the file library.py will be imported when Gramps begins. You can access the loaded module in other code by issuing an "import library" as Python keeps track of files already imported. However, the amount of useful code that you can run when the program is imported is limited. You might like to have the code do something that requires a dbstate or uistate object, and neither of these is available when just importing a file.

If "load_on_reg" was not True, then this code would be unavailable until manually loaded. There is no automatic mechanism in Gramps to load GENERAL plugins automatically.

In addition to importing a file at startup, one can also run a single function inside a GENERAL plugin, and it will be passed the dbstate, the uistate, and the plugin data. The function must be called "load_on_reg", and take those three parameters, like this:

<pre>
# file: library.py

def load_on_reg(dbstate, uistate, plugin):
"""
Runs when plugin is registered.
"""
print("Hello World!")
</pre>

Here, you could connect signals to the dbstate, open windows, etc.

Another example of what one can do with the plugin interface is to create a general purpose plugin framework for use by other plugins. Here is the basis for a plugin system that:

* allows plugins to list data files
* allows the plugin to process all of the data files

First, the gpr.py file:

<pre>

register(GENERAL,
id = "ID",
category = "CATEGORY",
load_on_reg = True,
process = "FUNCTION_NAME",
)
</pre>

This example uses three new features:

# GENERAL plugins can have a category
# GENERAL plugins can have a load_on_reg function that returns data
# GENERAL plugins can have a function (called "process") which will process the data

If you (or someone else) create additional general plugins of this category, and they follow your load_on_reg data format API, then they could be used just like your original data. For example, here is an additional general plugin in the 'WEBSTUFF' category:

<pre>
# anew.gpr.py

register(GENERAL,
id = 'a new plugin',
category = "WEBSTUFF",
version = '1.0',
gramps_target_version = '5.2',
data = ["a", "b", "c"],
)
</pre>

This doesn't have load_on_reg = True, nor does it have a fname or process, but it does set the data directly in the .gpr.py file. Then we have the following results:

<pre>
>>> from gui.pluginmanager import GuiPluginManager
>>> PLUGMAN = GuiPluginManager.get_instance()
>>> PLUGMAN.get_plugin_data('WEBSTUFF')
["a", "b", "c", "Stylesheet.css", "Another.css"]
>>> PLUGMAN.process_plugin_data('WEBSTUFF')
["A", "B", "C", "STYLESHEET.CSS", "ANOTHER.CSS"]
</pre>

=== Registered GENERAL Categories ===

The following are the published secondary plugins API's (type GENERAL, with the following categories):

==== WEBSTUFF ====

A sample gpr.py file:

<pre>
# stylesheet.gpr.py

register(GENERAL,
id = 'system stylesheets',
category = "WEBSTUFF",
name = _("CSS Stylesheets"),
description = _("Provides a collection of stylesheets for the web"),
version = '1.0',
gramps_target_version = '5.2',
fname = "stylesheet.py",
load_on_reg = True,
process = "process_list",
)
</pre>

Here is the associated program:

<pre>
# file: stylesheet.py

def load_on_reg(dbstate, uistate, plugin):
"""
Runs when plugin is registered.
"""
return ["Stylesheet.css", "Another.css"]

def process_list(files):
return [file.upper() for file in files]
</pre>

==== Filters ====

For example:

<pre>
register(GENERAL,
category="Filters",
...
load_on_reg = True
)
</pre>

<pre>
def load_on_reg(dbstate, uistate, plugin):
# returns a function that takes a namespace, 'Person', 'Family', etc.

def filters(namespace):
print("Ok...", plugin.category, namespace, uistate)
# return a Filter object here
return filters
</pre>



== List the Prerequistes your addon depends on ==

''In your gpr file, you can have a line like:

<code>depends_on = ["libwebconnect"]</code>

which is a list of id's from other gpr files. This example will ensure that [[Addon:Web_Connect_Pack#Prerequisites|libwebconnect]] is loaded before your addon. If it can't be found, or you have a cycle, then your addons won't be loaded.

example code used in the Addon:Web_Connect_Pack that references libwebconnect Prerequistes [https://github.com/gramps-project/addons-source/blob/1304b65a7d758bfe17339c26260473ac3e9c4061/RUWebConnectPack/RUWebPack.gpr.py#L17 RUWebPack.gpr.py#L17 ]

This means that common Prerequistes can be shared between addons and that code sits in its own gpr/addon file.



== Get translators to translate your addon into multiple languages ==

If you [[#Localization|designed for localization]], the addon will begin supporting a single language. Make your addon inviting for volunteers to translate it into their native language.
* Initialize and update the <code>template.pot</code> for your addon:
: <code>cd ~/addons-source</code>
: <code>./make.py gramps52 init NewProjectName</code>
* You should edit the header of <code>template.pot</code> with your information, so it gets copied to individual language files.
* Initialize a language for your addon (say French, fr):
: <code>./make.py gramps52 init NewProjectName fr</code>
* Update it from gramps and other addons:
: <code>./make.py gramps52 update NewProjectName fr</code>
* Edit the translations file manually:
: <code>/NewProjectName/po/fr-local.po</code>
* Compile the language:
: <code>./make.py gramps52 compile NewProjectName</code>
* Add or update your local language file, and commit changes:
: <code>git add NewProjectName/po/fr-local.po</code>
: <code>git commit NewProjectName/po/fr-local.po -m "Added fr po file"</code>
* If you have been given 'push' rights to GitHub 'gramps-project/addons-source', then;
: <code>git push origin gramps52</code>

== Package your addon ==

To create a downloadable package:

: <code>./make.py gramps52 build NewProjectName</code> or
: <code>./make.py gramps53 build NewProjectName</code> for the master branch.

This will automatically include the following files in your build:

* *.py
* *.glade
* *.xml
* *.txt
* locale/*/LC_MESSAGES/*.mo

Starting with Gramp 5.0, if you have additional files beyond those listed above, you should create a MANIFEST file in the root of your addon folder listing the files (or pattern) one per line, like this sample MANIFEST file:

<pre>
README.md
extra_dir/*
help_files/docs/help.html
</pre>

{{man note|Note:|Running the command <code>make.py xxx build</code> will increment the third number in your dotted version number of all addons in the <code>*.gpr.py</code> file. Consider this number to be a "build number".}}

This will leave your 'addons-source' with untracked changes according to git. You should delete the 'NewProjectName/locale' directory. The updated 'NewProjectName/NewProjectName.gpr.py ' is ready to add and commit the next time you make other changes.
: <code>rm –rf –v 'NewProjectName/locale'</code>

Then add the package to GitHub:

<pre> cd '~/addons'
git add gramps52/download/NewProjectName.addon.tgz
git commit -m "Added new plugin: NewProjectName"</pre>
or (for the master branch);
<pre> cd '~/addons'
git add gramps53/download/NewProjectName.addon.tgz
git commit -m " Added new plugin: NewProjectName"</pre>

== List your addon in the Gramps Plugin Manager==

{{man warn|Gramps needs to have been built|Make sure you have already built gramps52 or master. Change to the appropriate git branch in your gramps directory, and run <code>python3 setup.py build</code> See [[Linux:Build_from_source]]}}

To create a listing:

: <code>cd '~/gramps-addons'</code> or wherever you have built your addon
: <code>GRAMPSPATH=path/to/your/gramps/install ./make.py gramps52 listing NewProjectName</code>
or (for the master branch);
: <code>cd '~/gramps-addons'</code> or wherever you have built your addon
: <code>GRAMPSPATH=path/to/your/gramps/install ./make.py gramps53 listing NewProjectName</code>

That will create a series of files in the <tt>../listings/</tt> directory.

Then add the updated listing to GitHub:

<pre> cd '~/addons'
git add gramps52/listings/*
git commit -m "Added new plugin to listings: NewProjectName"</pre>
or (for the master branch);
<pre> cd '~/addons'
git add gramps53/listings/*
git commit -m " Added new plugin to listings: NewProjectName"</pre>

== List and document your addon on the wiki==

===List your addon===
Add a short description of your addon to the Addons list by editing the current release listing eg: [[5.2_Addons]] or if the addon is meant for a future release [[5.3_Addons]] when available.

==== Example addon template ====
Examine the listing for other addons and refer to the [[Addon list legend]] for details of on the meaning of each columns.
<pre>
|- 
|
|
|
|
|
|
|
|
|-
</pre>

===Document your addon===
Document the addon in the wiki using the page name format of {{man menu|Addon:NewProjectName}} examine the other addon support pages for the general format to use.
{{man tip|Hint on creating a new wiki page.|To create a new wiki page use the search box to search for the name of your page that doesn't exist then on the search results page you will be provided with a link to create the new page, by selecting and you can add your content}}

====Example addon article====
Consider including the following information:

<pre>

{{Third-party plugin}}


== Usage ==

=== Configure Options ===

==Features==

== Prerequisites ==

== Issues ==


[[Category:Addons]]
[[Category:Plugins]]
[[Category:Developers/General]]
</pre>

== Announce the addon ==
Join the [[Contact#Forum|Gramps Forum]] and announce it to the users with general information on why you created and how to use it.

== Support it through issue tracker ==

Become a user on the [https://gramps-project.org/bugs/view_all_bug_page.php Gramps MantisBT (Mantis BugTracker)].
and please check it regularly. There is no automated notification of issues (and possible feature requests) related to your addon when reported by users.

Users tend to not understand coding and they make assumptions. So be kind and guiding if a report is ambiguous or inaccurate. A negative remark from an addon developer or anyone can be very discouraging.

== Maintain the code as Gramps continues to evolve ==

{{man tip|When submitting an update the patch part of the version number MAJOR.MINOR.PATCH is updated during the addon build process e.g. 1.1.3 to 1.1.4|You can find this step in [https://github.com/gramps-project/addons-source/blob/master/make.py#L125 addons-source/make.py].[https://gramps.discourse.group/t/should-addons-pr-include-version-number-update/2591]}}

Remember that Gramps addons exist for many reasons and there are many Gramps developers that do support addons in various ways (translations, triage, keeping in sync with master, download infrastructure, etc).

Some reasons why the addons exist; they provide:
* A quick way for anyone to share their work; the Gramps-project has never denied adding a addon.
* A method to continuously update and develop a stand-alone component, often before being officially accepted.
* A place for controversial plugins that will never be accepted into core, but are loved by many users (eg, Data Entry Gramplet).
* A place for experimental components to live.

== Example code adding common enhancements ==
* Copy all the Gramplet's output to a system clipboard via context pop-up menu : Enhancement request {{bug|11573}}, [https://github.com/gramps-project/gramps/pull/1014/commits/72012e13b4ca15caca4b7f36fdb9702c1fd470fd example pull]
* add a custom [[Gramps_Glossary#viewmode|View Mode]] toolbar icon via the <code>.gpr.py</code> : [https://github.com/gramps-project/gramps/pull/1017 Pull 1017 Discussion], [https://github.com/gramps-project/gramps/pull/1017/commits/76e41d546d6ec519dd78fbe07f663135b5c79351 example Pull]

= Resources =
* [[Brief_introduction_to_Git|Git introduction]]
* [[Getting started with Gramps development]]
* [[Portal:Developers]]
* [https://gramps-project.org/docs/gen/gen_plug.html?highlight=include_in_listing#module-gramps.gen.plug._pluginreg Registration Module]

;Gramps Addons site for Gramps 4.2 and newer
* https://github.com/gramps-project/addons-source - Source code (Git)
* https://github.com/gramps-project/addons - downloadable .tgz files
;Gramps Addons site for Gramps 4.1 and older
* For 4.1.x and earlier, see [[Addons development old]].
= Addon Development Tutorials and Samples =
* [[Report-writing_tutorial|Report-writing Tutorial]]
* [[Quick_Views|Quick Views]]
* [[Gramplets|Gramplets]]
* [[Develop_an_Add-on_Rule|Develop an Add-on Rule]]
* [[Develop_an_Add-on_Tool|Develop an Add-on Tool]]
* [[Adapt_a_built-in_Report|Adapt a built-in Report]]

[[Category:Developers/General]]
[[Category:Developers/Tutorials]]
[[Category:Plugins]]
[[Category:Reports]]
[[Category:Gramplets]]
[[Category:Addons]]

Developer policies

2024-06-26T20:03:53Z

Codefarmer: Add note that Black formatter checks for code formatting compliance.

This document collects the different policies the Gramps developer community has adopted.

== Coding policies ==
=== License ===
Gramps is a GPLv2 licensed application with the possibility to use a later version of the GPL (GPLv3). There are no plans at the moment to move to GPLv3 and drop GPLv2. See [[Project License]] for details.

=== Coding style ===
Follow the Gramps [[Programming guidelines]] - which mostly refer to PEP8 with a few additions. Gramps CI checks PRs for compliance using the [https://github.com/psf/black Black] formatter.

All source files shall include conforming [[Source file headers]].

=== GUI design ===
User interfaces shall conform to the agreed upon [[UI style]].

=== Acceptable changes ===
You should follow the [[:Category:Developers/Roadmap|roadmap]] set out for the next release. Only minor features or new reports/gramplets/... can still be added to the roadmap after it has been made official. Add your changes to the [[:Category:Developers/Roadmap|roadmap]] (on this wiki and in the bug tracker) so others are notified what you work on. Seek approval for your changes via the ''gramps-devel'' mailing list.

== Commit policies ==
=== General ===
Read [[Committing policies]]

=== Becoming an official developer ===
The road to become an official developer is as follows:
* Fix bugs on the bug tracker and participate in the ''gramps-devel'' mailing list.
* Accept the guidance from existing developers. If you do not agree with them, you need to convince them. To do that, first consider coding what is asked for and pointing out the weakness afterward, i.e. let the code speak for you.
* Take up a feature request after assuring yourself (e.g. via the ''gramps-devel'' mailing list) the feature will probably be accepted by the developers. Let your code be reviewed.
* Once you come to the conclusion your code needs little change before commit, ask the technical architect (Nick) to send you an invitation to join the GitHub ''Developers'' team. If you have not had contact with the technical architect yet, ask one of the other developers to vouch for you.
* Even after you obtained commit rights, consider a review of your code by other developers by submitting a pull request or using the bug tracker (send reminder) or the ''gramps-devel'' mailing list.

[[Category:Developers/General]]

Programming guidelines

2024-06-26T20:03:16Z

Codefarmer: Add note that Black formatter checks for code formatting compliance.

In a multi-programmer environment, it is important to follow common coding guidelines to make sure the code remains maintainable.

== Coding style ==

=== PEP8 ===
* Write [https://www.python.org/dev/peps/pep-0008/ PEP 8] compatible code! This is important to have a consistent, readable codebase.
** it is not explicit in PEP8, but we like a space after a comma

=== Tabs ===
* Do not use TABs. Use space characters. In Gramps we use 4 spaces for indentation. This does not mean you must set your TAB stops to 4. TABs and indents are not the same thing. Most editors have a configuration option to set indentation and TAB stops. Be careful to just set the '''indentation''' to 4, which automatically means it has to be '''spaces'''. (TABs are still necessary, in Makefiles for example, and they '''have to''' be equivalent to 8 spaces, '''always'''.) To summarize:
** uses spaces, no TABs
** indentation is 4
** TAB stops (if any) are at position 9,17,25,... (first column is 1)

=== Members names ===
* Private class functions (functions that cannot be called outside the class) should be preceded with two underscores.
* Protected functions (functions that can only be called by the class or derived classes) should be preceded with one underscore.
<pre>
def __private_function(self):
pass

def _protected_function(self):
pass
</pre>

=== Callbacks ===

Names of callbacks should be prefixed by 'cb_'. For example, <code>cb_my_callback</code>.

<code>pylint</code> does not check that arguments are used when methods are named in this way. This is useful to avoid the <code>pylint</code> warning: 'W0613: Unused argument <arg>'.

=== Imports ===
The top module is called gramps, and it has following submodules:
* gen
* cli
* gui
* plugins
The other dirs should not contain code, or are for testing.

Within a submodule, only relative imports are allowed of the own submodule (so starting with . or with a module of the own directory), and absolute imports of other submodules (so starting with <code>gramps.</code>)

{{man note|Important:|files in the gen submodule are '''not''' allowed to import files from the other submodules. So <code>gen</code> should be self-contained.}}

== Class headers ==
* Each class should have a simple header to help mark it in the file. This is not used for documentation - it is used to help find the class when multiple classes exist in the same file.
<pre>
#------------------------------------------------------------
#
# MyClass
#
#------------------------------------------------------------
</pre>

== Docstrings ==
* Python provides a docstrings to document classes and functions. If the class is a class used by others (such as the [http://www.gramps-project.org/docs/gen/gen_lib.html#module-gen.lib gen lib] classes), the docstrings should follow the restructuredtext ([http://docutils.sourceforge.net/docs/user/rst/quickstart.html#structure rst]) format. This allows us to extract [http://www.gramps-project.org/docs/ API] documentation using sphinx.

* Apart from adding doc strings to classes and functions, also the api generating rst files must be edited so as to extract the documentation. These files are in the [https://github.com/gramps-project/gramps/tree/master/docs docs directory], for info read the [https://github.com/gramps-project/gramps/blob/master/docs/README.txt /docs/README.txt] file.

:More info
:* [http://www.sphinx-doc.org/en/stable/markup/ Sphinx for python]
:* [http://www.sphinx-doc.org/en/stable/rest.html doc with sphinx]

Classes that are not core reusable classes do not have to follow this format (although we encourage you do), but should be documented using docstrings.
<pre>
class MyClass:
"""
MyClass is a sample class.
"""

def my_function(self):
"""
The my_function task serves no purpose whatsoever.
"""
pass
</pre>

== Black ==
Gramps CI checks for code formatting compliance using [https://github.com/psf/black Black]. When a PR fails the check, code which requires changes is shown in the Checks tab in the Lint panel. You may update the code manually to make it pass, or integrate Black formatter with your preferred editor to ensure that the check will pass. When using Black locally, use the same version as the CI system to ensure formatting consistency.

== Pylint ==
* Run <code>pylint</code> on your code before checking in.
* New files shall have a Pylint score of 9 or higher. New files will not be accepted if they have a Pylint score lower than 9.
* Any changes to existing files with a Pylint score lower than 9 shall not reduce the Pylint score. It is expected that over time, this policy will cause all files to eventually have a score of 9 or higher.

Note that you must run <code>pylint</code> in the <code>gramps</code> directory. If import errors still occur, add a PYTHONPATH. Example usage:
me@laptop:~/programs/master/src$ PYTHONPATH=plugins/lib/ pylint --include-ids=y --reports=y plugins/mapservices/googlemap.py
Set reports to '''n''' to have less output. Information on the meaning of codes can be found here:
* [http://pylint-messages.wikidot.com/all-codes All codes], PyLint Messages: and what they're trying to tell you

== Best practices ==
* Always develop with [[Coding_for_translation|language translation]] in mind

* Reduce dependencies (imports) between files.

* Think on [[Accessibility]].

[[Category:Developers/General]]
[[Category:Developers/Quality Assurance]]

Using the bug tracker

2024-01-21T21:19:50Z

Codefarmer: Include addon version in the bug report

{{languages|Using the bug tracker}}
{{man tip|The bug/issue tracker for Gramps|is located at the following URL: <code>https://www.gramps-project.org/bugs</code>}}
This bug/issue tracker allows users and developers to log new issues and track them as they progress. Please take some time to read the issue tracker instructions below and read '''[[How to create a good bug report|how to create a good bug report]]'''. Also, have a look at '''[[Known_issues|known issues]]''' and '''[[Common_problems|common problems]]'''.

== Quick recommendations ==
When composing a problem (bug) report for Gramps:
* Be '''''precise'''''
* Be '''''clear''':'' explain how to reproduce the problem, step by step, so others can reproduce the bug, or understand the request.
* Include only '''''one problem per report'''''
* Include any relevant links and '''''examples'''''
{{man tip|Before you create a "Bug" report...|Composing a bug report can involve a lot of research and writing effort. Save yourself from unnecessary work.<ul><li>A solution or workaround might already exist in another bug report or in the forums.</li><li>If you connot find anything resembling your issue, ask about it in one of the forums. The community will help you solve or isolate the problem.</li></ul> }}

==Report a bug==
===1. Login===
To report a bug or raise a feature request, you must have a login account on the '''Gramps bug tracker''' ''([https://www.mantisbt.org/ powered by MantisBT])'':
* [https://bugs.gramps-project.org {{man button|Login}}] to your account at https://gramps-project.org/bugs/login_page.php , or;
* Select [https://gramps-project.org/bugs/signup_page.php {{man button|Signup for a new account}}] or visit the following link to create a new login account: https://gramps-project.org/bugs/signup_page.php .

Due to periodic SPAMbot activity, New Account requests might require human pre-approval. Be aware that this means that it might take up to 12 hours before a confirmation email is sent when creating a user account. Only after clicking on the link in the confirmation email can you submit bugs. Your email address will be handled confidentially.

{{-}}

===2. Search wiki and existing bugs===
[[File:Search box for existing bugs.png|thumb|right|450px|Search Box]]
Sometimes the behavior being observed might seem odd, yet as-designed. So the first step is to search the wiki to see what the documented behavior is. If you're still not sure, ask the [https://forum.gramps-project.org/ Gramps community on Discourse.]

If it still appears to be a bug, perhaps the bug you want to report has been reported before. To check this, click on [https://gramps-project.org/bugs/view_all_bug_page.php {{man button|View Issues}}]. The top of the page is reserved for filters, which you set. Normally the default filters are just fine. Under these filters, there is a {{man label|Search}} box. Enter the terms best describing the bug, and click {{man button|Apply Filter}} to search. If you have an error message, try pasting a part of the error, to see if it is has been reported already.

If the bug is already reported, read over the bug report, and see if you can add to the information. If so, you can leave a note with extra information to help the developers.
{{-}}

===3. Submit new bug===
[[File:Report issue buttons Gramps bugs.png|thumb|right|450px|'Report Issue' buttons.]]
Click on one of the {{man label|Report Issue}} buttons, and enter the required information, see below on how to select the project to which the bug belongs. Be verbose, the developers are bad at mind reading. We shall mercilessly close the bugs which have no meaningful information at all, such as #{{bug|7126}}. Do not forget to list the Gramps version you are using. You can check this in Gramps by clicking in the Gramps program the Help menu, option About.
{{-}}
==== How to proceed ====
[[File:Dropdown-Choose-Project-GrampsBugtracker.png|thumb|right|450px|Choose Project - selection list]]
The first step in submitting an issue on the tracker is to determine which project it belongs to on the issue tracker from the '''Select Project''' box, use the '''Choose Project''' drop down list to select the "project" for the bugs. "Projects" are a way to categorize issues. There are two types of projects in the issue tracker, '''Feature Requests''' and '''Gramps''':

*The '''Feature Requests''' project is a place for recording requests for new features.
**If the issue represents functionality that does not currently exist in Gramps, then the issue should be filed under the '''Feature Requests''' project.

*The '''Gramps''' project is a place for recording all issues with Gramps.
**If the issue represents a problem with functionality that has been released in a stable release or a problem with functionality that only exists in the master branch, then the issue should be filed under the Gramps project.

* For bug reports and feature requests relating to Gramps Web, see [https://www.grampsweb.org/help/ | Get Help - Gramps Web]
{{-}}

==== Enter Issue Details ====
[[File:Enter Issue Details page Gramps bugs.png|thumb|right|550px|Enter Issue Details - page]]
The {{man label|Enter Issue Details}} page is where you share with the developers what your issue or feature request is.

Try and complete all the relevant sections as well as you can and be prepared to answer follow up questions if your report needs clarification. Here's a concise guide on '''[[How to create a good bug report]]''' for Gramps which will greatly increase the chances of reproducibility and thus being fixed.

===== Filling out the page =====

* Select Profile
** Gramps runs on multiple operating systems, so it's important to know which operating system and version you are reporting an issue against. This is where you provide that information. MantisBT allows you store multiple profiles in your Account so that you can pick the appropriate one, which is handy if you run Gramps on different system configurations.
* Product Version
**The projects with names that look like '''Gramps x.x.X''' are where issues are reported that apply specifically to a maintenance branch (see [[Brief_introduction_to_Git#Types_of_branches|Types of Branches]]). A separate project exists for each maintenance branch.
**For recording issues that ''only'' apply to the master branch in Git (see [[Brief_introduction_to_Git#Types_of_branches|Types of Branches]]), use next un-released version e.g.: 5.3.0 as shown on the [https://gramps-project.org/bugs/roadmap_page.php| MantisBT Roadmap].
* Addon Version
** If you are reporting a bug in an addon, use the Plugin Manager or Enhanced Plugin Manager to find the version of the addon and include it in the report.
{{-}}

==Useful MantisBT bug tracker Syntax codes==

The following are useful [http://www.mantisbt.org/ MantisBT bug tracker] syntax codes you can use:
* Using ''<code>#</code>'' before a bug number writes a link to the bug. eg: ''<code>#1</code>'' becomes {{bug|1}}
* Use ''<code>@</code>'' before a user name to mention a person (note: user names with embedded spaces are not supported)
* Using ''<code>~</code>'' before a comment number writes a link to the comment, same as : ''<code>{url}#c{comment number}</code>''. eg: ''<code>~3</code>'' becomes [https://gramps-project.org/bugs/view.php?id=1#c3]
* To link a GitHub Pull Request in the bug tracker, use p:gramps:nnnn: where nnnn is the PR number.

=== Limited HTML tags ===
* A [https://github.com/mantisbt/mantisbt/blob/55fb5721ea7d980557da484390db5c6003b63cd0/config_defaults_inc.php#L1979 limited set] of [https://www.w3schools.com/tags/ HTML tags] can be used in the text field:
**<code> </code> to define a paragraph.
**<code> <li></code> to defines a [https://www.w3schools.com/tags/tag_li.asp list item] used with:
***<code> <ul></code> unordered lists
***<code> <ol></code> ordered lists
**<code> </code> to insert a single line break.
**<code> <pre> </pre></code> to add preformatted text, that is displayed in a fixed-width font, and it preserves both spaces and line breaks.
**<code> </code> usually displays text in ''italics''.
**<code> </code> shows '''bold''' text
**<code> </code> Underline a misspelled word
**<code> </code> It renders as emphasized text.
**<code> </code> It defines important text.

==See also==
* [[How to create a good bug report]]
* [[Known issues]]
* [[Common problems]]
* Help the Gramps project [[Bug triage]]

MantisBT.org reports providing user-oriented (''not'' admin) documentation
* [https://www.mantisbt.org/bugs/view.php?id=5070 0005070]: I have written [MantisBT] quick-start documentation [.doc, .pdf, .swx] if you’re interested
* [https://www.mantisbt.org/bugs/view.php?id=8939 0008939]: Lifecycle model [Visio] for a report in MantisBT

[[Category:Developers/General]]
[[Category:Developers/Quality Assurance]]

Talk:Brief introduction to Git

2024-01-18T19:22:14Z

Codefarmer: /* Anchor for Making a PR */ new section

== Anchor for Making a PR ==

@daleathan In a prior revision the anchor for Making a PR was set to

[ [ Brief_introduction_to_Git#Making_a_Pull_Request_.28PR.29_on_Github|Making a Pull Request (PR) on Github ] ]

Curious, is there a particular reason for setting it to "#Making_a_Pull_Request_.28PR.29_on_Github" ? Gramps' CONTRIBUTING file ( https://github.com/gramps-project/gramps/blob/892fc270592095192947097d22a72834d5c70447/CONTRIBUTING ) expects it to be:

https://gramps-project.org/wiki/index.php?title=Brief_introduction_to_Git#Making_a_PR

Can we revert to the previous? Is there a way to find out if there are any references to the current anchor and replace those as well?

Using the bug tracker

2023-12-29T17:05:21Z

Codefarmer: Pointer to bug reporting for Gramps Web

{{languages|Using the bug tracker}}
{{man tip|The bug/issue tracker for Gramps|is located at the following URL: <code>https://www.gramps-project.org/bugs</code>}}
This bug/issue tracker allows users and developers to log new issues and track them as they progress. Please take some time to read the issue tracker instructions below and read '''[[How to create a good bug report|how to create a good bug report]]'''. Also, have a look at '''[[Known_issues|known issues]]''' and '''[[Common_problems|common problems]]'''.

== Quick recommendations ==
When composing a problem (bug) report for Gramps:
* Be '''''precise'''''
* Be '''''clear''':'' explain how to reproduce the problem, step by step, so others can reproduce the bug, or understand the request.
* Include only '''''one problem per report'''''
* Include any relevant links and '''''examples'''''
{{man tip|Before you create a "Bug" report...|Composing a bug report can involve a lot of research and writing effort. Save yourself from unnecessary work.<ul><li>A solution or workaround might already exist in another bug report or in the forums.</li><li>If you connot find anything resembling your issue, ask about it in one of the forums. The community will help you solve or isolate the problem.</li></ul> }}

==Report a bug==
===1. Login===
To report a bug or raise a feature request, you must have a login account on the '''Gramps bug tracker''' ''([https://www.mantisbt.org/ powered by MantisBT])'':
* [https://bugs.gramps-project.org {{man button|Login}}] to your account at https://gramps-project.org/bugs/login_page.php , or;
* Select [https://gramps-project.org/bugs/signup_page.php {{man button|Signup for a new account}}] or visit the following link to create a new login account: https://gramps-project.org/bugs/signup_page.php .

Due to periodic SPAMbot activity, New Account requests might require human pre-approval. Be aware that this means that it might take up to 12 hours before a confirmation email is sent when creating a user account. Only after clicking on the link in the confirmation email can you submit bugs. Your email address will be handled confidentially.

{{-}}

===2. Search wiki and existing bugs===
[[File:Search box for existing bugs.png|thumb|right|450px|Search Box]]
Sometimes the behavior being observed might seem odd, yet as-designed. So the first step is to search the wiki to see what the documented behavior is. If you're still not sure, ask the [https://forum.gramps-project.org/ Gramps community on Discourse.]

If it still appears to be a bug, perhaps the bug you want to report has been reported before. To check this, click on [https://gramps-project.org/bugs/view_all_bug_page.php {{man button|View Issues}}]. The top of the page is reserved for filters, which you set. Normally the default filters are just fine. Under these filters, there is a {{man label|Search}} box. Enter the terms best describing the bug, and click {{man button|Apply Filter}} to search. If you have an error message, try pasting a part of the error, to see if it is has been reported already.

If the bug is already reported, read over the bug report, and see if you can add to the information. If so, you can leave a note with extra information to help the developers.
{{-}}

===3. Submit new bug===
[[File:Report issue buttons Gramps bugs.png|thumb|right|450px|'Report Issue' buttons.]]
Click on one of the {{man label|Report Issue}} buttons, and enter the required information, see below on how to select the project to which the bug belongs. Be verbose, the developers are bad at mind reading. We shall mercilessly close the bugs which have no meaningful information at all, such as #{{bug|7126}}. Do not forget to list the Gramps version you are using. You can check this in Gramps by clicking in the Gramps program the Help menu, option About.
{{-}}
==== How to proceed ====
[[File:Dropdown-Choose-Project-GrampsBugtracker.png|thumb|right|450px|Choose Project - selection list]]
The first step in submitting an issue on the tracker is to determine which project it belongs to on the issue tracker from the '''Select Project''' box, use the '''Choose Project''' drop down list to select the "project" for the bugs. "Projects" are a way to categorize issues. There are two types of projects in the issue tracker, '''Feature Requests''' and '''Gramps''':

*The '''Feature Requests''' project is a place for recording requests for new features.
**If the issue represents functionality that does not currently exist in Gramps, then the issue should be filed under the '''Feature Requests''' project.

*The '''Gramps''' project is a place for recording all issues with Gramps.
**If the issue represents a problem with functionality that has been released in a stable release or a problem with functionality that only exists in the master branch, then the issue should be filed under the Gramps project.

* For bug reports and feature requests relating to Gramps Web, see [https://www.grampsweb.org/help/ | Get Help - Gramps Web]
{{-}}

==== Enter Issue Details ====
[[File:Enter Issue Details page Gramps bugs.png|thumb|right|550px|Enter Issue Details - page]]
The {{man label|Enter Issue Details}} page is where you share with the developers what your issue or feature request is.

Try and complete all the relevant sections as well as you can and be prepared to answer follow up questions if your report needs clarification. Here's a concise guide on '''[[How to create a good bug report]]''' for Gramps which will greatly increase the chances of reproducibility and thus being fixed.

===== Filling out the page =====

* Select Profile
** Gramps runs on multiple operating systems, so it's helpful to know which operating system and version you are reporting an issue against. This is where you provide that information. MantisBT allows you store multiple profiles in your Account so that you can pick the appropriate one, which is handy if you run Gramps on different system configurations.
* Product Version
**The projects with names that look like '''Gramps x.x.X''' are where issues are reported that apply specifically to a maintenance branch (see [[Brief_introduction_to_Git#Types_of_branches|Types of Branches]]). A separate project exists for each maintenance branch.
**For recording issues that ''only'' apply to the master branch in Git (see [[Brief_introduction_to_Git#Types_of_branches|Types of Branches]]), use next un-released version e.g.: 5.3.0 as shown on the [https://gramps-project.org/bugs/roadmap_page.php| MantisBT Roadmap].
{{-}}

==Useful MantisBT bug tracker Syntax codes==

The following are useful [http://www.mantisbt.org/ MantisBT bug tracker] syntax codes you can use:
* Using ''<code>#</code>'' before a bug number writes a link to the bug. eg: ''<code>#1</code>'' becomes {{bug|1}}
* Use ''<code>@</code>'' before a user name to mention a person (note: user names with embedded spaces are not supported)
* Using ''<code>~</code>'' before a comment number writes a link to the comment, same as : ''<code>{url}#c{comment number}</code>''. eg: ''<code>~3</code>'' becomes [https://gramps-project.org/bugs/view.php?id=1#c3]
* To link a GitHub Pull Request in the bug tracker, use p:gramps:nnnn: where nnnn is the PR number.

=== Limited HTML tags ===
* A [https://github.com/mantisbt/mantisbt/blob/55fb5721ea7d980557da484390db5c6003b63cd0/config_defaults_inc.php#L1979 limited set] of [https://www.w3schools.com/tags/ HTML tags] can be used in the text field:
**<code> </code> to define a paragraph.
**<code> <li></code> to defines a [https://www.w3schools.com/tags/tag_li.asp list item] used with:
***<code> <ul></code> unordered lists
***<code> <ol></code> ordered lists
**<code> </code> to insert a single line break.
**<code> <pre> </pre></code> to add preformatted text, that is displayed in a fixed-width font, and it preserves both spaces and line breaks.
**<code> </code> usually displays text in ''italics''.
**<code> </code> shows '''bold''' text
**<code> </code> Underline a misspelled word
**<code> </code> It renders as emphasized text.
**<code> </code> It defines important text.

==See also==
* [[How to create a good bug report]]
* [[Known issues]]
* [[Common problems]]
* Help the Gramps project [[Bug triage]]

MantisBT.org reports providing user-oriented (''not'' admin) documentation
* [https://www.mantisbt.org/bugs/view.php?id=5070 0005070]: I have written [MantisBT] quick-start documentation [.doc, .pdf, .swx] if you’re interested
* [https://www.mantisbt.org/bugs/view.php?id=8939 0008939]: Lifecycle model [Visio] for a report in MantisBT

[[Category:Developers/General]]
[[Category:Developers/Quality Assurance]]

Using the bug tracker

2023-12-29T16:51:54Z

Codefarmer: Encourage bug reports to read the good bug reporting wiki.

{{languages|Using the bug tracker}}
{{man tip|The bug/issue tracker for Gramps|is located at the following URL: <code>https://www.gramps-project.org/bugs</code>}}
This bug/issue tracker allows users and developers to log new issues and track them as they progress. Please take some time to read the issue tracker instructions below and read '''[[How to create a good bug report|how to create a good bug report]]'''. Also, have a look at '''[[Known_issues|known issues]]''' and '''[[Common_problems|common problems]]'''.

== Quick recommendations ==
When composing a problem (bug) report for Gramps:
* Be '''''precise'''''
* Be '''''clear''':'' explain how to reproduce the problem, step by step, so others can reproduce the bug, or understand the request.
* Include only '''''one problem per report'''''
* Include any relevant links and '''''examples'''''
{{man tip|Before you create a "Bug" report...|Composing a bug report can involve a lot of research and writing effort. Save yourself from unnecessary work.<ul><li>A solution or workaround might already exist in another bug report or in the forums.</li><li>If you connot find anything resembling your issue, ask about it in one of the forums. The community will help you solve or isolate the problem.</li></ul> }}

==Report a bug==
===1. Login===
To report a bug or raise a feature request, you must have a login account on the '''Gramps bug tracker''' ''([https://www.mantisbt.org/ powered by MantisBT])'':
* [https://bugs.gramps-project.org {{man button|Login}}] to your account at https://gramps-project.org/bugs/login_page.php , or;
* Select [https://gramps-project.org/bugs/signup_page.php {{man button|Signup for a new account}}] or visit the following link to create a new login account: https://gramps-project.org/bugs/signup_page.php .

Due to periodic SPAMbot activity, New Account requests might require human pre-approval. Be aware that this means that it might take up to 12 hours before a confirmation email is sent when creating a user account. Only after clicking on the link in the confirmation email can you submit bugs. Your email address will be handled confidentially.

{{-}}

===2. Search wiki and existing bugs===
[[File:Search box for existing bugs.png|thumb|right|450px|Search Box]]
Sometimes the behavior being observed might seem odd, yet as-designed. So the first step is to search the wiki to see what the documented behavior is. If you're still not sure, ask the [https://forum.gramps-project.org/ Gramps community on Discourse.]

If it still appears to be a bug, perhaps the bug you want to report has been reported before. To check this, click on [https://gramps-project.org/bugs/view_all_bug_page.php {{man button|View Issues}}]. The top of the page is reserved for filters, which you set. Normally the default filters are just fine. Under these filters, there is a {{man label|Search}} box. Enter the terms best describing the bug, and click {{man button|Apply Filter}} to search. If you have an error message, try pasting a part of the error, to see if it is has been reported already.

If the bug is already reported, read over the bug report, and see if you can add to the information. If so, you can leave a note with extra information to help the developers.
{{-}}

===3. Submit new bug===
[[File:Report issue buttons Gramps bugs.png|thumb|right|450px|'Report Issue' buttons.]]
Click on one of the {{man label|Report Issue}} buttons, and enter the required information, see below on how to select the project to which the bug belongs. Be verbose, the developers are bad at mind reading. We shall mercilessly close the bugs which have no meaningful information at all, such as #{{bug|7126}}. Do not forget to list the Gramps version you are using. You can check this in Gramps by clicking in the Gramps program the Help menu, option About.
{{-}}
==== How to proceed ====
[[File:Dropdown-Choose-Project-GrampsBugtracker.png|thumb|right|450px|Choose Project - selection list]]
The first step in submitting an issue on the tracker is to determine which project it belongs to on the issue tracker from the '''Select Project''' box, use the '''Choose Project''' drop down list to select the "project" for the bugs. "Projects" are a way to categorize issues. There are two types of projects in the issue tracker, '''Feature Requests''' and '''Gramps''':

*The '''Feature Requests''' project is a place for recording requests for new features.
**If the issue represents functionality that does not currently exist in Gramps, then the issue should be filed under the '''Feature Requests''' project.

*The '''Gramps''' project is a place for recording all issues with Gramps.
**If the issue represents a problem with functionality that has been released in a stable release or a problem with functionality that only exists in the master branch, then the issue should be filed under the Gramps project.
{{-}}

==== Enter Issue Details ====
[[File:Enter Issue Details page Gramps bugs.png|thumb|right|550px|Enter Issue Details - page]]
The {{man label|Enter Issue Details}} page is where you share with the developers what your issue or feature request is.

Try and complete all the relevant sections as well as you can and be prepared to answer follow up questions if your report needs clarification. Here's a concise guide on '''[[How to create a good bug report]]''' for Gramps which will greatly increase the chances of reproducibility and thus being fixed.

===== Filling out the page =====

* Select Profile
** Gramps runs on multiple operating systems, so it's helpful to know which operating system and version you are reporting an issue against. This is where you provide that information. MantisBT allows you store multiple profiles in your Account so that you can pick the appropriate one, which is handy if you run Gramps on different system configurations.
* Product Version
**The projects with names that look like '''Gramps x.x.X''' are where issues are reported that apply specifically to a maintenance branch (see [[Brief_introduction_to_Git#Types_of_branches|Types of Branches]]). A separate project exists for each maintenance branch.
**For recording issues that ''only'' apply to the master branch in Git (see [[Brief_introduction_to_Git#Types_of_branches|Types of Branches]]), use next un-released version e.g.: 5.3.0 as shown on the [https://gramps-project.org/bugs/roadmap_page.php| MantisBT Roadmap].
{{-}}

==Useful MantisBT bug tracker Syntax codes==

The following are useful [http://www.mantisbt.org/ MantisBT bug tracker] syntax codes you can use:
* Using ''<code>#</code>'' before a bug number writes a link to the bug. eg: ''<code>#1</code>'' becomes {{bug|1}}
* Use ''<code>@</code>'' before a user name to mention a person (note: user names with embedded spaces are not supported)
* Using ''<code>~</code>'' before a comment number writes a link to the comment, same as : ''<code>{url}#c{comment number}</code>''. eg: ''<code>~3</code>'' becomes [https://gramps-project.org/bugs/view.php?id=1#c3]
* To link a GitHub Pull Request in the bug tracker, use p:gramps:nnnn: where nnnn is the PR number.

=== Limited HTML tags ===
* A [https://github.com/mantisbt/mantisbt/blob/55fb5721ea7d980557da484390db5c6003b63cd0/config_defaults_inc.php#L1979 limited set] of [https://www.w3schools.com/tags/ HTML tags] can be used in the text field:
**<code> </code> to define a paragraph.
**<code> <li></code> to defines a [https://www.w3schools.com/tags/tag_li.asp list item] used with:
***<code> <ul></code> unordered lists
***<code> <ol></code> ordered lists
**<code> </code> to insert a single line break.
**<code> <pre> </pre></code> to add preformatted text, that is displayed in a fixed-width font, and it preserves both spaces and line breaks.
**<code> </code> usually displays text in ''italics''.
**<code> </code> shows '''bold''' text
**<code> </code> Underline a misspelled word
**<code> </code> It renders as emphasized text.
**<code> </code> It defines important text.

==See also==
* [[How to create a good bug report]]
* [[Known issues]]
* [[Common problems]]
* Help the Gramps project [[Bug triage]]

MantisBT.org reports providing user-oriented (''not'' admin) documentation
* [https://www.mantisbt.org/bugs/view.php?id=5070 0005070]: I have written [MantisBT] quick-start documentation [.doc, .pdf, .swx] if you’re interested
* [https://www.mantisbt.org/bugs/view.php?id=8939 0008939]: Lifecycle model [Visio] for a report in MantisBT

[[Category:Developers/General]]
[[Category:Developers/Quality Assurance]]

Using the bug tracker

2023-12-29T16:48:52Z

Codefarmer: Remove obsolete reference to 'Gramps Master' project, and direct users to use Product Version field.

{{languages|Using the bug tracker}}
{{man tip|The bug/issue tracker for Gramps|is located at the following URL: <code>https://www.gramps-project.org/bugs</code>}}
This bug/issue tracker allows users and developers to log new issues and track them as they progress. Please take some time to read the issue tracker instructions below and read '''[[How to create a good bug report|how to create a good bug report]]'''. Also, have a look at '''[[Known_issues|known issues]]''' and '''[[Common_problems|common problems]]'''.

== Quick recommendations ==
When composing a problem (bug) report for Gramps:
* Be '''''precise'''''
* Be '''''clear''':'' explain how to reproduce the problem, step by step, so others can reproduce the bug, or understand the request.
* Include only '''''one problem per report'''''
* Include any relevant links and '''''examples'''''
{{man tip|Before you create a "Bug" report...|Composing a bug report can involve a lot of research and writing effort. Save yourself from unnecessary work.<ul><li>A solution or workaround might already exist in another bug report or in the forums.</li><li>If you connot find anything resembling your issue, ask about it in one of the forums. The community will help you solve or isolate the problem.</li></ul> }}

==Report a bug==
===1. Login===
To report a bug or raise a feature request, you must have a login account on the '''Gramps bug tracker''' ''([https://www.mantisbt.org/ powered by MantisBT])'':
* [https://bugs.gramps-project.org {{man button|Login}}] to your account at https://gramps-project.org/bugs/login_page.php , or;
* Select [https://gramps-project.org/bugs/signup_page.php {{man button|Signup for a new account}}] or visit the following link to create a new login account: https://gramps-project.org/bugs/signup_page.php .

Due to periodic SPAMbot activity, New Account requests might require human pre-approval. Be aware that this means that it might take up to 12 hours before a confirmation email is sent when creating a user account. Only after clicking on the link in the confirmation email can you submit bugs. Your email address will be handled confidentially.

{{-}}

===2. Search wiki and existing bugs===
[[File:Search box for existing bugs.png|thumb|right|450px|Search Box]]
Sometimes the behavior being observed might seem odd, yet as-designed. So the first step is to search the wiki to see what the documented behavior is. If you're still not sure, ask the [https://forum.gramps-project.org/ Gramps community on Discourse.]

If it still appears to be a bug, perhaps the bug you want to report has been reported before. To check this, click on [https://gramps-project.org/bugs/view_all_bug_page.php {{man button|View Issues}}]. The top of the page is reserved for filters, which you set. Normally the default filters are just fine. Under these filters, there is a {{man label|Search}} box. Enter the terms best describing the bug, and click {{man button|Apply Filter}} to search. If you have an error message, try pasting a part of the error, to see if it is has been reported already.

If the bug is already reported, read over the bug report, and see if you can add to the information. If so, you can leave a note with extra information to help the developers.
{{-}}

===3. Submit new bug===
[[File:Report issue buttons Gramps bugs.png|thumb|right|450px|'Report Issue' buttons.]]
Click on one of the {{man label|Report Issue}} buttons, and enter the required information, see below on how to select the project to which the bug belongs. Be verbose, the developers are bad at mind reading. We shall mercilessly close the bugs which have no meaningful information at all, such as #{{bug|7126}}. Do not forget to list the Gramps version you are using. You can check this in Gramps by clicking in the Gramps program the Help menu, option About.
{{-}}
==== How to proceed ====
[[File:Dropdown-Choose-Project-GrampsBugtracker.png|thumb|right|450px|Choose Project - selection list]]
The first step in submitting an issue on the tracker is to determine which project it belongs to on the issue tracker from the '''Select Project''' box, use the '''Choose Project''' drop down list to select the "project" for the bugs. "Projects" are a way to categorize issues. There are two types of projects in the issue tracker, '''Feature Requests''' and '''Gramps''':

*The '''Feature Requests''' project is a place for recording requests for new features.
**If the issue represents functionality that does not currently exist in Gramps, then the issue should be filed under the '''Feature Requests''' project.

*The '''Gramps''' project is a place for recording all issues with Gramps.
**If the issue represents a problem with functionality that has been released in a stable release or a problem with functionality that only exists in the master branch, then the issue should be filed under the Gramps project.
{{-}}

==== Enter Issue Details ====
[[File:Enter Issue Details page Gramps bugs.png|thumb|right|550px|Enter Issue Details - page]]
The {{man label|Enter Issue Details}} page is where you share with the developers what your issue or feature request is.

Try and complete all the relevant sections as well as you can and be prepared to answer follow up questions if your report needs clarification, it may help you to read the '''[[How to create a good bug report]]''' article.

===== Filling out the page =====

* Select Profile
** Gramps runs on multiple operating systems, so it's helpful to know which operating system and version you are reporting an issue against. This is where you provide that information. MantisBT allows you store multiple profiles in your Account so that you can pick the appropriate one, which is handy if you run Gramps on different system configurations.
* Product Version
**The projects with names that look like '''Gramps x.x.X''' are where issues are reported that apply specifically to a maintenance branch (see [[Brief_introduction_to_Git#Types_of_branches|Types of Branches]]). A separate project exists for each maintenance branch.
**For recording issues that ''only'' apply to the master branch in Git (see [[Brief_introduction_to_Git#Types_of_branches|Types of Branches]]), use next un-released version e.g.: 5.3.0 as shown on the [https://gramps-project.org/bugs/roadmap_page.php| MantisBT Roadmap].
{{-}}

==Useful MantisBT bug tracker Syntax codes==

The following are useful [http://www.mantisbt.org/ MantisBT bug tracker] syntax codes you can use:
* Using ''<code>#</code>'' before a bug number writes a link to the bug. eg: ''<code>#1</code>'' becomes {{bug|1}}
* Use ''<code>@</code>'' before a user name to mention a person (note: user names with embedded spaces are not supported)
* Using ''<code>~</code>'' before a comment number writes a link to the comment, same as : ''<code>{url}#c{comment number}</code>''. eg: ''<code>~3</code>'' becomes [https://gramps-project.org/bugs/view.php?id=1#c3]
* To link a GitHub Pull Request in the bug tracker, use p:gramps:nnnn: where nnnn is the PR number.

=== Limited HTML tags ===
* A [https://github.com/mantisbt/mantisbt/blob/55fb5721ea7d980557da484390db5c6003b63cd0/config_defaults_inc.php#L1979 limited set] of [https://www.w3schools.com/tags/ HTML tags] can be used in the text field:
**<code> </code> to define a paragraph.
**<code> <li></code> to defines a [https://www.w3schools.com/tags/tag_li.asp list item] used with:
***<code> <ul></code> unordered lists
***<code> <ol></code> ordered lists
**<code> </code> to insert a single line break.
**<code> <pre> </pre></code> to add preformatted text, that is displayed in a fixed-width font, and it preserves both spaces and line breaks.
**<code> </code> usually displays text in ''italics''.
**<code> </code> shows '''bold''' text
**<code> </code> Underline a misspelled word
**<code> </code> It renders as emphasized text.
**<code> </code> It defines important text.

==See also==
* [[How to create a good bug report]]
* [[Known issues]]
* [[Common problems]]
* Help the Gramps project [[Bug triage]]

MantisBT.org reports providing user-oriented (''not'' admin) documentation
* [https://www.mantisbt.org/bugs/view.php?id=5070 0005070]: I have written [MantisBT] quick-start documentation [.doc, .pdf, .swx] if you’re interested
* [https://www.mantisbt.org/bugs/view.php?id=8939 0008939]: Lifecycle model [Visio] for a report in MantisBT

[[Category:Developers/General]]
[[Category:Developers/Quality Assurance]]

Using the bug tracker

2023-12-29T16:40:42Z

Codefarmer: Gramps BugTracker has only one project for Gramps bugs so remove obsolete reference to version-based projects.

{{languages|Using the bug tracker}}
{{man tip|The bug/issue tracker for Gramps|is located at the following URL: <code>https://www.gramps-project.org/bugs</code>}}
This bug/issue tracker allows users and developers to log new issues and track them as they progress. Please take some time to read the issue tracker instructions below and read '''[[How to create a good bug report|how to create a good bug report]]'''. Also, have a look at '''[[Known_issues|known issues]]''' and '''[[Common_problems|common problems]]'''.

== Quick recommendations ==
When composing a problem (bug) report for Gramps:
* Be '''''precise'''''
* Be '''''clear''':'' explain how to reproduce the problem, step by step, so others can reproduce the bug, or understand the request.
* Include only '''''one problem per report'''''
* Include any relevant links and '''''examples'''''
{{man tip|Before you create a "Bug" report...|Composing a bug report can involve a lot of research and writing effort. Save yourself from unnecessary work.<ul><li>A solution or workaround might already exist in another bug report or in the forums.</li><li>If you connot find anything resembling your issue, ask about it in one of the forums. The community will help you solve or isolate the problem.</li></ul> }}

==Report a bug==
===1. Login===
To report a bug or raise a feature request, you must have a login account on the '''Gramps bug tracker''' ''([https://www.mantisbt.org/ powered by MantisBT])'':
* [https://bugs.gramps-project.org {{man button|Login}}] to your account at https://gramps-project.org/bugs/login_page.php , or;
* Select [https://gramps-project.org/bugs/signup_page.php {{man button|Signup for a new account}}] or visit the following link to create a new login account: https://gramps-project.org/bugs/signup_page.php .

Due to periodic SPAMbot activity, New Account requests might require human pre-approval. Be aware that this means that it might take up to 12 hours before a confirmation email is sent when creating a user account. Only after clicking on the link in the confirmation email can you submit bugs. Your email address will be handled confidentially.

{{-}}

===2. Search wiki and existing bugs===
[[File:Search box for existing bugs.png|thumb|right|450px|Search Box]]
Sometimes the behavior being observed might seem odd, yet as-designed. So the first step is to search the wiki to see what the documented behavior is. If you're still not sure, ask the [https://forum.gramps-project.org/ Gramps community on Discourse.]

If it still appears to be a bug, perhaps the bug you want to report has been reported before. To check this, click on [https://gramps-project.org/bugs/view_all_bug_page.php {{man button|View Issues}}]. The top of the page is reserved for filters, which you set. Normally the default filters are just fine. Under these filters, there is a {{man label|Search}} box. Enter the terms best describing the bug, and click {{man button|Apply Filter}} to search. If you have an error message, try pasting a part of the error, to see if it is has been reported already.

If the bug is already reported, read over the bug report, and see if you can add to the information. If so, you can leave a note with extra information to help the developers.
{{-}}

===3. Submit new bug===
[[File:Report issue buttons Gramps bugs.png|thumb|right|450px|'Report Issue' buttons.]]
Click on one of the {{man label|Report Issue}} buttons, and enter the required information, see below on how to select the project to which the bug belongs. Be verbose, the developers are bad at mind reading. We shall mercilessly close the bugs which have no meaningful information at all, such as #{{bug|7126}}. Do not forget to list the Gramps version you are using. You can check this in Gramps by clicking in the Gramps program the Help menu, option About.
{{-}}
==== How to proceed ====
[[File:Dropdown-Choose-Project-GrampsBugtracker.png|thumb|right|450px|Choose Project - selection list]]
The first step in submitting an issue on the tracker is to determine which project it belongs to on the issue tracker from the '''Select Project''' box, use the '''Choose Project''' drop down list to select the "project" for the bugs. "Projects" are a way to categorize issues. There are two types of projects in the issue tracker, '''Feature Requests''' and '''Gramps''':

*The '''Feature Requests''' project is a place for recording requests for new features.
**If the issue represents functionality that does not currently exist in Gramps, then the issue should be filed under the '''Feature Requests''' project.

*The '''Gramps''' project is a place for recording all issues with Gramps.
**If the issue represents a problem with functionality that has been released in a stable release or a problem with functionality that only exists in the master branch, then the issue should be filed under the Gramps project.
{{-}}

==== Enter Issue Details ====
[[File:Enter Issue Details page Gramps bugs.png|thumb|right|550px|Enter Issue Details - page]]
The {{man label|Enter Issue Details}} page is where you share with the developers what your issue or feature request is.

Try and complete all the relevant sections as well as you can and be prepared to answer follow up questions if your report needs clarification, it may help you to read the '''[[How to create a good bug report]]''' article.

===== Filling out the page =====

* Select Profile
** Gramps runs on multiple operating systems, so it's helpful to know which operating system and version you are reporting an issue against. This is where you provide that information. MantisBT allows you store multiple profiles in your Account so that you can pick the appropriate one, which is handy if you run Gramps on different system configurations.
* Product Version
**The projects with names that look like '''Gramps x.x.X''' are where issues are reported that apply specifically to a maintenance branch (see [[Brief_introduction_to_Git#Types_of_branches|Types of Branches]]). A separate project exists for each maintenance branch.
**The '''Gramps Master''' project should only be used by developers and testers of the latest code. It is a place for recording issues that only apply to the master branch in Git (see [[Brief_introduction_to_Git#Types_of_branches|Types of Branches]]). There is only one "Gramps Master" project because there is only one master branch in the Git repository.
{{-}}

==Useful MantisBT bug tracker Syntax codes==

The following are useful [http://www.mantisbt.org/ MantisBT bug tracker] syntax codes you can use:
* Using ''<code>#</code>'' before a bug number writes a link to the bug. eg: ''<code>#1</code>'' becomes {{bug|1}}
* Use ''<code>@</code>'' before a user name to mention a person (note: user names with embedded spaces are not supported)
* Using ''<code>~</code>'' before a comment number writes a link to the comment, same as : ''<code>{url}#c{comment number}</code>''. eg: ''<code>~3</code>'' becomes [https://gramps-project.org/bugs/view.php?id=1#c3]
* To link a GitHub Pull Request in the bug tracker, use p:gramps:nnnn: where nnnn is the PR number.

=== Limited HTML tags ===
* A [https://github.com/mantisbt/mantisbt/blob/55fb5721ea7d980557da484390db5c6003b63cd0/config_defaults_inc.php#L1979 limited set] of [https://www.w3schools.com/tags/ HTML tags] can be used in the text field:
**<code> </code> to define a paragraph.
**<code> <li></code> to defines a [https://www.w3schools.com/tags/tag_li.asp list item] used with:
***<code> <ul></code> unordered lists
***<code> <ol></code> ordered lists
**<code> </code> to insert a single line break.
**<code> <pre> </pre></code> to add preformatted text, that is displayed in a fixed-width font, and it preserves both spaces and line breaks.
**<code> </code> usually displays text in ''italics''.
**<code> </code> shows '''bold''' text
**<code> </code> Underline a misspelled word
**<code> </code> It renders as emphasized text.
**<code> </code> It defines important text.

==See also==
* [[How to create a good bug report]]
* [[Known issues]]
* [[Common problems]]
* Help the Gramps project [[Bug triage]]

MantisBT.org reports providing user-oriented (''not'' admin) documentation
* [https://www.mantisbt.org/bugs/view.php?id=5070 0005070]: I have written [MantisBT] quick-start documentation [.doc, .pdf, .swx] if you’re interested
* [https://www.mantisbt.org/bugs/view.php?id=8939 0008939]: Lifecycle model [Visio] for a report in MantisBT

[[Category:Developers/General]]
[[Category:Developers/Quality Assurance]]

Gramps for Windows with MSYS2

2023-08-24T01:43:37Z

Codefarmer: Run second update after core packages are updated

{{man warn|1=Warning|2=Do not open your existing databases with the master branch, it might destroy your data, and will make it impossible to use the data in the stable version {{stable_branch}}. To try it out, export your database to a gramps xml file, eg <code>test_master.gramps</code>, create a new family tree in the master branch, and import this xml file. Alternatively you can [[Gramps_for_Windows_with_MSYS2#Keep_your_GRAMPSHOME_separate|Keep your GRAMPSHOME separate]]}}

How to use MSYS2 to run latest Gramps development version from source in 64bit Windows.

In similar way you can build the 32bit version ([https://www.msys2.org/news/#2020-05-17-32-bit-msys2-no-longer-actively-supported 2020-05-17 - 32-bit MSYS2 no longer actively supported])
==Install MSYS2==

{{man note|Installation restrictions|MSYS2 can't be installed on [https://en.wikipedia.org/wiki/File_Allocation_Table FAT* formatted disk partitions]. Current MSYS2 can't be installed on Windows XP anymore.}}

From the MSYS2 home page https://www.msys2.org/ download the latest MSYS2 64bit installer( msys2-x86_64-YYYYMMDD.exe ) from [https://repo.msys2.org/distrib/x86_64/ https://repo.msys2.org/distrib/x86_64/] and run it.

Install it in short path like <code>C:\msys64</code>

At the end of install select to run mingw64 shell eg: use the '''MSYS2 MinGW 64-bit''' shortcut.

===Update MSYS2===
First keep running the following command(multiple times) until it has updated the list of packages and updated all core packages nothing else to do:

<pre>
pacman -Syuu
</pre>

If core packages are updated you must close the mingw64 shell (forcefully with close button, not just typing exit on it) and then restart the mingw64 shell from the shortcut. Following a core update, run the update command again to update non-core packages.

===Install Gramps dependencies===
Start mingw64 shell and use '''pacman''' package manager to download and install Gramps dependencies

<pre>
pacman -S mingw-w64-x86_64-python3-bsddb3 mingw-w64-x86_64-gexiv2 mingw-w64-x86_64-ghostscript mingw-w64-x86_64-python3-cairo mingw-w64-x86_64-python3-gobject mingw-w64-x86_64-python3-icu mingw-w64-x86_64-iso-codes mingw-w64-x86_64-hunspell mingw-w64-x86_64-hunspell-en mingw-w64-x86_64-enchant
</pre>

To handle the following warning '''No intltool or version < 0.25.0, build_intl is aborting''' during the build later, install:
pacman -S perl-XML-Parser
pacman -S intltool

You will also need the following to run the test:
<pre>
pacman -S mingw-w64-x86_64-python3-lxml
pacman -S mingw-w64-x86_64-python3-jsonschema
</pre>
Some additional (optional) items needed for certain addons.
<pre>
pacman -S mingw-w64-x86_64-gtkspell3
pacman -S mingw-w64-x86_64-geocode-glib
pacman -S mingw-w64-x86_64-python3-pillow
</pre>

Install Git and Gcc.
<pre>
pacman -S msys/git
pacman -S msys/gcc
</pre>

The Genealogical Symbols preferences tab needs Python Fontconfig version 0.5 so we need to build it.
From a suitable build directory (I use ~/build)
<pre>
git clone https://github.com/Vayn/python-fontconfig.git
cd python-fontconfig/
git checkout e1b1751f52167184e0c
python3 setup.py install
</pre>

Install Graphviz. To run the Graph View addon also install goocanvas.
(If you run into a problem try the alternate instructions to install [[Gramps_for_Windows_with_MSYS2#Issue|Graphviz]])
<pre>
pacman -S mingw-w64-x86_64-graphviz
pacman -S mingw-w64-x86_64-goocanvas
</pre>

Install osmgpsmap for the Geography Views with the following command:
<pre>
pacman -S mingw-w64-x86_64-osm-gps-map
</pre>

==Install Gramps==
===Prepare source===
Create directory to store Gramps source in and go to it
<pre>
mkdir ~/grampsdev
cd ~/grampsdev
</pre>

===Download source===
Download Gramps master branch from source repository
<pre>
git init
git remote add -t master -f origin https://github.com/gramps-project/gramps.git
git checkout master
</pre>
Check which Gramps version is used
<pre>
git describe
</pre>
it should return something like:
<blockquote>
v5.0.0-alpha1-1024-g0919763f1
</blockquote>
===Setup source===
Before using Gramps you must set-it up.
 You just use '''setup build''' command not '''install''' one
<pre>
python3 setup.py build
</pre>
==Run Gramps==
Start mingw64 shell and go to directory where Gramps source reside
<pre>
cd ~/grampsdev
</pre>
Use python3 to start Gramps
 To check gramps version use "v" flag
<pre>
python3 Gramps.py -v
</pre>
It should return something like:
<pre>
Gramps Settings:
----------------
python : 3.5.3
gramps : 5.0.0-alpha1-0919763f1
gtk++ : 3.22.9
pygobject : 3.22.0
pango : 1.40.3
cairo : 1.15.4
pycairo : 1.1.10
osmgpsmap : 1.0
GExiv2 : 0.10
ICU : 57.1
PyICU : 1.9.3
o.s. : win32

Non-python dependencies:
------------------------
Graphviz : Graphviz not in system PATH
Ghostscr. : 9.20
</pre>
Run Gramps
<pre>
python3 Gramps.py
</pre>
==Building and updating MSYS2/MinGW packages==
===Install build tools===
<pre>
pacman -S --needed --noconfirm base-devel mingw-w64-x86_64-toolchain
</pre>
[https://github.com/Alexpux/MINGW-packages MINGW-packages recipes] are on GitHub so you can use git to clone it. If instead you want to access recipe one by one you can download it with Subversion so install it first
<pre>
pacman -S subversion
</pre>
We need a place to download and build from source code so we will create folder called "build" inside our home folder
<pre>
mkdir ~/build
</pre>
To prevent pacman to upgrade packages we rebuilt for our needs we can assign them to group '''gramps_fixed''' and add them to IgnoreGroup list.
Open in text editor file ''etc/pacman.conf'' (C:\MSYS2\etc\pacman.conf) and add line ''IgnoreGroup = gramps_fixed'' to ''options'' section.
<pre>
[options]
IgnoreGroup = gramps_fixed
</pre>
===db===
GrampsAIO uses Oracle Berkeley DB version 6.0.30 but MSYS2 have it at version 6.0.19 and most probably never update it to a newer version.
 Gramps will ask permission to downgrade database version at import of any family tree created with GrampsAIO bundle. To prevent that build right version of DB.
 ''Hard way'' (it can take some time to finish)
<pre>
cd ~/build
svn checkout https://github.com/bpisoj/MINGW-packages/branches/gramps5/mingw-w64-db
cd mingw-w64-db
MINGW_INSTALLS=mingw64 makepkg-mingw -sLf
pacman -U mingw-w64-x86_64-db-6.0.30-1-any.pkg.tar.zst
</pre>
'''The easy way doesn't work anymore! This is because the recent versions of Python have changed and we have to rebuild.'''
 Start ''msys2 shell'' and type (easy way):
<pre>
cd ~/build
wget https://github.com/bpisoj/MINGW-packages/releases/download/v5.0/mingw-w64-x86_64-db-6.0.30-1-any.pkg.tar.xz
pacman -U mingw-w64-x86_64-db-6.0.30-1-any.pkg.tar.xz
</pre>

===bsddb3===
As db version is changed then we have to rebuild Python bindings for Oracle Berkeley DB
 From ''msys2 shell'' (easy way):
<pre>
cd ~/build
wget https://github.com/bpisoj/MINGW-packages/releases/download/v5.0/mingw-w64-x86_64-python3-bsddb3-6.1.0-3.1-any.pkg.tar.xz
pacman -U mingw-w64-x86_64-python3-bsddb3-6.1.0-3.1-any.pkg.tar.xz
</pre>
Or hard way:
<pre>
cd ~/build
svn checkout https://github.com/bpisoj/MINGW-packages/branches/gramps5/mingw-w64-python-bsddb3
cd mingw-w64-python-bsddb3
MINGW_INSTALLS=mingw64 makepkg-mingw -sLf
pacman -U mingw-w64-x86_64-python3-bsddb3-6.1.0-3.1-any.pkg.tar.xz
</pre>

===gtk3===
[https://www.gtk.org/ GTK+] since version 3.20 drag-and-drop code has been rearchitected to move the drag cancel animation and most input handling into GDK, thereby dropping most of the platform-dependent code out of GTK (MSYS2 version of GTK is currently 3.22.10). This change is not yet present in Windows port of code so we have to use older GTK version 3.18 where it still works.
 Latest in gtk-3.18 branch is gtk-3.18.9 (previous versions of this branch have working dnd but have other bugs) so we build that.
* Easy way:
<pre>
cd ~/build
wget https://github.com/bpisoj/MINGW-packages/releases/download/v5.0/mingw-w64-x86_64-gtk3-3.18.9-1-any.pkg.tar.xz
pacman -U mingw-w64-x86_64-gtk3-3.18.9-1-any.pkg.tar.xz
</pre>
* Hard Way:
<pre>
cd ~/build
svn checkout https://github.com/bpisoj/MINGW-packages/branches/gramps5/mingw-w64-gtk3
cd mingw-w64-gtk3
MINGW_INSTALLS=mingw64 makepkg-mingw -sLf
pacman -U mingw-w64-x86_64-gtk3-3.18.9-1-any.pkg.tar.xz
</pre>

===graphviz===

As of 2019.09.17 package mingw-w64-osm-gps-map is available so all you have to do is:

<pre>
pacman -S mingw-w64-x86_64-graphviz
</pre>

Previously Graphviz was in MSYS2 MINGW-packages git repository but was not build-able at that time (2017-03-26) so it is not available via pacman.
We build latest version from Graphviz git repository by manually patching code in process so we can't yet provide PKGBUILD
* Easy way
As we use simple archive not real packages we need to make care that dependencies are satisfied
<pre>
pacman -S --needed mingw-w64-x86_64-cairo mingw-w64-x86_64-devil mingw-w64-x86_64-expat mingw-w64-x86_64-freetype mingw-w64-x86_64-glib2 mingw-w64-x86_64-gtk2 mingw-w64-x86_64-gtkglext mingw-w64-x86_64-fontconfig mingw-w64-x86_64-freeglut mingw-w64-x86_64-libglade mingw-w64-x86_64-libgd mingw-w64-x86_64-libpng mingw-w64-x86_64-libsystre mingw-w64-x86_64-pango mingw-w64-x86_64-poppler mingw-w64-x86_64-zlib mingw-w64-x86_64-libtool
</pre>
Next we download prebuilt archive and extract it
<pre>
cd ~/build
wget https://github.com/bpisoj/MINGW-packages/releases/download/v5.0/win64_graphviz_20170323.1842.tar.xz
tar xfv win64_graphviz_20170323.1842.tar.xz -C /
</pre>
After successful install we first need to configure it (from mingw64 shell)
<pre>
dot -c
</pre>
If no error is displayed everything is working fine and Graphviz registered their plugins.
We can check version with
<pre>
dot -V

dot - graphviz version 2.41.20170323.1842 (20170323.1842)
</pre>
<pre>
winpty dot -v

dot - graphviz version 2.41.20170323.1842 (20170323.1842)
libdir = "C:\MSYS2\mingw64\bin"
Activated plugin library: libgvplugin_dot_layout-6.dll
Using layout: dot:dot_layout
Activated plugin library: libgvplugin_core-6.dll
Using render: dot:core
Using device: dot:dot:core
The plugin configuration file: C:\MSYS2\mingw64\bin\config6
was successfully loaded.
render : cairo dot fig gd map pic pov ps svg tk vml vrml xdot
layout : circo dot fdp neato nop nop1 nop2 osage patchwork sfdp twopi
textlayout : textlayout
device : bmp canon cmap cmapx cmapx_np dot eps fig gd gd2 gif gv ico imap
imap_np ismap jpe jpeg jpg pdf pic plain plain-ext png pov ps ps2
svg svgz tga tif tiff tk vml vmlz vrml wbmp xdot xdot1.2 xdot1.4
loadimage : (lib) bmp eps gd gd2 gif ico jpe jpeg jpg pdf png ps svg xbm
</pre>
* Hard way (TODO)
====pygraphviz====
Needed for NetworkChart report (Third-party addon)
* Easy way:
<pre>
cd ~/build
wget https://github.com/bpisoj/MINGW-packages/releases/download/v5.0/mingw-w64-x86_64-python3-pygraphviz-1.4rc1-1-any.pkg.tar.xz
pacman -U mingw-w64-x86_64-python3-pygraphviz-1.4rc1-1-any.pkg.tar.xz
</pre>
* Hard way
download https://gramps-project.org/wiki/images/2/2b/Pygraphviz-1.4rc1.zip [[:File:Pygraphviz-1.4rc1.zip|(source here)]]

Unzip it into <code>~/build/pygraphviz-1.4rc1/</code>
<pre>
cd ~/build/pygraphviz-1.4rc1
MINGW_INSTALLS=mingw64 makepkg-mingw -sLf
pacman -U mingw-w64-x86_64-python3-pygraphviz-1.4rc1-0.0-any.pkg.tar.xz
</pre>
For NetworkChart report to work install also networkx package
<pre>
pacman -S mingw-w64-x86_64-python3-networkx
</pre>
For NetworkChart report to work install also pydotplus
<pre>
pip3 install pydotplus
</pre>

===osmgpsmap===
As of 2019.02.08 package mingw-w64-osm-gps-map is available so all you have to do is
<pre>
pacman -S mingw-w64-x86_64-osm-gps-map
</pre>
 Start '''msys2 shell''' (always build package recipes from msys2 shell)
Hard way:
<pre>
cd ~/build
svn checkout https://github.com/Alexpux/MINGW-packages/trunk/mingw-w64-osm-gps-map
cd mingw-w64-osm-gps-map
MINGW_INSTALLS=mingw64 makepkg-mingw -sLf
pacman -U mingw-w64-x86_64-osm-gps-map-1.1.0-2-any.pkg.tar.xz
</pre>

==Issue==
===Graphviz===
* No Graphviz see: [https://github.com/Alexpux/MINGW-packages/issues/737 MSYS2:Package request: graphviz]
** Marked as WIP see: https://github.com/Alexpux/MINGW-packages/tree/master/mingw-w64-graphviz

====Alternate method using Windows version of Graphviz====
Tested alternate method to use Windows version of Graphviz[http://felsin9.de/nnis/ghc-vis/installing-windows/]
{{man warn|Warning it is not advised for users to mix various libraries like the following it is a direct way to dll hell.|This way Gramps will use graphviz libs instead of MSYS2 ones and they are older and in much way incompatible with rest of Gramps dependencies. until Graphviz becomes available from MSYS2 directly this is an alternate method.}}

Download the current GraphViz ZIP archive from https://www.graphviz.org/download/ and extract it to C:\graphviz, so that it directly contains the directories bin, lib, share and so on.

From the msys2 prompt type:
<pre>
echo 'export PATH=/c/graphviz/bin:$PATH' >> ~/.bashrc
source ~/.bashrc
</pre>
Then type:

python3 Gramps.py -v

and Graphviz will be listed.

<pre>Non-python dependencies:
------------------------
Graphviz : 2.38
</pre>

==Install Python pip==
To install a working version of pip use the following steps:

<pre>
mkdir ~/scripts
cd ~/scripts
curl -O 'https://bootstrap.pypa.io/get-pip.py'
./get-pip.py
</pre>

Test that it works:

pip3 --version

If that succeeds you can now remove the installation script if wanted:

rm get-pip.py

==Keep your [[Gramps_{{man version}}_Wiki_Manual_-_Command_Line#GRAMPSHOME|GRAMPSHOME]] separate==
To keep your test family trees separate from your personal family trees you may want to use your MSYS2 home directory which you can set from mingw64 shell either:

On each run like:

GRAMPSHOME=~ python3 Gramps.py

If you want it persistent:

echo 'export GRAMPSHOME=~' >> ~/.profile
source ~/.profile

==See also==
* [[Running a development version of Gramps]]
* [https://sourceforge.net/p/gramps/mailman/message/35346200/ Gramps on WSL (Win10/Ubuntu 14.04/VcXsvr)]

[[Category:GEPS|M]]
[[Category:Developers/General]]

Addon:NumberOfAncestorsQuickView

2023-07-08T16:20:47Z

Codefarmer: Link to Ancestor Fill Report addon wiki which was added recently

{{Third-party plugin}}

[[File:NumberOfAncestors-QuickView-example-51.png|thumb|right|450px|Number of Ancestors Quick View]]

The Quick View {{man label|Number of Ancestors}} is similar to the text report [[Gramps_{{man version}}_Wiki_Manual_-_Reports_-_part_6#Number_of_Ancestors_Report|Number of Ancestors]]. For each generation of the person's ancestors it tells you the number of ancestors found, the theoretical ancestor number and how many percent of the theoretical ancestors were found. The Quick View only counts individual ancestors, therefore duplicates caused by pedigree collapse are ignored in the calculations.

==Usage==
You can activate the Quick View by right-clicking on a person's name in the [[Gramps_{{man version}}_Wiki_Manual_-_Categories#People_Category|People Category View]]. Then select {{man menu|Quick View > Number Of Ancestors}}.

==Tips==
* Quick Views can also be used as Gramplets. ([[Gramps_{{man version}}_Wiki_Manual_-_Gramplets#Quick_View|more information]])
* The Third-party Addon [[Addon:Ancestor_Fill_Report|Ancestor Fill Report]] calculates pedigree collapse.

==See also==
* [https://en.wikipedia.org/wiki/Pedigree_collapse Pedigree collapse] - Wikipedia

[[Category:Plugins]]

Output formats

2023-06-03T02:22:07Z

Codefarmer: Fix typo; remove extraneous empty lines

Output Format: ''choose the output format:

==CSV==
* <code>.csv</code> '''Comma Separated Value''' structured text format extension
A comma-separated values (CSV) file is a delimited text file that uses a comma to separate values. A CSV file stores tabular data (numbers and text) in plain text.. Beginning with Gramps 5.2, the CSV import module allows selecting addiational delimiters beyond commas.
==D3==
* <code>.d3</code> '''Data-Driven Documents''' structured text format extension

[https://github.com/d3/d3/wiki D3 (Data-Driven Documents)] is a JavaScript library and framework for manipulating visualization documents based on data. D3 helps you bring data to life using HTML, SVG, and CSS. D3’s emphasis on web standards gives you the full capabilities of modern browsers without tying yourself to a proprietary framework, combining powerful visualization components and a data-driven approach to DOM manipulation.

A combination of HTML (HyperText Markup Language), SVG (Scalable Vector Graphics), and CSS (Cascading Style Sheet)
* [https://wikipedia.org/wiki/D3.js D3.js library] - Wikipedia

==GEDCOM==
* <code>.ged</code> '''GEnealogical Data COMmunication''' genealogical data file format extension
de facto standard file format for data interchange between genealogy programs via [[#GEDCOM_import|import]] and export.

'''Dialects'''
* <code>.ged2</code> '''GEDCOM Extensions''' genealogical data file format extension
* [http://www.pmoylan.org/pages/os2/wft.html Web Family Tree] GEDCOM

==GeneWeb==
* <code>.gw</code> '''GeneWeb''' genealogical data file format extension
[https://wikipedia.org/wiki/GeneWeb GeneWeb] is free open source genealogy software with an interface on a lightweight web server.

==GIF==
* <code>.gif</code> '''Graphics Interchange Format''' image file format extension
==Graphviz==
* <code>.gv</code> '''GraphViz''' image file format extension

[https://wikipedia.org/wiki/Graphviz Graphviz] (Graph Visualization) suite of open source software ([https://www.graphviz.org/download/ Download page])

'''[https://wikipedia.org/wiki/DOT_(graph_description_language) DOT]''' is the graph description language of the suite GraphViz. It has a human-readable syntax that describes network data, including subgraphs and elements appearances (i.e. color, width, label).

'''DOT graphs''' can also be imported into [https://wikipedia.org/wiki/NetworkX NetworkX], [https://wikipedia.org/wiki/Tulip_(software) Tulip] or [http://zvtm.sourceforge.net/zgrviewer.html ZGRViewer].

Files are typically indicated with the <code>.gv</code> or <code>.dot</code> filename extensions. The extension [https://wikipedia.org/w/index.php?title=.gv&redirect=no <code>.gv</code>] is preferred. (This avoids confusion with the extension [https://wikipedia.org/wiki/.dot <code>.dot</code>] also used for Microsoft Word ''template'' files prior to 2007.) However, the DOT language can be converted to several object-oriented graphics formats.
==GRDB==
* <code>.grdb</code> '''[[#GRAMPS_V2.x_database_import|GRAMPS V2.x database]]''' database file extension
==HTML==
* <code>.html</code> '''HyperText Markup Language''' structured text format extension
HyperText Markup Language (HTML)
==JPEG==
* <code>.jpg</code> '''Joint Photographic Experts Group''' image file format extension
==JSON==
* <code>.json</code> '''JavaScript Object Notation''' structured text file format extension
[https://www.json.org/ JavaScript Object Notation] is a lightweight data-interchange format.

==LaTeX==
* <code>.tex</code> '''Lamport's TeX (''Τ'' tau, ''ε'' epsilon and ''Χ'' chi)''' structured text format extension
A file format to provide high-quality typesetting information describing layout and font styling of textual data. Originally designed to flexibly support the complex layout (including multi-level superscript, subscript, matrixes & special glyphs) of scientific formulas.

LaTeX ''(also written LATEX)'' uses the TeX typesetting program for formatting its output, and LaTeX itself is written in the TeX macro language.

* File extension: <code>.tex</code>
* Helper (file viewer) application: see the [[Addon:GenealogyTree#Prerequisites|Prerequisites]] section for the GenealogyTree addon.

"Lamport's TeX" is named after developer [https://wikipedia.org/wiki/Leslie_Lamport Leslie Lamport]. With LaTeX, Lamport added a collection of macros to the original TEX program which was made by [https://wikipedia.org/wiki/Donald_Knuth Donald Knuth].

[https://www.latex-project.org/get/ How to get LaTeX]

==Open Document Spreadsheet==
* <code>.ods</code> '''OpenDocument Spreadsheet''' format extension

==Open Document Text==
* <code>.odt</code> '''OpenDocument Text''' structured text format extension
"Filename extensions
.odt & .fodt for word processing (text) documents.
Open Document Format for Office Applications (ODF), also known as OpenDocument, is a ZIP-compressed[[https://wikipedia.org/wiki/OpenDocument#cite_note-6 6]] XML-based file format for spreadsheets, charts, presentations and word processing documents. It was developed with the aim of providing an open, XML-based file format specification for office applications.[[https://wikipedia.org/wiki/OpenDocument#cite_note-7 7]]" - ''[https://wikipedia.org/wiki/OpenDocument Wikipedia]''

==PDF document==
* <code>.pdf</code> '''Portable Document Format''' text formatting and images file format extension
** Ghostscript ''PDF dialect''
** Graphviz ''PDF dialect''

"Portable Document Format (PDF) (redundantly: PDF format) is a file format developed by Adobe in the 1990s to present documents, including text formatting and images, in a manner independent of application software, hardware, and operating systems.[[https://wikipedia.org/wiki/PDF#cite_note-pdf-ref-1.7-3 2]][[https://wikipedia.org/wiki/PDF#cite_note-4 3]] Based on the PostScript language, each PDF file encapsulates a complete description of a fixed-layout flat document, including the text, fonts, vector graphics, raster images and other information needed to display it." - ''Wikipedia''

==Plain Text==
* <code>.txt</code> '''text''' format extension

==PNG==
* <code>.png</code> '''Portable Network Graphics''' image file format extension

==PostScript==
* <code>.ps</code> '''PostScript''' page description language file format extension
PostScript (PS) is a page description language in the electronic publishing and desktop publishing business. It is a dynamically typed, concatenative programming language and was created at Adobe Systems.
==Print...==

==Pro-Gen==
* <code>.def</code> '''data exchange format''' genealogical data file format extension
[https://www.pro-gen.nl/gbhome.htm PRO-GEN] is a commercial genealogical program that has been very popular in the Netherlands and North-West Germany. It is often used by people who started collecting and storing data as early as 1989. This was a DOS based program which has been patched to work with Win 10.

==Prolog==
* Prolog export - Prolog fact format in Unicode (utf-8)

==Raw export==
raw Python object

==RTF document==
* <code>.rtf</code> '''Rich Text Format''' structured text file format extension
"The Rich Text Format (often abbreviated RTF) is a proprietary[[https://wikipedia.org/wiki/Rich_Text_Format#cite_note-6 6]][[https://wikipedia.org/wiki/Rich_Text_Format#cite_note-e-gov-uk-7 7]][[https://wikipedia.org/wiki/Rich_Text_Format#cite_note-e-gov-uk-archived-8 8]] document file format with published specification developed by Microsoft Corporation from 1987 until 2008 for cross-platform document interchange with Microsoft products." - ''[https://wikipedia.org/wiki/Rich_Text_Format Wikipedia]''
==SQLite==
* <code>.sql</code> '''SQLite''' database file format extension
[https://www.sqlite.org/fileformat.html SQLite] is a database engine written in the C programming language.
==SVG==
* <code>.svg</code> '''Scalable Vector Graphics''' image file format extension
Scalable Vector Graphics (SVG) is an Extensible Markup Language (XML)-based vector image format for two-dimensional graphics with support for interactivity and animation.
==SVGZ==
* <code>.svgz</code> '''Compressed Structured Vector Graphs''' image file format extension

==vCalendar==
* <code>.vcf</code> '''vCalendar file''' calendar format extension
A calendar format that is a predecessor of iCalendar. It was created by the Internet Mail Consortium (IMC),

==vCard==
* <code>.vcf</code> '''Virtual Contact File''' structured text format extension

[https://wikipedia.org/wiki/VCard vCard] is a file format standard for electronic business cards.
==XML==
* <code>.xml</code> '''Extensible Markup Language''' structured text format extension

'''Dialects'''
* <code>.gramps</code> [[#Gramps_XML_and_XML_Package_import|'''Gramps Extensible Markup Language''']] Gramps native data exchange format in uncompressed text and [https://wikipedia.org/wiki/Gzip gzip] compressed
* <code>.gpkg</code> [[#Gramps_XML_and_XML_Package_import|'''Gramps XML package ''']] Gramps native data backup and archive format in [https://wikipedia.org/wiki/.tar.gz .tar.gz] compressed format with or without media.
* Isotammi XML export
=See also:=
[[Gramps_5.1_Wiki_Manual_-_Manage_Family_Trees#Exporting_data]]

[[Category:Documentation]]

Addon:D3 Ancestral and Descendant Charts

2023-05-29T20:29:28Z

Codefarmer: Add few more details to the library versions used by D3Charts

{{Third-party plugin}}

The '''D3 Ancestral and Descendant Charts''' addon consists of three(3) Web based reports:
* {{man label|[[Addon:D3_Ancestral_and_Descendant_Charts#Ancestral_Collapsible_Tree|Ancestral Collapsible Tree]]}}
* {{man label|[[Addon:D3_Ancestral_and_Descendant_Charts#Ancestral_Fan_Chart|Ancestral Fan Chart]]}}
* {{man label|[[Addon:D3_Ancestral_and_Descendant_Charts#Descendant_Indented_Tree|Descendant Indented Tree]]}}.

Each chart used the [[Output_formats#D3|D3.js library]] for its layout which are SVG based and provide some really nice inter-activeness and animation.

Note the filtering is based off the text based Ancestry and Descendant Reports.

All of the reports generate [https://en.wikipedia.org/wiki/JSON JSON] for ancestry/descendant's and could be easily customized for other usage.

== Usage ==

=== Ancestral Collapsible Tree ===
[[File:D3-AncestralCollapsibleTree-WebReport-Addon-example-50.png|thumb|right|450px|Ancestral Collapsible Tree - example output]]

This report is available under the menu {{Man menu|Reports > Web Pages > Ancestral Collapsible Tree...}}

A graphical representation of ancestry for a given individual.

By default up to Great Grandparents are displayed.

Clicking on an ancestor whom has further ancestors will either collapse or expand all ancestors for that person.

Specific customizable colors indicate whether there are further ancestors for a given person, and can be specified for maternal and paternal lines.

{{-}}

=== Ancestral Fan Chart ===

[[File:D3-AncestralFanChart-WebReport-Addon-example-50.png|thumb|right|450px|Ancestral Fan Chart - example output]]

This report is available under the menu {{Man menu|Reports > Web Pages > Ancestral Fan Chart...}}

The Ancestral Fan Chart report illustrates an individuals ancestry by means of a full circle fan chart.

The initial display shows the filtered individual at the center of the fan chart.

Selecting individuals on the fan chart will result in that individual becoming the center person and a new fan chart is drawn dynamically indicating that persons ancestry.

Continuous selection of the center of the fan chart will eventually return you to the original filter person, a page reload will also do this.

Custom colors can be provided for paternal and maternal sides of the filtered person.

{{-}}

=== Descendant Indented Tree ===

[[File:D3-DescendantIndentedTree-WebReport-Addon-example-50.png|thumb|right|450px|Descendant Indented Tree - example output]]

This report is available under the menu {{Man menu|Reports > Web Pages > Descendant Indented Tree...}}

The Descendant Indented Tree report is a graphical representation of the text based Descendant Report.

When clicking on a person if that person has further descendants, then the tree will dynamically expand or collapse depending on its current state.

As with the other reports some customizable colors can be specified at generation time. In this report they pertain to whether there are more descendants to view or not.

{{-}}

== Issues ==
* Charts appear without content - related to a security vulnerability update to Browsers. (i.e. local HTML files ought not to be authorized to open files from different sub-directories) This shouldn't be a problem once the files are uploaded to a server. It is just local mode that is affected. Workarounds for local mode available for:
** set [https://gramps.discourse.group/t/web-page-reports-have-no-content/411/8 Firefox] <tt>privacy.file_unique_origin flag</tt> to false in [http://kb.mozillazine.org/About:config about:config]
** Chrome launch flags: <pre>C:\Program Files (x86)\Google\Chrome\Application\chrome.exe" --allow-file-access-from-files --allow-file-access --allow-cross-origin-auth-prompt</pre>
* Help buttons URL's on report dialogs do not lead here.
* {{bug|9602}}: Descendant Indented Tree doesn't work with Chromium browser
* {{bug|11800}}: D3 Chart update of d3.js and jquery libraries to newer versions
** Uses D3.js version 3.4.5 (and not the [https://d3js.org/ current release])
** Uses [https://jquery.com/ jquery] v1.10.2 and 2.0.3 which are no longer supported or patched
** Uses [https://jqueryui.com/ jquery-ui] v1.10.4 which is also outdated
* Does not work with MS-IE 11?[https://github.com/d3/d3/issues/599#issuecomment-32245110]
If anyone is still facing the problem [with MS-IE 11] here is the solution:

Add this 2 lines to your html file.

<code><meta http-equiv="X-UA-Compatible" content="IE=edge" /></code>

If not IE doesn't understand the property CSSStyleDeclaration in your d3.js file.

==See Also==
* [[Web Solutions for Gramps]]

[[Category:Plugins]]
[[Category:Developers/General]]
[[Category:Reports]]

Addon:Python Shell Gramplet

2023-05-07T20:51:06Z

Codefarmer: Incorporate information Nick_H shared on Discourse forums

{{Third-party plugin}}

[[File:PythonGramplet-interactive-shell-example-50.png|thumb|right|450px|Python Shell Gramplet - Interactive shell example output]]

The {{man label|Python Shell}} Gramplet brings up an interactive Python Shell for interpreting python expressions.

==Options==
You can type most any (single line) Python expression.

In addition, the environment has been populated with some useful variables, including
*'''self''' - (this Python gramplet)
*'''Date''' - a date object constructor, that can be used for date arithmetic.
*'''db''' - Interact with the Database
*'''dbstate''' - Information about the Database
*'''gc''' - the Python "garbage collector" preloaded with the same flags as the Debug Tool.
*'''uistate''' - Interact with the GUI

When the {{man label|Python Shell}} Gramplet is detached you can select the {{man button|Help}} button to see this page.

== Usage ==

Output of print() commands issued in the Python Shell will be directed to the Gramps console window, so be sure to keep that window open.

Use the [[Using database API|database API]] to retrieve objects and use object library to find the information you require. If you want to write GUI code, then knowledge of Gtk3 is also required.

==Examples==

=== Dates ===

The '''Date''' entry is a date object constructor, and can be used for date arithmetic. For example, you might be interested in questions like:

What was the date 56 years before a given date:

> Date(2007, 12, 31) - 56
1951-12-31

How old was someone on Sept 3, 1955 who was born on June 7, 1922:

> Date(1955, 9, 3) - Date(1922, 5, 7)
33 years, 3 months

When did they turn 21 years old?

> Date(1922, 5, 7) + 21
1943-05-07

You can also add years, months, and days:

> Date(1980) + (0, 0, 25)
1980-01-26

You can convert one date into another calendar, which returns a new date object:

> Date(1703, 6, 1).to_calendar("hebrew")
5463-10-17 (Hebrew)

=== Displayers ===

Use utility code to make things easier. For example, you will probably want to use the name, date and place displayers rather than formatting the data yourself. To print the name of the default person, use the following code:

> from gramps.gen.display.name import displayer as nd
> person = self.dbstate.db.get_default_person()
> print(nd.display(person))

To find the type of a variable use:

> type(person)

=== Developers ===

Another use for this Gramplet is for debugging. This gramplet makes a nice interface to the running Gramps system. You can inspect, and alter the system by entering Python commands. As a simple example, you can:

> self.clear_text() # clear the text in this window
> self.set_wrap(False) # turn word wrap off
> self.set_wrap(True) # turn word wrap on

The Python Gramplet also has the Python "garbage collector" preloaded with the same flags as the Debug Tool. To use:

> gc.collect()
23
> gc.garbage[0]
<cell at 0x9f9089c: function object at 0x9f89dbc>
> gc.get_referents(self)
[...]
> gc.get_referrers(self)
[...]

{{stub}}
You can use the Python Shell to interact with people from your database and test Gramps functions:

{| border="1" style="border-collapse:collapse"
! Gramps 3.x
| <pre>
> person = db.get_person_from_gramps_id("I01284")
> from Utils import probably_alive
> probably_alive(person, db, Date(1776, 7, 4))
</pre>
|-
! Gramps 4.x
| <pre>
> person = db.get_person_from_gramps_id("I01284")
> from gen.utils.alive import probably_alive
> probably_alive(person, db, Date(1776, 7, 4))
</pre>
|-
! Gramps 5.x
| <pre>
> person = db.get_person_from_gramps_id("I01284")
> from gramps.gen.utils.alive import probably_alive
> probably_alive(person, db, Date(1776, 7, 4))
</pre>
|}

You can also interact with the GUI:

This following returns the Gtk Frame of the first Gramplet in the first column.

{| border="1" style="border-collapse:collapse"
! Gramps 3.x
| <pre>
> uistate.viewmanager.pages
[<DataViews.GrampletView.GrampletView instance at 0xa0bd0ac>,
<DataViews.PersonView.PersonView instance at 0xa8f542c>,
<DataViews.RelationView.RelationshipView instance at 0xa8f562c>,
<DataViews.FamilyList.FamilyListView instance at 0xa8f5f8c>,
<DataViews.PedigreeView.PedigreeView instance at 0xa8fc5cc>,
<DataViews.EventView.EventView instance at 0xa8fc88c>,
<DataViews.SourceView.SourceView instance at 0xa8fcdcc>,
<DataViews.PlaceView.PlaceView instance at 0xa9070ec>,
<DataViews.MediaView.MediaView instance at 0xa9074ac>,
<DataViews.RepositoryView.RepositoryView instance at 0xa9077ac>,
<DataViews.NoteView.NoteView instance at 0xa907d8c>,
<DataViews.GeoView.GeoView instance at 0xa90d0cc>]
> uistate.viewmanager.pages[0]
<DataViews.GrampletView.GrampletView instance at 0xa0bd0ac>
> uistate.viewmanager.pages[0].columns[0].get_children()[0].get_children()[0]
</pre>
|-
! Gramps 4.x
| <pre>

</pre>
|-
! Gramps 5.x
| <pre>
> uistate.viewmanager.pages[:]
[<dashboardview.DashboardView object at 0x0000000008c9f4e0>, <persontreeview.PersonTreeView object at 0x0000000000a05748>, <relview.RelationshipView object at 0x000000000b1b6358>]
</pre>
|}

This following returns a reference to a loaded Gramplet object on the Event view - useful when developing Gramplets. Note that the Events view must be navigated first, as main views are lazy loading in Gramps 4.

{| border="1" style="border-collapse:collapse"
! Gramps 4.x
| <pre>
> evtview = uistate.viewmanager.pages[uistate.viewmanager.page_lookup.get((5,0))]
> # list all TabGramplet objects loaded for Events view
> [child.get_title() for child in evtview.bottombar.get_children()]
['Gallery', 'Citations', 'Notes', 'Attributes', 'References', 'Event PlaceTitle Compare Gramplet']
> # get a reference to my custom Gramplet object
> eptcGramplet = evtview.bottombar.get_children()[5].pui

</pre>
|}

[[Category:Plugins]]
[[Category:Developers/General]]
[[Category:Gramplets]]

Using the bug tracker

2023-02-05T19:13:46Z

Codefarmer: Check the documentation and ask before filing a bug

{{languages|Using the bug tracker}}
{{man tip|The bug/issue tracker for Gramps|is located at the following URL: <code>https://www.gramps-project.org/bugs</code>}}
This bug/issue tracker allows users and developers to log new issues and track them as they progress. Please take some time to read the issue tracker instructions below and read '''[[How to create a good bug report|how to create a good bug report]]'''. Also, have a look at '''[[Known_issues|known issues]]''' and '''[[Common_problems|common problems]]'''.

== Quick recommendations ==
When composing a problem (bug) report for Gramps:
* Be '''''precise'''''
* Be '''''clear''':'' explain how to reproduce the problem, step by step, so others can reproduce the bug, or understand the request.
* Include only '''''one problem per report'''''
* Include any relevant links and '''''examples'''''
{{man tip|Before you create a "Bug" report...|Composing a bug report can involve a lot of research and writing effort. Save yourself from unnecessary work.<ul><li>A solution or workaround might already exist in another bug report or in the forums.</li><li>If you connot find anything resembling your issue, ask about it in one of the forums. The community will help you solve or isolate the problem.</li></ul> }}

==Report a bug==
===1. Login===
To report a bug or raise a feature request, you must have a login account on the '''Gramps bug tracker''' ''([https://www.mantisbt.org/ powered by MantisBT])'':
* [https://bugs.gramps-project.org {{man button|Login}}] to your account at https://gramps-project.org/bugs/login_page.php , or;
* Select [https://gramps-project.org/bugs/signup_page.php {{man button|Signup for a new account}}] or visit the following link to create a new login account: https://gramps-project.org/bugs/signup_page.php .

Due to periodic SPAMbot activity, New Account requests might require human pre-approval. Be aware that this means that it might take up to 12 hours before a confirmation email is sent when creating a user account. Only after clicking on the link in the confirmation email can you submit bugs. Your email address will be handled confidentially.

{{-}}

===2. Search wiki and existing bugs===
[[File:Search box for existing bugs.png|thumb|right|450px|Search Box]]
Sometimes the behavior being observed might seem odd, yet as-designed. So the first step is to search the wiki to see what the documented behavior is. If you're still not sure, ask the [https://gramps.discourse.group/ Gramps community on Discourse.]

If it still appears to be a bug, perhaps the bug you want to report has been reported before. To check this, click on [https://gramps-project.org/bugs/view_all_bug_page.php {{man button|View Issues}}]. The top of the page is reserved for filters, which you set. Normally the default filters are just fine. Under these filters, there is a {{man label|Search}} box. Enter the terms best describing the bug, and click {{man button|Apply Filter}} to search. If you have an error message, try pasting a part of the error, to see if it is has been reported already.

If the bug is already reported, read over the bug report, and see if you can add to the information. If so, you can leave a note with extra information to help the developers.
{{-}}

===3. Submit new bug===
[[File:Report issue buttons Gramps bugs.png|thumb|right|450px|'Report Issue' buttons.]]
Click on one of the {{man label|Report Issue}} buttons, and enter the required information, see below on how to select the project to which the bug belongs. Be verbose, the developers are bad at mind reading. We shall mercilessly close the bugs which have no meaningful information at all, such as #{{bug|7126}}. Do not forget to list the Gramps version you are using. You can check this in Gramps by clicking in the Gramps program the Help menu, option About.
{{-}}
==== How to proceed ====
[[File:Dropdown-Choose-Project-GrampsBugtracker.png|thumb|right|450px|Choose Project - selection list]]
The first step in submitting an issue on the tracker is to determine which project it belongs to on the issue tracker from the '''Select Project''' box, use the '''Choose Project''' drop down list to select the "project" for the bugs. "Projects" are a way to categorize issues. There are two types of projects in the issue tracker, '''Feature Requests''' and '''Gramps''':

*The '''Feature Requests''' project is a place for recording requests for new features.
**If the issue represents functionality that does not currently exist in Gramps, then the issue should be filed under the '''Feature Requests''' project.

*The '''Gramps''' project is a place for recording all issues with Gramps.
**If the issue represents a problem with functionality that has been released in a stable release of code, then the issue should be filed under the project that corresponds to the maintenance branch for that release. For example, a bug found in Gramps 5.1.0 should be filed under the '''Gramps 5.1.0''' project.

*If the issue represents a problem with functionality that only exists in the master branch, or the problem exists in the master branch, but not any stable releases, then the issue should be filed under the '''Gramps Master''' project.
{{-}}

==== Enter Issue Details ====
[[File:Enter Issue Details page Gramps bugs.png|thumb|right|550px|Enter Issue Details - page]]
The {{man label|Enter Issue Details}} page is where you share with the developers what your issue or feature request is.

Try and complete all the relevant sections as well as you can and be prepared to answer follow up questions if your report needs clarification, it may help you to read the '''[[How to create a good bug report]]''' article.

===== Filling out the page =====

* Select Profile
** Gramps runs on multiple operating systems, so it's helpful to know which operating system and version you are reporting an issue against. This is where you provide that information. Mantis allows you store multiple profiles in your Account so that you can pick the appropriate one, which is handy if you run Gramps on different system configurations.
* Product Version
**The projects with names that look like '''Gramps x.x.X''' are where issues are reported that apply specifically to a maintenance branch (see [[Brief_introduction_to_Git#Types_of_branches|Types of Branches]]). A separate project exists for each maintenance branch.
**The '''Gramps Master''' project should only be used by developers and testers of the latest code. It is a place for recording issues that only apply to the master branch in Git (see [[Brief_introduction_to_Git#Types_of_branches|Types of Branches]]). There is only one "Gramps Master" project because there is only one master branch in the Git repository.
{{-}}

==Useful Mantis bug tracker Syntax codes==

The following are useful [http://www.mantisbt.org/ Mantis bug tracker] syntax codes you can use:
* Using ''<code>#</code>'' before a bug number writes a link to the bug. eg: ''<code>#1</code>'' becomes {{bug|1}}
* Use ''<code>@</code>'' before a user name to mention a person (note: user names with embedded spaces are not supported)
* Using ''<code>~</code>'' before a comment number writes a link to the comment, same as : ''<code>{url}#c{comment number}</code>''. eg: ''<code>~3</code>'' becomes [https://gramps-project.org/bugs/view.php?id=1#c3]
* To link a GitHub Pull Request in the bug tracker, use p:gramps:nnnn: where nnnn is the PR number.

=== Limited HTML tags ===
* A [https://github.com/mantisbt/mantisbt/blob/55fb5721ea7d980557da484390db5c6003b63cd0/config_defaults_inc.php#L1979 limited set] of [https://www.w3schools.com/tags/ HTML tags] can be used in the text field:
**<code> </code> to define a paragraph.
**<code> <li></code> to defines a [https://www.w3schools.com/tags/tag_li.asp list item] used with:
***<code> <ul></code> unordered lists
***<code> <ol></code> ordered lists
**<code> </code> to insert a single line break.
**<code> <pre> </pre></code> to add preformatted text, that is displayed in a fixed-width font, and it preserves both spaces and line breaks.
**<code> </code> usually displays text in ''italics''.
**<code> </code> shows '''bold''' text
**<code> </code> Underline a misspelled word
**<code> </code> It renders as emphasized text.
**<code> </code> It defines important text.

==See also==
* [[How to create a good bug report]]
* [[Known issues]]
* [[Common problems]]
* Help the Gramps project [[Bug triage]].

[[Category:Developers/General]]
[[Category:Developers/Quality Assurance]]

Using the bug tracker

2023-02-05T17:54:45Z

Codefarmer: Ask bug reporters to fill in system information

{{languages|Using the bug tracker}}
{{man tip|The bug/issue tracker for Gramps|is located at the following URL: <code>https://www.gramps-project.org/bugs</code>}}
This bug/issue tracker allows users and developers to log new issues and track them as they progress. Please take some time to read the issue tracker instructions below and read '''[[How to create a good bug report|how to create a good bug report]]'''. Also, have a look at '''[[Known_issues|known issues]]''' and '''[[Common_problems|common problems]]'''.

== Quick recommendations ==
When composing a problem (bug) report for Gramps:
* Be '''''precise'''''
* Be '''''clear''':'' explain how to reproduce the problem, step by step, so others can reproduce the bug, or understand the request.
* Include only '''''one problem per report'''''
* Include any relevant links and '''''examples'''''
{{man tip|Before you create a "Bug" report...|Composing a bug report can involve a lot of research and writing effort. Save yourself from unnecessary work.<ul><li>A solution or workaround might already exist in another bug report or in the forums.</li><li>If you connot find anything resembling your issue, ask about it in one of the forums. The community will help you solve or isolate the problem.</li></ul> }}

==Report a bug==
===1. Login===
To report a bug or raise a feature request, you must have a login account on the '''Gramps bug tracker''' ''([https://www.mantisbt.org/ powered by MantisBT])'':
* [https://bugs.gramps-project.org {{man button|Login}}] to your account at https://gramps-project.org/bugs/login_page.php , or;
* Select [https://gramps-project.org/bugs/signup_page.php {{man button|Signup for a new account}}] or visit the following link to create a new login account: https://gramps-project.org/bugs/signup_page.php .

Due to periodic SPAMbot activity, New Account requests might require human pre-approval. Be aware that this means that it might take up to 12 hours before a confirmation email is sent when creating a user account. Only after clicking on the link in the confirmation email can you submit bugs. Your email address will be handled confidentially.

{{-}}

===2. Search existing bugs===
[[File:Search box for existing bugs.png|thumb|right|450px|Search Box]]
Perhaps the bug you want to report has been submitted before. To check this, click on [https://gramps-project.org/bugs/view_all_bug_page.php {{man button|View Issues}}]. The top of the page is reserved for filters, which you set. Normally the default filters are just fine. Under these filters, there is a {{man label|Search}} box. Enter the terms best describing the bug, and click {{man button|Apply Filter}} to search. If you have an error message, try pasting a part of the error, to see if it is has been reported already.

If the bug is already reported, read over the bug report, and see if you can add to the information. If so, you can leave a note with extra information to help the developers.
{{-}}

===3. Submit new bug===
[[File:Report issue buttons Gramps bugs.png|thumb|right|450px|'Report Issue' buttons.]]
Click on one of the {{man label|Report Issue}} buttons, and enter the required information, see below on how to select the project to which the bug belongs. Be verbose, the developers are bad at mind reading. We shall mercilessly close the bugs which have no meaningful information at all, such as #{{bug|7126}}. Do not forget to list the Gramps version you are using. You can check this in Gramps by clicking in the Gramps program the Help menu, option About.
{{-}}
==== How to proceed ====
[[File:Dropdown-Choose-Project-GrampsBugtracker.png|thumb|right|450px|Choose Project - selection list]]
The first step in submitting an issue on the tracker is to determine which project it belongs to on the issue tracker from the '''Select Project''' box, use the '''Choose Project''' drop down list to select the "project" for the bugs. "Projects" are a way to categorize issues. There are two types of projects in the issue tracker, '''Feature Requests''' and '''Gramps''':

*The '''Feature Requests''' project is a place for recording requests for new features.
**If the issue represents functionality that does not currently exist in Gramps, then the issue should be filed under the '''Feature Requests''' project.

*The '''Gramps''' project is a place for recording all issues with Gramps.
**If the issue represents a problem with functionality that has been released in a stable release of code, then the issue should be filed under the project that corresponds to the maintenance branch for that release. For example, a bug found in Gramps 5.1.0 should be filed under the '''Gramps 5.1.0''' project.

*If the issue represents a problem with functionality that only exists in the master branch, or the problem exists in the master branch, but not any stable releases, then the issue should be filed under the '''Gramps Master''' project.
{{-}}

==== Enter Issue Details ====
[[File:Enter Issue Details page Gramps bugs.png|thumb|right|550px|Enter Issue Details - page]]
The {{man label|Enter Issue Details}} page is where you share with the developers what your issue or feature request is.

Try and complete all the relevant sections as well as you can and be prepared to answer follow up questions if your report needs clarification, it may help you to read the '''[[How to create a good bug report]]''' article.

===== Filling out the page =====

* Select Profile
** Gramps runs on multiple operating systems, so it's helpful to know which operating system and version you are reporting an issue against. This is where you provide that information. Mantis allows you store multiple profiles in your Account so that you can pick the appropriate one, which is handy if you run Gramps on different system configurations.
* Product Version
**The projects with names that look like '''Gramps x.x.X''' are where issues are reported that apply specifically to a maintenance branch (see [[Brief_introduction_to_Git#Types_of_branches|Types of Branches]]). A separate project exists for each maintenance branch.
**The '''Gramps Master''' project should only be used by developers and testers of the latest code. It is a place for recording issues that only apply to the master branch in Git (see [[Brief_introduction_to_Git#Types_of_branches|Types of Branches]]). There is only one "Gramps Master" project because there is only one master branch in the Git repository.
{{-}}

==Useful Mantis bug tracker Syntax codes==

The following are useful [http://www.mantisbt.org/ Mantis bug tracker] syntax codes you can use:
* Using ''<code>#</code>'' before a bug number writes a link to the bug. eg: ''<code>#1</code>'' becomes {{bug|1}}
* Use ''<code>@</code>'' before a user name to mention a person (note: user names with embedded spaces are not supported)
* Using ''<code>~</code>'' before a comment number writes a link to the comment, same as : ''<code>{url}#c{comment number}</code>''. eg: ''<code>~3</code>'' becomes [https://gramps-project.org/bugs/view.php?id=1#c3]
* To link a GitHub Pull Request in the bug tracker, use p:gramps:nnnn: where nnnn is the PR number.

=== Limited HTML tags ===
* A [https://github.com/mantisbt/mantisbt/blob/55fb5721ea7d980557da484390db5c6003b63cd0/config_defaults_inc.php#L1979 limited set] of [https://www.w3schools.com/tags/ HTML tags] can be used in the text field:
**<code> </code> to define a paragraph.
**<code> <li></code> to defines a [https://www.w3schools.com/tags/tag_li.asp list item] used with:
***<code> <ul></code> unordered lists
***<code> <ol></code> ordered lists
**<code> </code> to insert a single line break.
**<code> <pre> </pre></code> to add preformatted text, that is displayed in a fixed-width font, and it preserves both spaces and line breaks.
**<code> </code> usually displays text in ''italics''.
**<code> </code> shows '''bold''' text
**<code> </code> Underline a misspelled word
**<code> </code> It renders as emphasized text.
**<code> </code> It defines important text.

==See also==
* [[How to create a good bug report]]
* [[Known issues]]
* [[Common problems]]
* Help the Gramps project [[Bug triage]].

[[Category:Developers/General]]
[[Category:Developers/Quality Assurance]]

Addons development

2022-11-06T22:50:42Z

Codefarmer: Clarify that maintenance branch should be used for contributions to public releases

{{man tip|Information on developing Gramps addons|If you are looking for addons to install, visit: [[Third-party Addons]]}}
{{man warn|Note that this article anticipates that most addons will be developed under Linux.|([[Getting started with Gramps development|Linux is the principal development platform.]]) While it is possible to do so under Windows or MacOS, some of the steps will differ and the documented processes have not been as thoroughly reviewed. So developer beware. See [[Portal:Developers]]}}
If you are developing a [[Third-party Addons|Third-party Addon]]; this page documents the API, methods, and best practices for Gramps 4.2 and later.

==What can addons extend?==
Addons for Gramps can extend the program in many different ways. You can add any of the following [https://github.com/gramps-project/gramps/blob/master/gramps/gen/plug/_pluginreg.py types] of addons:

#Report
#Quickreport
#Tool
#Importer
#Exporter
#Doc creator
#Plugin lib
#Map service
#Gramps View
#Relationships
#Gramplet
#Sidebar
#Database (Introduced Gramps 5.x and greater)
#Rule (Introduced Gramps 5.1.x and greater)

==Writing an addon==
Writing an addon is fairly straightforward if you have just a little bit of Python experience. And sharing your addon is the right thing to do. The general steps to writing an addon and sharing your own addons are:

# [[#Develop_your_addon|Develop your addon]]
# [[#Create_a_Gramps_Plugin_Registration_file|Create a Gramps Plugin Registration file (.gpr.py)]]
# [[#internationalization|Invite translation of your addon]] into multiple natural languages
# [[#Package_your_addon|Package your addon]]
# [[#List_and_document_your_addon_on_the_wiki|Document your addon]] and publish it to the addon list
# [[#List_your_addon_in_the_Gramps_Plugin_Manager|Register your addon with the Plugin Manager]]
# [[#Announce_it_on_the_Gramps_mailing_list|Announce it on the Gramps mailing list]] - Let users know it exist and how to use it.
# [[#Support_it_through_issue_tracker|Support it through the issue tracker]]
# [[#Maintain_the_code_as_Gramps_continues_to_evolve|Maintain the code]] as Gramps continues to evolve

We'll now expand upon each of these steps individually.

== Develop your addon ==

The [http://github.com/gramps-project/addons-source addons-source] repository holds the source code for the addons with branches holding the version for different gramps. If you are working on an addon for gramps for the current Gramps {{man version}} public release, be sure to use the maintenance/gramps51 git branch, as the default is master branch for the developmental pre-release. (Currently gramps 5.2, which is not the typical target for addons.)

Example commands are shown below referring to the public release rather than the master branch.

The developers are currently merging changes to the most recent maintenance branch into master as necessary, so you don't have to do anything for that unless you are in a hurry.

The [http://github.com/gramps-project/addons-source addons-source] git repository has the following structure, with the code for each addon in its own folder:

* /addons-source
** /''IndividualNameOfAddon1''
** /''IndividualNameOfAddon2''
** ...

The [http://github.com/gramps-project/addons addons] git repository holds built versions of the addons for each release of Gramps, and has the following structure:

* /addons
** /gramps42
*** /download
*** /listings
** /gramps50
*** /download
*** /listings
** /gramps51
*** /download
*** /listings

=== Get a local copy of Gramps and its addons ===

These steps show how to download the addon sources.

# Get an https://github.com/join account if you don't already have one.
# Request GIT write access for the https://github.com/gramps-project/addons-source project by emailing the [[Contact#Mailing_lists|gramps-devel mailing list]]
See also [[Brief_introduction_to_Git|git introduction]] for instructions on installing git and getting basic settings configured. Also [https://help.github.com/articles/generating-an-ssh-key/ Connecting to GitHub with SSH] will help with setting up credentials for GitHub.
To fully build and advertise a new addon will require local copies of the three repositories, the 'addons-source', 'addons' and the main Gramps source 'gramps'.

This wiki assumes that all three git repositories local locations are put into the same base directory and named with the repository names in order for the make.py script commands to work as shown. From the base directory, run the following commands to create a copy of each repository. If you want to use SSH;

git clone git@github.com:gramps-project/addons-source.git addons-source
git clone git@github.com:gramps-project/addons.git addons
git clone git@github.com:gramps-project/gramps.git gramps

or if you want to use a web url:

git clone https://github.com/gramps-project/addons-source.git addons-source
git clone https://github.com/gramps-project/addons.git addons
git clone https://github.com/gramps-project/gramps.git gramps

To switch to a local copy of the gramps51 maintenance branch:

cd addons-source
git checkout -b gramps51 origin/maintenance/gramps51

or to work in the master branch:

cd addons-source
git checkout -b gramps52 origin/master

=== Other prerequisites ===
{{man warn|These instructions, the make.py script etc.|are designed to operate in a Linux environment. {{man menu|They won't work on Windows without modifications.}}}}
* Gramps uses Python version 3.2 or higher. You must have at least that version installed. If you have installed Gramps 4.2 or higher on your Linux system already, then a sufficient version of Python will be present. If you have more than one version of Python installed, then you must use the correct version for these scripts. On some systems, both Python 2.x and 3.x are installed. It is possible that the normal invocation of <code>python</code> starts up Python 2.x, and that to start up Python 3.x requires invoking with <code>python3</code> or <code>python3.4</code> etc. You can test the version by <code>python –version</code> or <code>python3 –version</code>. If this is so, replace any usage of 'python' in the examples below with the appropriate invocation.
* The make.py used in construction of the addons requires that the LANGUAGE environment variable be set to 'en_US.UTF-8'.
* The make.py used in construction of the addons requires that the GRAMPSPATH environment variable be set to your path to the Gramps source tree.
* intltool must be installed;
: <code>sudo apt-get install intltool</code>

For example if your home directory is '/home/name' and you use the suggested path names, use
: <code>GRAMPSPATH=/home/name/gramps LANGUAGE='en_US.UTF-8' python3 make.py ...</code>
to replace the <code>./make.py</code> in the examples below.

=== Create your addon subdirectory ===
* Make a new project directory in addons-source:
: <code>mkdir NewProjectName</code>

===Follow the development API for your tool===
Create your NewProjectName.py and NewProjectName.gpr.py files.

Follow the development API for your tool, [[Report-writing_tutorial|report]], view, or [[Gramplets]]. Place all of your associated .py, .glade, etc. files in this directory. For general information on Gramps development see [[Portal:Developers]] and [[Writing a plugin|Writing a Plugin]] specifically.

=== Test your addon as you develop ===

{{man warn|{{bug|10436}} Symlinks to folders in gramps plugin dir are not scanned}}

To test your addon as you develop it is suggested that you copy your NewProjectName plugin into your Gramps user plugin directory from your addon development directory, prior to testing. Or just edit in the Gramps user plugin directory until it is ready to publish, then copy back to your addon development directory.

Your installed Gramps will search this folder (and subdirectories) for .gpr.py files, and add them to the plugin list.

If you have code that you want to share between addons, you don't need to do anything special. Gramps adds each directory in which a .gpr.py is found onto the PYTHONPATH which is searched when you perform an import. Thus "import NewProjectName" will work from another addon. You should always make sure you name your addons with a name appropriate for Python imports.

=== Commit your changes ===
To commit your changes so that others can see your addon source.

* Remove the files using the ''clean'' command that should not be added to GitHub (eg files(template.pot/ locale etc)):
: <code>./make.py gramps51 clean NewProjectName</code>
* Add the project to the repository:
: <code>git add NewProjectName</code>
* Commit it with an appropriate message
: <code>git commit -m "A message describing what this addon is"</code>

Before committing additional edits to your addon, you should:

* to make sure that outside changes do not affect your commit
: <code>git pull --rebase</code>
* only the files you changed should be in this list
: <code>git status</code>
* Commit it with an appropriate message
: <code>git commit -m "A message describing the changes"</code>

If you have been given 'push' rights to GitHub 'gramps-project/addons-source', and when you are sure you are done and want to publish to the repository:

* to make sure that outside changes do not affect your commit
: <code>git pull --rebase</code>
: <code>git push origin gramps51</code>

Also you may want to [[Addons_development#Package_your_addon |Package your addon]] so it can be downloaded via the plugin manager.

=== Config ===

Some addons may want to have persistent data (data settings that remain between sessions). You can handle this yourself, or you can use Gramps' built-in configure system.

At the top of the source file of your addon, you would do this:

from config import config as configman
config = configman.register_manager("grampletname")
# register the values to save:
config.register("section.option-name1", value1)
config.register("section.option-name2", value2)
...
# load an existing file, if one:
config.load()
# save it, it case it didn't exist:
config.save()

This will create the file "grampletname.ini" and put in the same directory as the addon. If the config file already exists, it remains intact.

In the addon, you can then:

x = config.get("section.option-name1")
config.set("section.option-name1", 3)

and when this code is exiting, you might want to save the config. In a Gramplet that would be:

def on_save(self):
config.save()

If your code is a system-level file, then you might want to save the config in the Gramps system folder:

config = configman.register_manager("system", use_config_path=True)

This, however, would be rare; most .ini files would go into the plugins directory.

In other code that might use this config file, you would do this:

from config import config as configman
config = configman.get_manager("grampletname")
x = config.get("section.option-name1")

=== Localization ===

For general help on translations in Gramps, see [[Coding for translation]]. However, that will only use translations that come with Gramps, or allows you to contribute translations to the Gramps core. To have your own managed translations that will be packaged with your addon, read the rest of this page.
Note that these instructions will only work for Python strings, if you have a glade file, it will not get translated.

For any addon which you have translations into other languages, you will need to add a way to retrieve the translation. You need to add this to the top of your NewProjectName.py file:

from gramps.gen.const import GRAMPS_LOCALE as glocale
_ = glocale.get_addon_translator(__file__).gettext

Then you can use the standard "_()" function to translate phrases in your addon.

You can use one of a few different types of translation functions:

# gettext
# lgettext
# ngettext
# lngettext
# sgettext

These have become obsolete in Gramps 4; gettext, ngettext, and sgettext always return translated strings in unicode for consistent portability between Python 2 and Python3.

See the [http://docs.python.org/3/library/gettext.html#the-gnutranslations-class python documentation] for documentation of gettext and ngettext. The "l" versions return the string encoded according to the [http://docs.python.org/3/library/locale.html#locale.setlocale currently set locale]; the "u" versions return unicode strings in Python2 and are not available in Python 3.

'''sgettext''' is a Gramps extension that filters out clarifying comments for translators, such as
_("Remaining names | rest")
Where "rest" is the English string that we want to present and "Remaining names" is a hint for translators.

==== Commands to compile translations ====

To build and compile translations for all projects to their download/Addon.addon.tgz files:

: <code>python3 make.py gramps51 build all</code>

To compile translations for all projects :

: <code>python3 make.py gramps51 compile all</code>

== Create a Gramps Plugin Registration file ==

First, create the NewProjectName.gpr.py file. The registration takes this general form:

<pre>
register(PTYPE,
gramps_target_version = "5.1",
version = "1.0.0",
ATTR = value,
)
</pre>

[https://github.com/gramps-project/gramps/blob/master/gramps/gen/plug/_pluginreg.py#L76 PTYPE] is TOOL, GRAMPLET, REPORT, QUICKVIEW, IMPORT, EXPORT, DOCGEN, GENERAL, MAPSERVICE, VIEW, or RELCALC.

ATTR depends on the PTYPE. But you must have '''gramps_target_version''' and '''version'''. '''gramps_target_version''' should be a string of the form "X.Y" version number matching Gramps X major, Y minor integer. '''version''' is a string of the form "X.Y.Z" representing the version of your addon. X, Y, and Z should all be integers.

Here is a sample Tool GPR file:

<pre>
register(TOOL,
id = 'AttachSource',
name = _("Attach Source"),
description = _("Attaches a shared source to multiple objects."),
version = '1.0.0',
gramps_target_version = '5.1',
status = STABLE,
fname = 'AttachSourceTool.py',
authors = ["Douglas S. Blank"],
authors_email = ["doug.blank@gmail.com"],
category = TOOL_DBPROC,
toolclass = 'AttachSourceWindow',
optionclass = 'AttachSourceOptions',
tool_modes = [TOOL_MODE_GUI]
)
</pre>

You can see examples of the kinds of addons [https://github.com/gramps-project/gramps/plugins here] (for example, see [https://github.com/gramps-project/gramps/plugins/drawreport/drawplugins.gpr.py gramps/plugins/drawreport/drawplugins.gpr.py]) and see the full documentation [https://github.com/gramps-project/gramps/gen/plug/_pluginreg.py here] in the comments and docstrings.

Note that this .gpr.py will automatically use translations if you have them (see below). That is, the function "_" is predefined to use your locale translations; you only need to mark the text with _("TEXT") and include a translation of "TEXT" in your translation file. For example, in the above example, _("Attach Source") is marked for translation. If you have developed and packaged your addon with translation support, then that phrase will be converted into the user's language.

=== Report plugins ===
The possible report categories are (gen/plug/_pluginreg.py):
<pre>
#possible report categories
CATEGORY_TEXT = 0
CATEGORY_DRAW = 1
CATEGORY_CODE = 2
CATEGORY_WEB = 3
CATEGORY_BOOK = 4
CATEGORY_GRAPHVIZ = 5
REPORT_CAT = [ CATEGORY_TEXT, CATEGORY_DRAW, CATEGORY_CODE,
CATEGORY_WEB, CATEGORY_BOOK, CATEGORY_GRAPHVIZ]
</pre>

Each report category has a set of standards and interface. The categories CATEGORY_TEXT and CATEGORY_DRAW use the Document interface of Gramps. See also [[Report API]] for a draft view on this.

The application programming interface or API for reports is treated at [[Report-writing_tutorial]]. For general information on Gramps development see [[Portal:Developers]] and [[Writing a plugin|Writing a Plugin]] specifically.

=== General plugins ===

The plugin framework also allows you to create generic plugins for use. This includes the ability to create libraries of functions, and plugins of your own design.

==== Example: A library of functions ====

In this example, a file name library.py will be imported at time of registration (when Gramps starts):

<pre>
# file: library.gpr.py

register(GENERAL,
id = 'My Library',
name = _("My Library"),
description = _("Provides a library for doing something."),
version = '1.0',
gramps_target_version = '5.1',
status = STABLE,
fname = 'library.py',
load_on_reg = True,
)
</pre>

The code in the file library.py will be imported when Gramps begins. You can access the loaded module in other code by issuing an "import library" as Python keeps track of files already imported. However, the amount of useful code that you can run when the program is imported is limited. You might like to have the code do something that requires a dbstate or uistate object, and neither of these is available when just importing a file.

If "load_on_reg" was not True, then this code would be unavailable until manually loaded. There is no automatic mechanism in Gramps to load GENERAL plugins automatically.

In addition to importing a file at startup, one can also run a single function inside a GENERAL plugin, and it will be passed the dbstate, the uistate, and the plugin data. The function must be called "load_on_reg", and take those three parameters, like this:

<pre>
# file: library.py

def load_on_reg(dbstate, uistate, plugin):
"""
Runs when plugin is registered.
"""
print("Hello World!")
</pre>

Here, you could connect signals to the dbstate, open windows, etc.

Another example of what one can do with the plugin interface is to create a general purpose plugin framework for use by other plugins. Here is the basis for a plugin system that:

* allows plugins to list data files
* allows the plugin to process all of the data files

First, the gpr.py file:

<pre>

register(GENERAL,
id = "ID",
category = "CATEGORY",
load_on_reg = True,
process = "FUNCTION_NAME",
)
</pre>

This example uses three new features:

# GENERAL plugins can have a category
# GENERAL plugins can have a load_on_reg function that returns data
# GENERAL plugins can have a function (called "process") which will process the data

If you (or someone else) create additional general plugins of this category, and they follow your load_on_reg data format API, then they could be used just like your original data. For example, here is an additional general plugin in the 'WEBSTUFF' category:

<pre>
# anew.gpr.py

register(GENERAL,
id = 'a new plugin',
category = "WEBSTUFF",
version = '1.0',
gramps_target_version = '5.1',
data = ["a", "b", "c"],
)
</pre>

This doesn't have load_on_reg = True, nor does it have a fname or process, but it does set the data directly in the .gpr.py file. Then we have the following results:

<pre>
>>> from gui.pluginmanager import GuiPluginManager
>>> PLUGMAN = GuiPluginManager.get_instance()
>>> PLUGMAN.get_plugin_data('WEBSTUFF')
["a", "b", "c", "Stylesheet.css", "Another.css"]
>>> PLUGMAN.process_plugin_data('WEBSTUFF')
["A", "B", "C", "STYLESHEET.CSS", "ANOTHER.CSS"]
</pre>

=== Registered GENERAL Categories ===

The following are the published secondary plugins API's (type GENERAL, with the following categories):

==== WEBSTUFF ====

A sample gpr.py file:

<pre>
# stylesheet.gpr.py

register(GENERAL,
id = 'system stylesheets',
category = "WEBSTUFF",
name = _("CSS Stylesheets"),
description = _("Provides a collection of stylesheets for the web"),
version = '1.0',
gramps_target_version = '5.1',
fname = "stylesheet.py",
load_on_reg = True,
process = "process_list",
)
</pre>

Here is the associated program:

<pre>
# file: stylesheet.py

def load_on_reg(dbstate, uistate, plugin):
"""
Runs when plugin is registered.
"""
return ["Stylesheet.css", "Another.css"]

def process_list(files):
return [file.upper() for file in files]
</pre>

==== Filters ====

For example:

<pre>
register(GENERAL,
category="Filters",
...
load_on_reg = True
)
</pre>

<pre>
def load_on_reg(dbstate, uistate, plugin):
# returns a function that takes a namespace, 'Person', 'Family', etc.

def filters(namespace):
print("Ok...", plugin.category, namespace, uistate)
# return a Filter object here
return filters
</pre>



== List the Prerequistes your addon depends on ==

''In your gpr file, you can have a line like:

<code>depends_on = ["libwebconnect"]</code>

which is a list of id's from other gpr files. This example will ensure that [[Addon:Web_Connect_Pack#Prerequisites|libwebconnect]] is loaded before your addon. If it can't be found, or you have a cycle, then your addons won't be loaded.

example code used in the Addon:Web_Connect_Pack that references libwebconnect Prerequistes [https://github.com/gramps-project/addons-source/blob/1304b65a7d758bfe17339c26260473ac3e9c4061/RUWebConnectPack/RUWebPack.gpr.py#L17 RUWebPack.gpr.py#L17 ]

This means that common Prerequistes can be shared between addons and that code sits in its own gpr/addon file.



== Get translators to translate your addon into multiple languages ==

If you [[#Localization|designed for localization]], the addon will begin supporting a single language. Make your addon inviting for volunteers to translate it into their native language.
* Initialize and update the <code>template.pot</code> for your addon:
: <code>cd ~/addons-source</code>
: <code>./make.py gramps51 init NewProjectName</code>
* You should edit the header of <code>template.pot</code> with your information, so it gets copied to individual language files.
* Initialize a language for your addon (say French, fr):
: <code>./make.py gramps51 init NewProjectName fr</code>
* Update it from gramps and other addons:
: <code>./make.py gramps51 update NewProjectName fr</code>
* Edit the translations file manually:
: <code>/NewProjectName/po/fr-local.po</code>
* Compile the language:
: <code>./make.py gramps51 compile NewProjectName</code>
* Add or update your local language file, and commit changes:
: <code>git add NewProjectName/po/fr-local.po</code>
: <code>git commit NewProjectName/po/fr-local.po -m "Added fr po file"</code>
* If you have been given 'push' rights to GitHub 'gramps-project/addons-source', then;
: <code>git push origin gramps51</code>

== Package your addon ==

To create a downloadable package:

: <code>./make.py gramps51 build NewProjectName</code> or
: <code>./make.py gramps52 build NewProjectName</code> for the master branch.

This will automatically include the following files in your build:

* *.py
* *.glade
* *.xml
* *.txt
* locale/*/LC_MESSAGES/*.mo

Starting with Gramp 5.0, if you have additional files beyond those listed above, you should create a MANIFEST file in the root of your addon folder listing the files (or pattern) one per line, like this sample MANIFEST file:

<pre>
README.md
extra_dir/*
help_files/docs/help.html
</pre>

{{man note|Note:|Running the command <code>make.py xxx build</code> will increment the third number in your dotted version number of all addons in the <code>*.gpr.py</code> file. Consider this number to be a "build number".}}

This will leave your 'addons-source' with untracked changes according to git. You should delete the 'NewProjectName/locale' directory. The updated 'NewProjectName/NewProjectName.gpr.py ' is ready to add and commit the next time you make other changes.
: <code>rm –rf –v 'NewProjectName/locale'</code>

Then add the package to GitHub:

<pre> cd '~/addons'
git add gramps51/download/NewProjectName.addon.tgz
git commit -m "Added new plugin: NewProjectName"</pre>
or (for the master branch);
<pre> cd '~/addons'
git add gramps52/download/NewProjectName.addon.tgz
git commit -m " Added new plugin: NewProjectName"</pre>

== List your addon in the Gramps Plugin Manager==

{{man warn|Gramps needs to have been built|Make sure you have already built gramps51 or master. Change to the appropriate git branch in your gramps directory, and run <code>python3 setup.py build</code> See [[Linux:Build_from_source]]}}

To create a listing:

: <code>cd '~/gramps-addons'</code> or wherever you have built your addon
: <code>GRAMPSPATH=path/to/your/gramps/install ./make.py gramps51 listing NewProjectName</code>
or (for the master branch);
: <code>cd '~/gramps-addons'</code> or wherever you have built your addon
: <code>GRAMPSPATH=path/to/your/gramps/install ./make.py gramps52 listing NewProjectName</code>

That will create a series of files in the <tt>../listings/</tt> directory.

Then add the updated listing to GitHub:

<pre> cd '~/addons'
git add gramps51/listings/*
git commit -m "Added new plugin to listings: NewProjectName"</pre>
or (for the master branch);
<pre> cd '~/addons'
git add gramps52/listings/*
git commit -m " Added new plugin to listings: NewProjectName"</pre>

== List and document your addon on the wiki==

===List your addon===
Add a short description of your addon to the Addons list by editing the current release listing eg: [[5.1_Addons]] or if the addon is meant for a future release [[5.2_Addons]] when available.

==== Example addon template ====
Examine the listing for other addons and refer to the [[Addon list legend]] for details of on the meaning of each columns.
<pre>
|- 
|
|
|
|
|
|
|
|
|-
</pre>

===Document your addon===
Document the addon in the wiki using the page name format of {{man menu|Addon:NewProjectName}} examine the other addon support pages for the general format to use.
{{man tip|Hint on creating a new wiki page.|To create a new wiki page use the search box to search for the name of your page that doesn't exist then on the search results page you will be provided with a link to create the new page, by selecting and you can add your content}}

====Example addon article====
Consider including the following information:

<pre>

{{Third-party plugin}}


== Usage ==

=== Configure Options ===

==Features==

== Prerequisites ==

== Issues ==


[[Category:Addons]]
[[Category:Plugins]]
[[Category:Developers/General]]
</pre>

== Announce the addon ==
Join the [[Contact#Mailing_lists|Gramps Mailing lists]] or [[Contact#Forum|Forum]] and announce it to the users with general information on why you created and how to use it.

== Support it through issue tracker ==

Become a user on the [https://gramps-project.org/bugs/view_all_bug_page.php Gramps MantisBT (Mantis BugTracker)].
and please check it regularly. There is no automated notification of issues (and possible feature requests) related to your addon when reported by users.

Users tend to not understand coding and they make assumptions. So be kind and guiding if a report is ambiguous or inaccurate. A negative remark from an addon developer or anyone can be very discouraging.

== Maintain the code as Gramps continues to evolve ==

{{man tip|When submitting an update the patch part of the version number MAJOR.MINOR.PATCH is updated during the addon build process e.g. 1.1.3 to 1.1.4|You can find this step in [https://github.com/gramps-project/addons-source/blob/master/make.py#L125 addons-source/make.py].[https://gramps.discourse.group/t/should-addons-pr-include-version-number-update/2591]}}

Remember that Gramps addons exist for many reasons and there are many Gramps developers that do support addons in various ways (translations, triage, keeping in sync with master, download infrastructure, etc).

Some reasons why the addons exist; they provide:
* A quick way for anyone to share their work; the Gramps-project has never denied adding a addon.
* A method to continuously update and develop a stand-alone component, often before being officially accepted.
* A place for controversial plugins that will never be accepted into core, but are loved by many users (eg, Data Entry Gramplet).
* A place for experimental components to live.

== Example code adding common enhancements ==
* Copy all the Gramplet's output to a system clipboard via context pop-up menu : Enhancement request {{bug|11573}}, [https://github.com/gramps-project/gramps/pull/1014/commits/72012e13b4ca15caca4b7f36fdb9702c1fd470fd example pull]
* add a custom [[Gramps_Glossary#viewmode|View Mode]] toolbar icon via the <code>.gpr.py</code> : [https://github.com/gramps-project/gramps/pull/1017 Pull 1017 Discussion], [https://github.com/gramps-project/gramps/pull/1017/commits/76e41d546d6ec519dd78fbe07f663135b5c79351 example Pull]

= Resources =
* [[Brief_introduction_to_Git|Git introduction]]
* [[Getting started with Gramps development]]
* [[Portal:Developers]]
* [https://gramps-project.org/docs/gen/gen_plug.html?highlight=include_in_listing#module-gramps.gen.plug._pluginreg Registration Module]

;Gramps Addons site for Gramps 4.2 and newer
* https://github.com/gramps-project/addons-source - Source code (Git)
* https://github.com/gramps-project/addons - downloadable .tgz files
;Gramps Addons site for Gramps 4.1 and older
* For 4.1.x and earlier, see [[Addons development old]].

[[Category:Developers/General]]
[[Category:Developers/Tutorials]]
[[Category:Plugins]]
[[Category:Reports]]
[[Category:Gramplets]]
[[Category:Addons]]

Using the bug tracker

2022-10-08T15:04:31Z

Codefarmer: Add syntax code for Gramps Pull-Request

{{languages|Using the bug tracker}}
{{man tip|The bug/issue tracker for Gramps|is located at the following URL: <code>https://www.gramps-project.org/bugs</code>}}
This bug/issue tracker allows users and developers to log new issues and track them as they progress. Please take some time to read the issue tracker instructions below and read '''[[How to create a good bug report|how to create a good bug report]]'''. Also, have a look at '''[[Known_issues|known issues]]''' and '''[[Common_problems|common problems]]'''.

== Quick recommendations ==
When composing a problem (bug) report for Gramps:
* Be '''''precise'''''
* Be '''''clear''':'' explain how to reproduce the problem, step by step, so others can reproduce the bug, or understand the request.
* Include only '''''one problem per report'''''
* Include any relevant links and '''''examples'''''
{{man tip|Before you create a "Bug" report...|Composing a bug report can involve a lot of research and writing effort. Save yourself from unnecessary work.<ul><li>A solution or workaround might already exist in another bug report or in the forums.</li><li>If you connot find anything resembling your issue, ask about it in one of the forums. The community will help you solve or isolate the problem.</li></ul> }}

==Report a bug==
===1. Login===
To report a bug or raise a feature request, you must have a login account on the '''Gramps bug tracker''' ''([https://www.mantisbt.org/ powered by MantisBT])'':
* [https://bugs.gramps-project.org {{man button|Login}}] to your account at https://gramps-project.org/bugs/login_page.php , or;
* Select [https://gramps-project.org/bugs/signup_page.php {{man button|Signup for a new account}}] or visit the following link to create a new login account: https://gramps-project.org/bugs/signup_page.php .

Due to periodic SPAMbot activity, New Account requests might require human pre-approval. Be aware that this means that it might take up to 12 hours before a confirmation email is sent when creating a user account. Only after clicking on the link in the confirmation email can you submit bugs. Your email address will be handled confidentially.

{{-}}

===2. Search existing bugs===
[[File:Search box for existing bugs.png|thumb|right|450px|Search Box]]
Perhaps the bug you want to report has been submitted before. To check this, click on [https://gramps-project.org/bugs/view_all_bug_page.php {{man button|View Issues}}]. The top of the page is reserved for filters, which you set. Normally the default filters are just fine. Under these filters, there is a {{man label|Search}} box. Enter the terms best describing the bug, and click {{man button|Apply Filter}} to search. If you have an error message, try pasting a part of the error, to see if it is has been reported already.

If the bug is already reported, read over the bug report, and see if you can add to the information. If so, you can leave a note with extra information to help the developers.
{{-}}

===3. Submit new bug===
[[File:Report issue buttons Gramps bugs.png|thumb|right|450px|'Report Issue' buttons.]]
Click on one of the {{man label|Report Issue}} buttons, and enter the required information, see below on how to select the project to which the bug belongs. Be verbose, the developers are bad at mind reading. We shall mercilessly close the bugs which have no meaningful information at all, such as #{{bug|7126}}. Do not forget to list the Gramps version you are using. You can check this in Gramps by clicking in the Gramps program the Help menu, option About.
{{-}}
==== How to proceed ====
[[File:Dropdown-Choose-Project-GrampsBugtracker.png|thumb|right|450px|Choose Project - selection list]]
The first step in submitting an issue on the tracker is to determine which project it belongs to on the issue tracker from the '''Select Project''' box, use the '''Choose Project''' drop down list to select the "project" for the bugs. "Projects" are a way to categorize issues. There are two types of projects in the issue tracker, '''Feature Requests''' and '''Gramps''':

*The '''Feature Requests''' project is a place for recording requests for new features.
**If the issue represents functionality that does not currently exist in Gramps, then the issue should be filed under the '''Feature Requests''' project.

*The '''Gramps''' project is a place for recording all issues with Gramps.
**If the issue represents a problem with functionality that has been released in a stable release of code, then the issue should be filed under the project that corresponds to the maintenance branch for that release. For example, a bug found in Gramps 5.1.0 should be filed under the '''Gramps 5.1.0''' project.

*If the issue represents a problem with functionality that only exists in the master branch, or the problem exists in the master branch, but not any stable releases, then the issue should be filed under the '''Gramps Master''' project.
{{-}}

==== Enter Issue Details ====
[[File:Enter Issue Details page Gramps bugs.png|thumb|right|550px|Enter Issue Details - page]]
The {{man label|Enter Issue Details}} page is where you share with the developers what your issue or feature request is.

Try and complete all the relevant sections as well as you can and be prepared to answer follow up questions if your report needs clarification, it may help you to read the '''[[How to create a good bug report]]''' article.

===== Filling out the page =====

* Product Version
**The projects with names that look like '''Gramps x.x.X''' are where issues are reported that apply specifically to a maintenance branch (see [[Brief_introduction_to_Git#Types_of_branches|Types of Branches]]). A separate project exists for each maintenance branch.
**The '''Gramps Master''' project should only be used by developers and testers of the latest code. It is a place for recording issues that only apply to the master branch in Git (see [[Brief_introduction_to_Git#Types_of_branches|Types of Branches]]). There is only one "Gramps Master" project because there is only one master branch in the Git repository.
{{-}}

==Useful Mantis bug tracker Syntax codes==

The following are useful [http://www.mantisbt.org/ Mantis bug tracker] syntax codes you can use:
* Using ''<code>#</code>'' before a bug number writes a link to the bug. eg: ''<code>#1</code>'' becomes {{bug|1}}
* Use ''<code>@</code>'' before a user name to mention a person (note: user names with embedded spaces are not supported)
* Using ''<code>~</code>'' before a comment number writes a link to the comment, same as : ''<code>{url}#c{comment number}</code>''. eg: ''<code>~3</code>'' becomes [https://gramps-project.org/bugs/view.php?id=1#c3]
* To link a GitHub Pull Request in the bug tracker, use p:gramps:nnnn: where nnnn is the PR number.

=== Limited HTML tags ===
* A [https://github.com/mantisbt/mantisbt/blob/55fb5721ea7d980557da484390db5c6003b63cd0/config_defaults_inc.php#L1979 limited set] of [https://www.w3schools.com/tags/ HTML tags] can be used in the text field:
**<code> </code> to define a paragraph.
**<code> <li></code> to defines a [https://www.w3schools.com/tags/tag_li.asp list item] used with:
***<code> <ul></code> unordered lists
***<code> <ol></code> ordered lists
**<code> </code> to insert a single line break.
**<code> <pre> </pre></code> to add preformatted text, that is displayed in a fixed-width font, and it preserves both spaces and line breaks.
**<code> </code> usually displays text in ''italics''.
**<code> </code> shows '''bold''' text
**<code> </code> Underline a misspelled word
**<code> </code> It renders as emphasized text.
**<code> </code> It defines important text.

==See also==
* [[How to create a good bug report]]
* [[Known issues]]
* [[Common problems]]
* Help the Gramps project [[Bug triage]].

[[Category:Developers/General]]
[[Category:Developers/Quality Assurance]]

Gramps 5.1 Wiki Manual - Reports - part 2

2022-09-11T20:14:00Z

Codefarmer: Remove extraneous column

{{man index|Gramps 5.1 Wiki Manual - Reports - part 1|Gramps_5.1_Wiki_Manual_-_Reports_-_part_3|5.1}}
{{languages|Gramps_5.1_Wiki_Manual_-_Reports - part 2}}
{{#vardefine:chapter|13.2}}
{{#vardefine:figure|0}}
Back to [[Gramps_5.1_Wiki_Manual_-_Reports|Index of Reports]].
<hr>
This section describes the substitution values that can be used in the different reports available in Gramps.
= Substitution Values =

Many of the [[Gramps_5.1_Wiki_Manual_-_Reports_-_part_4#Graphical_Reports|graphical reports]] allow you to customize the information that is displayed on the reports. Variable substitution is the method that is used to substitute a particular symbol (key) for specific information about the person in the database.

For example:
{| {{prettytable}}
|-
! colspan="2"|Substitution Keys
! colspan="2"|Will show as: (the person is alive)
|-
!Line 1
|<code>$n</code>
!Line 1
|Smith, Edwin Michael
|-
!Line 2
|<code>b. $b{ at $B}</code>
!Line 2
|b. 1961-05-24 at San Jose, Santa Clara Co., CA
|-
!Line 3
|<code>d. $d< at >$D</code>
!Line 3
|d.
|-
|}

In the next section a list of all available variables (The Substitution Keys) follows.
* If you wish to display names, date, or place information differently, you may use [[#Format Strings|Format Strings]] to accomplish this.
* There are also [[#Control Variables|Control Variables]] to display special characters (like the dollar sign).
* You can also use [[#Grouping|Grouping]] to optionally display information. In the example above '''Line 2''', uses grouping to display <code>' at '</code> only when the birth place is known.
* Along with [[#Events|Events]] you can print almost anything.
* Finally, [[#Separators|Separators]], to make your life complete. In the example above '''Line 3''', uses this to display <code>' at '</code> only when both the birth date and place is known.

== The Substitution Keys ==
{| {{prettytable}}
|-
! colspan="2"|Personal variables
! colspan="2"|Marital variables
|-
!$n
|Displays the person's name
!$s
|Displays the name of the person's spouse
|-
!$i
|Displays the Gramps ID for the person.
!$j
|Displays the Gramps ID for the marriage.
|-
!$b
|Displays the person's date of birth
!$m
|Displays the marriage date of the person and the spouse.
|-
!$B
|Displays the person's place of birth
!$M
|Displays the place of the marriage of the person and the spouse.
|-
!$d
|Displays the person's date of death
!$v
|Displays the divorce date of the person and the spouse.
|-
!$D
|Displays the person's place of death
!$V
|Displays the place of the divorce of the person and the spouse.
|-
!$a
|Displays an attribute about the person.
see [[#Attributes|Attributes]] for more
!$u
|Displays an attribute about the marriage.
see [[#Attributes|Attributes]] for more
|-
!$e
|Displays event information about the person.
See [[#Events|Events]] for more
!$t
|Displays an event information about the marriage.
See [[#Events|Events]] for more
|}

All of the Marital variables are defined by the person's preferred spouse in Gramps. If the person has never been married, then these variables will not display anything.

==== Other Substitution Keys ====
* <code>$T</code> Displays Todays date.

=== Default displayed formats ===
{| {{prettytable}}
|-
!Variables
!Display format
|-
!$n $s
|Names will be displayed as set in 'Name format:' on the Display tab in Gramps preferences
|-
!$B $D $M $V
|Places will display the Place title by default
|-
!$b $d $m $v $T
|Dates will be displayed as set in 'Date format:' on the Display tab in Gramps preferences
|-
!$e $t
|Events will display the description by default
|}

=== Deprecated variables ===

Some of the old variables were deprecated because [[#Format Strings|Format Strings]] have replaced them. So here is a list of those variables and how to achieve their results:

{| {{prettytable}}
|-
!Old Variable
!How to display it now
!What is displayed
|-
|$f
|$n
|Name - as by Gramps name display under Preferences
|-
|$n
|$n(g f)
|Name - FirstName LastName
|-
|$N
|$n(f, g)
|Name - LastName, FirstName (note the explicit comma)
|-
|$nC
|$n(g F)
|Name - FirstName LastName in UPPER case
|-
|$NC
|$n(F, g)
|Name - LastName in UPPER case, FirstName
|-
|$by
|$b(yyyy)
|Date of birth, year only
|-
|$dy
|$d(yyyy)
|Date of death, year only
|-
|$my
|$m(yyyy)
|Date of preferred marriage, year only
|-
|$p
|$s
|Preferred spouse's name as by Gramps name display under Preferences
|-
|$s
|$s(g f)
|Preferred spouse's name - FirstName LastName
|-
|$S
|$s(f, g)
|Preferred spouse's name - LastName, FirstName
|-
|$sC
|$s(g F)
|Preferred spouse's name - FirstName LastName in UPPER case
|-
|$SC
|$s(F, g)
|Preferred spouse's name - LastName in UPPER case, FirstName
|}

== Format Strings ==

Format strings are used to display names and dates differently than those assigned under Gramps Preferences. Here is the syntax for a format string:

$''{{man label|key}}''(format string) 
where: ''{{man label|key}}'' is one of the following characters: 'nsijbmBMdvDVauet'

A format string is any text, separators or format codes (defined below) to display information about the person.

=== Formatting names ===

For names <code>($n $s)</code> you may use the following formatting codes to display the name differently.

{| {{prettytable}}
|-
!t
|Title
!f
|Given name
|-
!x
|Common name. Call name if existing, otherwise first first name
!c
|Call name
|-
!n
|Nick name
!s
|Suffix
|-
!l
|Surname
!g
|Family nickname
|}

These codes can be upper-cased to uppercase the result.

For example:
{| {{prettytable}}
|-
!Formatting code
!Displays
|-
|<pre>$n(L, f) ($n(c)), $n(L, f){ ($n(c))}
$s(f l s)</pre>
|<pre>SMITH, Edwin Michael (), SMITH, Edwin Michael
Janice Ann Adams</pre>
|}
{{man note|Note:|If you want to print a character 'c' within the format string (or any one of the other format codes), you will need to first add a <code>'\'</code> in front of it. See [[#Control Variables|Control Variables]] for more.}}

{{man note|Note:|The curly brackets <code>{ }</code> are used to hide information. Here it is used around <code>' ($n(c))'</code> to not display <code>' ()'</code> if the person does not have a call name. See [[#Grouping|Grouping]] for more.}}

=== Formatting Dates ===
For all of the date variables <code>($b $d $m $v)</code> you may use the following formatting codes:

{| {{prettytable}}
|-
!yyyy
|The year as a four digit number
!yyy
|The year, with a minimum of three digits
|-
!yy
|The year, from 00 to 99
!y
|The year, from 0 to 99
|-
!mmmm 
'''MMMM'''
|The full name of the month 
The full name IN CAPS
!mmm 
'''MMM'''
|The abbreviated name of the month 
The abbreviated name IN CAPS
|-
!mm
|The month, from 00 to 12
!m
|The month, from 0 to 12
|-
!dd
|The day, from 00 to 31
!d
|The day, from 0 to 31
|-
!o
|The date type (modifier)
!
|
|}

For example:
{| {{prettytable}}
|-
!Formatting code
!displays
|-
|<pre>$b(mmm-dd yy)
$m(yyyy/mmm/d)
$b(mmm-dd yy)</pre>
|<pre>May-24 61
1995/May/27
Jun-04 85</pre>
|}

{{man warn| For date types (modifier) |Only "Before", "After", and "About" are supported at this time. all others will not display anything. And for date span and date ranges, only the starting (first) date is displayed.}}

=== Formatting Places ===
For all of the place variables <code>($B $D $M $V)</code> you may use the following formatting codes:

{| {{prettytable}}
|-
!e
|Street
!l
|Locality
|-
!c
|City
!u
|County
|-
!s
|State
!p
|Postal Code
|-
!n
|Country
!t
|Title
|-
!x
|Longitude
!y
|Latitude
|}
These codes can be upper-cased to uppercase the result.

For example:
{| {{prettytable}}
|-
!Formatting code
!displays
|-
|<pre>$B
$B(c, s, N)</pre>
|<pre>St Judes Hospital
Carmel, IN, USA</pre>
|}

=== Rules for format strings ===

* Anything will print inside a format string
* You need to use [[#Control Variables|Control Variables]] to display things like <code>')'</code> and format codes
* Separators can be within format strings.
* At least ONE format code has to display something for the ENTIRE format string to display

For examples:
{| {{prettytable}}
|-
!Formatting code
!displays
|-
|<pre>$n(f l)
b. $b {at $B
{d. $d $D</pre>
|<pre>Edwin Michael Smith
b. 1961-05-24 at San Jose, Santa Clara Co., CA</pre>{{man label|The person is still alive (or has no information present) so the line was removed.}}
|}

== Control Variables ==

Control variables allow you to print characters that are special to Substitution values within a display.

For example the dollar character '$' is used to note the start of a variable. If you wish to print a dollar character you would use a control character like '\$'

{| {{prettytable}}
!Control Variables
!Result
|-
!\$
|Displays a single <code>'$'</code>
|-
!\\
|Displays a single <code>'\'</code>
|-
!$
|Displays a single <code>'('</code>
|-
!$
|Displays a single <code>')'</code>
|-
!\{
|Displays a single <code>'{'</code>
|-
!\}
|Displays a single <code>'}'</code>
|-
!\<
|Displays a single <code>'<'</code>
|-
!\>
|Displays a single <code>'>'</code>
|}

Basically anything that comes after a <code>'\'</code> will be printed.

{{man note|Note:|When you are inside a format string, you may need to use this to display a character that would normally be a format code.}}

For example:
{| {{prettytable}}
|-
!Formatting code:
!displays
|-
|<pre>$b(m hi mom)
$b(m hi \mo\m)</pre>
|<pre>5 hi 5o5
5 hi mom</pre>{{man label|As this person was born on the fifth month.}}
|}

== Grouping ==

There are instances where you do not want certain text to be displayed.

Take the example:
{| {{prettytable}}
|-
!Formatting Code
!Only date is known
!Only place is known
|-
|<code>died on $d at $D</code>
|<code>died on 1975-06-26 at</code>
|<code>died on at Reno, Washoe Co., NV<code>
|-
|}
Neither of these displayed results are very acceptable.

But with groups (denoted by '''{}'''), you can optionally print information if a variable within contains information.

{| {{prettytable}}
|-
!Formatting Code
!Only date is known
!Only place is known
|-
|<code>died{ on $d}{ at $D}</code>
|<code>died on 1975-06-26</code>
|<code>died at Reno, Washoe Co., NV</code>
|}
Which is a more preferable displayed result than in the first example.

=== Rules for groups ===

A group will only display if there is at least one variable that displays something. So if a group only has text and/or variables where the information is not known, the entire group will not print.

Groups can also be nested. If this happens (like below), the outer group will only display if there is at least one variable that displays something within the outer group or any of the sub groups.

Groups can also be used to remove text. If you wish to not display the entire line, <code>'-'</code> at the start of a line will remove the entire line from the display if the above rule is true.

If you do not wish to have the display code above (for death information) displayed (the person is alive, or you do not yet know the information), modify the code to look like:
* <code>-{died{ on $d}{ at $D}</code>

=== Examples ===
This will hide <code>'('</code> and <code>')'</code> if the divorce information is not known (or still married).
* <code>m. $m $M {- ($v(yyyy))</code>

Only display some spouse information if married or remove the entire line if never married:
* <code>{$s $m(yyyy) {- $v($yyyy$)}}</code>

== Attributes ==
Attributes do not have a format string. Instead the attribute name is placed inside <code>[]</code>. Here is the syntax for an attribute:

$''{{man label|key}}''[attribute name] 
where: ''{{man label|key}}'' is one of the following characters: 'au'

For example:
{| {{prettytable}}
!Formatting code
!displays
|-
|<pre>$a[Profession]
$a[Social Security Number]
$a[Total \$ bequeathed]</pre>
|<pre>Programmer
7A3-29-F1C6
3.00USD</pre>
|}

== Events ==

Events have the same starting structure as attributes, <code>$e</code> or <code>$t</code> and the event name in <code>[]</code> but events have an extra format string after the name to display the description, date, place, id, and attributes associated with it. Each of these items can be displayed with a , a 'n', 'd', 'D', 'i', and 'a' respectively in the format string. Here is the syntax for an event:

$''{{man label|key}}''[attribute name](format string) 
where: ''{{man label|key}}'' is one of the following characters: 'et'

=== Event format strings ===

The Event format string is used to display information about the event. Here are the format codes to display parts of the event:

{| {{prettytable}}
!Formatting code
!displays
!
!Formatting code
!displays
|-
!n
|Description
|
!i
|Event ID
|-
!d
|Event Date*
|
!D
|Event Place*
|-
!a
|An attributes for the event**
|
|
|
|}

*These variables can themselves have format strings. Date and a place can be formatted with format string as defined in [[#Format strings|Format strings]].

**Attribute needs to have the attribute name in [] and are formatted as above.

For example:
{| {{prettytable}}
!Formatting code
!displays
|-
|<pre>$e[First Communion](d(yyyy-mm-d))
$e[Bar Mitzvah](n< at > D)
$e[Birth](d(yyyy mm/dd) D)</pre>
|<pre>2009-11-6
Jerry's Bar Mitzah at Opas house
2007 05/23 Grandmothers house</pre>
|}

And:
{| {{prettytable}}
!Formatting code
!
!displays
|-
|<pre>$b(yyyy-Mmm-dd)
$M</pre>
|is the same as
|<pre>$e[Birth](d(yyyy-Mmm-dd))
$t[Marriage](D)</pre>
|}

=== Notes for attributes and events ===

Attribute and event names are mandatory. <code>'$a'</code> or <code>'$a[]'</code> will not display anything.

Attributes and event names may have special characters within them. Most notably <code>']'</code> and <code>')'</code>. If this is the case, you will need to use [[#Control Variables|Control Variables]]

== Separators ==

Separators are special 'text only' groups inside <code>'<'</code> and <code>'>'</code> that conditionally display a separator (like <code>', '</code> or <code>' - '</code>) between two groups, variables, format codes or text.

Separators are displayed conditionally depending on these rules:
* A variable that does '''not''' display anything will remove itself and a separator that is to the left of it from the display line only.
* If there is not a separator to the left, the same variable will remove itself and a separator that is to the right of it from the displayed line.
* If there are two separators together, the left one will be removed from the display line and the right is kept.
* Separators at the start or end of the display line (or format strings) are removed.

Take this example formatting code:
* <code>$s(f l s)<, >$m(yyyy)< @ >$M< - >$v($yyyy$)</code>

Here are some things that may happen:
{| {{prettytable}}
!Possibility
!Outcome
|-
|If '''none''' of the variables are known
|None of the separators will display
|-
|If only one variable '''is''' known
|Only that variable will print. No separators will print.
|-
|If only the spouse's name '''is not''' known
|The first separator will not display
|-
|If only the marriage date '''is not''' known
|The first separator does not display. We will be left with:
Jane Doe< - >{ … }And only the divorce date needs to be known to print the second separator.
|-
|If only the divorce date '''is not''' known
|the second separator will not display
|}

Separators can be inside format strings:
* <code>$n(<0>T< >L<, >f< >s)</code>

Unlike groups, separators can not cross over/out of format strings. So the separator <code><0></code> will NEVER display. No matter what is on the left hand side of the variable.

Here is a useful example:
* <code>{({b. $b}<, >{d. $d})}</code>

This will:
{| {{prettytable}}
|-
|Only print the outside () if either the birth or death date displays 
Only displays the center separator if both dates are known. 
So here are some thing that could display
{|
|-
|<code>(b. 1970-4-8)</code>
|<code>(d. 2012-3-9)</code>
|<code>(b. 1970-4-8, d. 2012-3-9)</code>
|or the line does not print at all.
|}
|-
| We will not see things like:
{|
|-
|<code>()</code>
|<code>(, )</code>
|<code>(b.)</code>
|<code>(b., )</code>
|<code>(d.)</code>
|-
|<code>(, d.)</code>
|<code>(b. 1970-4-8, )</code>
|<code>(b. 1970-4-8, d.)</code>
|<code>(, d. 2012-3-9)</code>
|<code>(b., d. 2012-3-9)</code>
|}
|}

{{-}}
<hr>
Back to [[Gramps_5.1_Wiki_Manual_-_Reports|Index of Reports]].
{{man index|Gramps 5.1 Wiki Manual - Reports - part 1|Gramps_5.1_Wiki_Manual_-_Reports_-_part_3|5.1}}
{{languages|Gramps 5.1 Wiki Manual - Reports - part 2}}
{{grampsmanualcopyright}}

[[Category:Documentation]]
[[Category:Plugins]]

Gramps 5.1 Wiki Manual - Reports - part 2

2022-09-11T20:08:01Z

Codefarmer: Add header to table describing fields

{{man index|Gramps 5.1 Wiki Manual - Reports - part 1|Gramps_5.1_Wiki_Manual_-_Reports_-_part_3|5.1}}
{{languages|Gramps_5.1_Wiki_Manual_-_Reports - part 2}}
{{#vardefine:chapter|13.2}}
{{#vardefine:figure|0}}
Back to [[Gramps_5.1_Wiki_Manual_-_Reports|Index of Reports]].
<hr>
This section describes the substitution values that can be used in the different reports available in Gramps.
= Substitution Values =

Many of the [[Gramps_5.1_Wiki_Manual_-_Reports_-_part_4#Graphical_Reports|graphical reports]] allow you to customize the information that is displayed on the reports. Variable substitution is the method that is used to substitute a particular symbol (key) for specific information about the person in the database.

For example:
{| {{prettytable}}
|-
! colspan="2"|Substitution Keys
! colspan="2"|Will show as: (the person is alive)
|-
!Line 1
|<code>$n</code>
!Line 1
|Smith, Edwin Michael
|-
!Line 2
|<code>b. $b{ at $B}</code>
!Line 2
|b. 1961-05-24 at San Jose, Santa Clara Co., CA
|-
!Line 3
|<code>d. $d< at >$D</code>
!Line 3
|d.
|-
|}

In the next section a list of all available variables (The Substitution Keys) follows.
* If you wish to display names, date, or place information differently, you may use [[#Format Strings|Format Strings]] to accomplish this.
* There are also [[#Control Variables|Control Variables]] to display special characters (like the dollar sign).
* You can also use [[#Grouping|Grouping]] to optionally display information. In the example above '''Line 2''', uses grouping to display <code>' at '</code> only when the birth place is known.
* Along with [[#Events|Events]] you can print almost anything.
* Finally, [[#Separators|Separators]], to make your life complete. In the example above '''Line 3''', uses this to display <code>' at '</code> only when both the birth date and place is known.

== The Substitution Keys ==
{| {{prettytable}}
|-
! colspan="2"|Personal variables
! colspan="2"|Marital variables
|-
!$n
|Displays the person's name
!$s
|Displays the name of the person's spouse
|-
!$i
|Displays the Gramps ID for the person.
!$j
|Displays the Gramps ID for the marriage.
|-
!$b
|Displays the person's date of birth
!$m
|Displays the marriage date of the person and the spouse.
|-
!$B
|Displays the person's place of birth
!$M
|Displays the place of the marriage of the person and the spouse.
|-
!$d
|Displays the person's date of death
!$v
|Displays the divorce date of the person and the spouse.
|-
!$D
|Displays the person's place of death
!$V
|Displays the place of the divorce of the person and the spouse.
|-
!$a
|Displays an attribute about the person.
see [[#Attributes|Attributes]] for more
!$u
|Displays an attribute about the marriage.
see [[#Attributes|Attributes]] for more
|-
!$e
|Displays event information about the person.
See [[#Events|Events]] for more
!$t
|Displays an event information about the marriage.
See [[#Events|Events]] for more
|}

All of the Marital variables are defined by the person's preferred spouse in Gramps. If the person has never been married, then these variables will not display anything.

==== Other Substitution Keys ====
* <code>$T</code> Displays Todays date.

=== Default displayed formats ===
{| {{prettytable}}
|-
!Variables
!Display format
|-
!$n $s
|Names will be displayed as set in 'Name format:' on the Display tab in Gramps preferences
|-
!$B $D $M $V
|Places will display the Place title by default
|-
!$b $d $m $v $T
|Dates will be displayed as set in 'Date format:' on the Display tab in Gramps preferences
|-
!$e $t
|Events will display the description by default
|}

=== Deprecated variables ===

Some of the old variables were deprecated because [[#Format Strings|Format Strings]] have replaced them. So here is a list of those variables and how to achieve their results:

{| {{prettytable}}
|-
!Old Variable
!How to display it now
!What is displayed
|-
|$f
|$n
|Name - as by Gramps name display under Preferences
|-
|$n
|$n(g f)
|Name - FirstName LastName
|-
|$N
|$n(f, g)
|Name - LastName, FirstName (note the explicit comma)
|-
|$nC
|$n(g F)
|Name - FirstName LastName in UPPER case
|-
|$NC
|$n(F, g)
|Name - LastName in UPPER case, FirstName
|-
|$by
|$b(yyyy)
|Date of birth, year only
|-
|$dy
|$d(yyyy)
|Date of death, year only
|-
|$my
|$m(yyyy)
|Date of preferred marriage, year only
|-
|$p
|$s
|Preferred spouse's name as by Gramps name display under Preferences
|-
|$s
|$s(g f)
|Preferred spouse's name - FirstName LastName
|-
|$S
|$s(f, g)
|Preferred spouse's name - LastName, FirstName
|-
|$sC
|$s(g F)
|Preferred spouse's name - FirstName LastName in UPPER case
|-
|$SC
|$s(F, g)
|Preferred spouse's name - LastName in UPPER case, FirstName
|}

== Format Strings ==

Format strings are used to display names and dates differently than those assigned under Gramps Preferences. Here is the syntax for a format string:

$''{{man label|key}}''(format string) 
where: ''{{man label|key}}'' is one of the following characters: 'nsijbmBMdvDVauet'

A format string is any text, separators or format codes (defined below) to display information about the person.

=== Formatting names ===

For names <code>($n $s)</code> you may use the following formatting codes to display the name differently.

{| {{prettytable}}
|-
!t
|Title
!f
|Given name
|-
!x
|Common name. Call name if existing, otherwise first first name
!c
|Call name
|-
!n
|Nick name
!s
|Suffix
|-
!l
|Surname
!g
|Family nickname
|}

These codes can be upper-cased to uppercase the result.

For example:
{| {{prettytable}}
|-
!Formatting code
!Displays
|-
|<pre>$n(L, f) ($n(c)), $n(L, f){ ($n(c))}
$s(f l s)</pre>
|<pre>SMITH, Edwin Michael (), SMITH, Edwin Michael
Janice Ann Adams</pre>
|}
{{man note|Note:|If you want to print a character 'c' within the format string (or any one of the other format codes), you will need to first add a <code>'\'</code> in front of it. See [[#Control Variables|Control Variables]] for more.}}

{{man note|Note:|The curly brackets <code>{ }</code> are used to hide information. Here it is used around <code>' ($n(c))'</code> to not display <code>' ()'</code> if the person does not have a call name. See [[#Grouping|Grouping]] for more.}}

=== Formatting Dates ===
For all of the date variables <code>($b $d $m $v)</code> you may use the following formatting codes:

{| {{prettytable}}
|-
!yyyy
|The year as a four digit number
!yyy
|The year, with a minimum of three digits
|-
!yy
|The year, from 00 to 99
!y
|The year, from 0 to 99
|-
!mmmm 
'''MMMM'''
|The full name of the month 
The full name IN CAPS
!mmm 
'''MMM'''
|The abbreviated name of the month 
The abbreviated name IN CAPS
|-
!mm
|The month, from 00 to 12
!m
|The month, from 0 to 12
|-
!dd
|The day, from 00 to 31
!d
|The day, from 0 to 31
|-
!o
|The date type (modifier)
!
|
|}

For example:
{| {{prettytable}}
|-
!Formatting code
!displays
|-
|<pre>$b(mmm-dd yy)
$m(yyyy/mmm/d)
$b(mmm-dd yy)</pre>
|<pre>May-24 61
1995/May/27
Jun-04 85</pre>
|}

{{man warn| For date types (modifier) |Only "Before", "After", and "About" are supported at this time. all others will not display anything. And for date span and date ranges, only the starting (first) date is displayed.}}

=== Formatting Places ===
For all of the place variables <code>($B $D $M $V)</code> you may use the following formatting codes:

{| {{prettytable}}
|-
!e
|Street
|
!l
|Locality
|-
!c
|City
|
!u
|County
|-
!s
|State
|
!p
|Postal Code
|-
!n
|Country
|
!t
|Title
|-
!x
|Longitude
|
!y
|Latitude
|}
These codes can be upper-cased to uppercase the result.

For example:
{| {{prettytable}}
|-
!Formatting code
!displays
|-
|<pre>$B
$B(c, s, N)</pre>
|<pre>St Judes Hospital
Carmel, IN, USA</pre>
|}

=== Rules for format strings ===

* Anything will print inside a format string
* You need to use [[#Control Variables|Control Variables]] to display things like <code>')'</code> and format codes
* Separators can be within format strings.
* At least ONE format code has to display something for the ENTIRE format string to display

For examples:
{| {{prettytable}}
|-
!Formatting code
!displays
|-
|<pre>$n(f l)
b. $b {at $B
{d. $d $D</pre>
|<pre>Edwin Michael Smith
b. 1961-05-24 at San Jose, Santa Clara Co., CA</pre>{{man label|The person is still alive (or has no information present) so the line was removed.}}
|}

== Control Variables ==

Control variables allow you to print characters that are special to Substitution values within a display.

For example the dollar character '$' is used to note the start of a variable. If you wish to print a dollar character you would use a control character like '\$'

{| {{prettytable}}
!Control Variables
!Result
|-
!\$
|Displays a single <code>'$'</code>
|-
!\\
|Displays a single <code>'\'</code>
|-
!$
|Displays a single <code>'('</code>
|-
!$
|Displays a single <code>')'</code>
|-
!\{
|Displays a single <code>'{'</code>
|-
!\}
|Displays a single <code>'}'</code>
|-
!\<
|Displays a single <code>'<'</code>
|-
!\>
|Displays a single <code>'>'</code>
|}

Basically anything that comes after a <code>'\'</code> will be printed.

{{man note|Note:|When you are inside a format string, you may need to use this to display a character that would normally be a format code.}}

For example:
{| {{prettytable}}
|-
!Formatting code:
!displays
|-
|<pre>$b(m hi mom)
$b(m hi \mo\m)</pre>
|<pre>5 hi 5o5
5 hi mom</pre>{{man label|As this person was born on the fifth month.}}
|}

== Grouping ==

There are instances where you do not want certain text to be displayed.

Take the example:
{| {{prettytable}}
|-
!Formatting Code
!Only date is known
!Only place is known
|-
|<code>died on $d at $D</code>
|<code>died on 1975-06-26 at</code>
|<code>died on at Reno, Washoe Co., NV<code>
|-
|}
Neither of these displayed results are very acceptable.

But with groups (denoted by '''{}'''), you can optionally print information if a variable within contains information.

{| {{prettytable}}
|-
!Formatting Code
!Only date is known
!Only place is known
|-
|<code>died{ on $d}{ at $D}</code>
|<code>died on 1975-06-26</code>
|<code>died at Reno, Washoe Co., NV</code>
|}
Which is a more preferable displayed result than in the first example.

=== Rules for groups ===

A group will only display if there is at least one variable that displays something. So if a group only has text and/or variables where the information is not known, the entire group will not print.

Groups can also be nested. If this happens (like below), the outer group will only display if there is at least one variable that displays something within the outer group or any of the sub groups.

Groups can also be used to remove text. If you wish to not display the entire line, <code>'-'</code> at the start of a line will remove the entire line from the display if the above rule is true.

If you do not wish to have the display code above (for death information) displayed (the person is alive, or you do not yet know the information), modify the code to look like:
* <code>-{died{ on $d}{ at $D}</code>

=== Examples ===
This will hide <code>'('</code> and <code>')'</code> if the divorce information is not known (or still married).
* <code>m. $m $M {- ($v(yyyy))</code>

Only display some spouse information if married or remove the entire line if never married:
* <code>{$s $m(yyyy) {- $v($yyyy$)}}</code>

== Attributes ==
Attributes do not have a format string. Instead the attribute name is placed inside <code>[]</code>. Here is the syntax for an attribute:

$''{{man label|key}}''[attribute name] 
where: ''{{man label|key}}'' is one of the following characters: 'au'

For example:
{| {{prettytable}}
!Formatting code
!displays
|-
|<pre>$a[Profession]
$a[Social Security Number]
$a[Total \$ bequeathed]</pre>
|<pre>Programmer
7A3-29-F1C6
3.00USD</pre>
|}

== Events ==

Events have the same starting structure as attributes, <code>$e</code> or <code>$t</code> and the event name in <code>[]</code> but events have an extra format string after the name to display the description, date, place, id, and attributes associated with it. Each of these items can be displayed with a , a 'n', 'd', 'D', 'i', and 'a' respectively in the format string. Here is the syntax for an event:

$''{{man label|key}}''[attribute name](format string) 
where: ''{{man label|key}}'' is one of the following characters: 'et'

=== Event format strings ===

The Event format string is used to display information about the event. Here are the format codes to display parts of the event:

{| {{prettytable}}
!Formatting code
!displays
!
!Formatting code
!displays
|-
!n
|Description
|
!i
|Event ID
|-
!d
|Event Date*
|
!D
|Event Place*
|-
!a
|An attributes for the event**
|
|
|
|}

*These variables can themselves have format strings. Date and a place can be formatted with format string as defined in [[#Format strings|Format strings]].

**Attribute needs to have the attribute name in [] and are formatted as above.

For example:
{| {{prettytable}}
!Formatting code
!displays
|-
|<pre>$e[First Communion](d(yyyy-mm-d))
$e[Bar Mitzvah](n< at > D)
$e[Birth](d(yyyy mm/dd) D)</pre>
|<pre>2009-11-6
Jerry's Bar Mitzah at Opas house
2007 05/23 Grandmothers house</pre>
|}

And:
{| {{prettytable}}
!Formatting code
!
!displays
|-
|<pre>$b(yyyy-Mmm-dd)
$M</pre>
|is the same as
|<pre>$e[Birth](d(yyyy-Mmm-dd))
$t[Marriage](D)</pre>
|}

=== Notes for attributes and events ===

Attribute and event names are mandatory. <code>'$a'</code> or <code>'$a[]'</code> will not display anything.

Attributes and event names may have special characters within them. Most notably <code>']'</code> and <code>')'</code>. If this is the case, you will need to use [[#Control Variables|Control Variables]]

== Separators ==

Separators are special 'text only' groups inside <code>'<'</code> and <code>'>'</code> that conditionally display a separator (like <code>', '</code> or <code>' - '</code>) between two groups, variables, format codes or text.

Separators are displayed conditionally depending on these rules:
* A variable that does '''not''' display anything will remove itself and a separator that is to the left of it from the display line only.
* If there is not a separator to the left, the same variable will remove itself and a separator that is to the right of it from the displayed line.
* If there are two separators together, the left one will be removed from the display line and the right is kept.
* Separators at the start or end of the display line (or format strings) are removed.

Take this example formatting code:
* <code>$s(f l s)<, >$m(yyyy)< @ >$M< - >$v($yyyy$)</code>

Here are some things that may happen:
{| {{prettytable}}
!Possibility
!Outcome
|-
|If '''none''' of the variables are known
|None of the separators will display
|-
|If only one variable '''is''' known
|Only that variable will print. No separators will print.
|-
|If only the spouse's name '''is not''' known
|The first separator will not display
|-
|If only the marriage date '''is not''' known
|The first separator does not display. We will be left with:
Jane Doe< - >{ … }And only the divorce date needs to be known to print the second separator.
|-
|If only the divorce date '''is not''' known
|the second separator will not display
|}

Separators can be inside format strings:
* <code>$n(<0>T< >L<, >f< >s)</code>

Unlike groups, separators can not cross over/out of format strings. So the separator <code><0></code> will NEVER display. No matter what is on the left hand side of the variable.

Here is a useful example:
* <code>{({b. $b}<, >{d. $d})}</code>

This will:
{| {{prettytable}}
|-
|Only print the outside () if either the birth or death date displays 
Only displays the center separator if both dates are known. 
So here are some thing that could display
{|
|-
|<code>(b. 1970-4-8)</code>
|<code>(d. 2012-3-9)</code>
|<code>(b. 1970-4-8, d. 2012-3-9)</code>
|or the line does not print at all.
|}
|-
| We will not see things like:
{|
|-
|<code>()</code>
|<code>(, )</code>
|<code>(b.)</code>
|<code>(b., )</code>
|<code>(d.)</code>
|-
|<code>(, d.)</code>
|<code>(b. 1970-4-8, )</code>
|<code>(b. 1970-4-8, d.)</code>
|<code>(, d. 2012-3-9)</code>
|<code>(b., d. 2012-3-9)</code>
|}
|}

{{-}}
<hr>
Back to [[Gramps_5.1_Wiki_Manual_-_Reports|Index of Reports]].
{{man index|Gramps 5.1 Wiki Manual - Reports - part 1|Gramps_5.1_Wiki_Manual_-_Reports_-_part_3|5.1}}
{{languages|Gramps 5.1 Wiki Manual - Reports - part 2}}
{{grampsmanualcopyright}}

[[Category:Documentation]]
[[Category:Plugins]]

Gramps 5.1 Wiki Manual - Reports

2022-09-11T20:00:44Z

Codefarmer: Typo corrections

{{man index|Gramps 5.1 Wiki Manual - Gramplets|Gramps 5.1 Wiki Manual - Reports - part 1|5.1}}
{{languages|Gramps_5.1_Wiki_Manual_-_Reports}}
{{#vardefine:chapter|13}}
{{#vardefine:figure|0}}
[[File:Menubar-ReportsOverview-50.png|thumb|right|450px|Fig. {{#var:chapter}}.{{#vardefineecho:figure|{{#expr:{{#var:figure}}+1}}}} Menubar - Reports Overview]]
This section describes all the different reports available in Gramps.

Gramps comes with a large number of available reports. The different subsections describe the various possibilities and options:

{{man note|Additional Reports |Gramps has even more reports available to install, made by volunteers just like you they are called Addons and you check the growing list of available reports [[5.1_Addons|'''here''']].. This system is controlled by the [[Gramps_5.1_Wiki_Manual_-_Plugin_Manager|'''Plugin Manager''']]. }}

=Introduction=
[[Gramps 5.1 Wiki Manual - Reports - part 1|Generating Reports]]: This first subsection gives you some general remarks.

= Reports =
[[File:ToolbarIcon-OpenTheReportsDialog-50.png|right|thumb|400px|Fig. {{#var:chapter}}.{{#vardefineecho:figure|{{#expr:{{#var:figure}}+1}}}} Toolbar Icon for "Open the reports dialog"]]

The reports can be accessed by choosing the menu {{man menu|Reports ->''Report Section'' ->''Particular Report''}} .

Alternatively, you can browse the complete selection of available reports along with their brief descriptions in a {{man label|[[Gramps_5.1_Wiki_Manual_-_Reports#Report_Selection_dialog|Report Selection]]}} dialog invoked by clicking the {{man button|Open the reports dialog}} icon on the toolbar from any of the categories.
{{-}}
== Report Selection dialog ==

[[File:ReportSelection-dialog-example-50.png|right|thumb|400px|Fig. {{#var:chapter}}.{{#vardefineecho:figure|{{#expr:{{#var:figure}}+1}}}} Report Selection - dialog - example showing "Timeline Chart" information]]

The {{man label|Report Selection}} dialog allows you to browse the complete selection of available reports along with their brief descriptions when invoked by clicking the {{man button|Open the reports dialog}} icon on the toolbar from any of the categories and using the {{man button|▶}} arrows to expand the listings.
{{-}}


=Substitution Values=
[[Gramps 5.1 Wiki Manual - Reports - part 2|Substitution Values]]: you can use some handy values in your reports. (Selected reports only)

=Books=
[[Gramps 5.1 Wiki Manual - Reports - part 3#Books|The Books Report]] allows you to create a custom '''genealogy book''' containing a collection of Gramps textual and graphical reports in a single document (i.e. a Book)

==Available items selections==
===Alphabetical Index===
[[Gramps_5.1_Wiki_Manual_-_Reports_-_part_3#Alphabetical_Index|Alphabetical Index]] - This item produces page(s) with an alphabetical index of people noted into selected textual reports.

===Custom Text===
[[Gramps_5.1_Wiki_Manual_-_Reports_-_part_3#Custom_Text|Custom Text]] - This item produces a page with three paragraphs, each containing custom text: Initial Text, Middle Text and Final Text. The text input fields are expandable so you can really put all the text you want in there.

===Table Of Contents===
[[Gramps_5.1_Wiki_Manual_-_Reports_-_part_3#Table_of_contents|Table Of Contents]] - A Table of contents (TOC) is generated for book as a list of the parts of a book or document organized in the order in which the parts appear.

===Title Page===
[[Gramps_5.1_Wiki_Manual_-_Reports_-_part_3#Title_Page|Title Page]] - A title page for your book.


=Graphs=
[[Gramps_5.1_Wiki_Manual_-_Reports_-_part_5#Graphs|Graphs]] reports are created in Graphviz format and then converted into graphical output running it through the Graphviz dot tool behind the scene.

===Family Lines Graph===
[[File:Graphs-FamilyLinesGraph-example-overview-50.png|100px|Family Lines Graph]]The [[Gramps 5.1 Wiki Manual - Reports - part 5#Family Lines Graph|Family Lines Graph]] creates an easy-to-follow graph.

===Hourglass Graph===
[[File:Graphs-HourglassGraph-example-overview-50.png|100px|Hourglass]]The [[Gramps 5.1 Wiki Manual - Reports - part 5#Hourglass Graph|Hourglass Graph]] generate an hourglass graph.
===Relationship Graph===
[[File:Graphs-RelationshipGraph-example-overview-50.png|100px|Relationship]]The [[Gramps 5.1 Wiki Manual - Reports - part 5#Relationship Graph|Relationship Graph]] creates a complex relationship graph.


=Graphical Reports=
[[Gramps_5.1_Wiki_Manual_-_Reports_-_part_4#Graphical_Reports|Graphical reports]] represent information in forms of charts and graphs.

===Ancestor Tree===
The [[Gramps 5.1 Wiki Manual - Reports - part 4#Ancestor Tree|Ancestor Tree report]] generates the chart of people who are ancestors of the Active Person.

===Calendar===
The [[Gramps 5.1 Wiki Manual - Reports - part 4#Calendar|Calendar report]] produces a calendar with birthdays and anniversaries on a page by month.
===Descendant Tree===
The [[Gramps 5.1 Wiki Manual - Reports - part 4#Descendant Tree|Descendant Tree report]] generates a graph of people who are descendants of the Active Person.

===Family Descendant Tree===
The [[Gramps 5.1 Wiki Manual - Reports - part 4#Family Descendant Tree|Family Descendant Tree]] generates a graph of people who are descendants of the Active Family.

===Fan Chart===
The [[Gramps 5.1 Wiki Manual - Reports - part 4#Fan Chart|Fan Chart report]] produces a chart resembling a fan, with Active Person in the center, parents the semicircle next to it, ans so on, for a total of five generations.
====See also====
{{fan_charts}}

===Statistics Charts===
The [[Gramps 5.1 Wiki Manual - Reports - part 4#Statistics Charts|Statistics Charts report]] can collect and display a wealth of statistical data about your database.

===Timeline Chart===
The [[Gramps 5.1 Wiki Manual - Reports - part 4#Timeline Chart|Timeline Chart report]] outputs the list of people with their lifetimes represented by intervals on a common chronological scale.


=Text Reports=
[[Gramps_5.1_Wiki_Manual_-_Reports_-_part_6#Text_Reports|Text reports]] output information as formatted text.
===Ahnentafel Report===
The [[Gramps 5.1 Wiki Manual - Reports - part 6#Ahnentafel Report|Ahnentafel Report]] lists the Active Person and his or her ancestors along with their vital data. The people are numbered in an establish standard called 'Ahnentafel'.
===Birthday and Anniversary Report===
The [[Gramps 5.1 Wiki Manual - Reports - part 6#Birthday and Anniversary Report|Birthday and Anniversary Report]] gives the same information as a calendar but in text format.
===Complete Individual Report===
The [[Gramps 5.1 Wiki Manual - Reports - part 6#Complete Individual Report|Complete Individual Report]] provides individual summaries similar to that of the Individual Summary Report.
===Database Summary Report===
The [[Gramps_5.1_Wiki_Manual_-_Reports_-_part_6#Database_Summary_Report|Database Summary Report]] displays the overall statistics concerning number of individuals of each gender, various incomplete entries statistics, as well as family and media statistics.
===Descendant Report===
The [[Gramps 5.1 Wiki Manual - Reports - part 6#Descendant Report|Descendant Report]] presents the descendants of the Active Person with a brief description in intended style.

===Detailed Ancestral Report===
The [[Gramps 5.1 Wiki Manual - Reports - part 6#Detailed Ancestral Report|Detailed Ancestral Report]] covers in detail the ancestors of the Active Person, including a range of vital data as well as marriages.

===Detailed Descendant Report===
The [[Gramps 5.1 Wiki Manual - Reports - part 6#Detailed Descendant Report|Detailed Descendant Report]] covers in detail the descendants of the Active Person by generation, following the genealogical tradition of textual descendant reports by generation. It aims to provide all important features expected to be found in these classic descendency formats and has received influence from various sources.

===End of Line Report===
The [[Gramps 5.1 Wiki Manual - Reports - part 6#End of Line Report|End of Line Report]] provides a list of of the person's last known ancestors with the pedigree line, ordered by generations.
===Family Group Report===
The [[Gramps 5.1 Wiki Manual - Reports - part 6#Family Group Report|Family Group Report]] creates a family group report, showing information on a set of parents and their children.
===Kinship Report===
[[Gramps 5.1 Wiki Manual - Reports - part 6#Kinship Report|Kinship Report]] provides the kinship of selected person according to level search( height, down generations) set by the user.

===Note Link Report===
The [[Gramps_5.1_Wiki_Manual_-_Reports_-_part_6#Note_Link_Report|Note Link Report]] checks the status of internal Gramps links in notes.

===Number of Ancestors Report===
The [[Gramps 5.1 Wiki Manual - Reports - part 6#Number of Ancestors Report|Number of Ancestors Report]] displays the number of ancestors of the Active Person. The form is - generation x has y individuals (z %).
===Place Report===
The [[Gramps 5.1 Wiki Manual - Reports - part 6#Place Report|Place Report]] produces a report according to places selected by the user. It will list related person and event to the selected place.
===Records Report===
[[Gramps 5.1 Wiki Manual - Reports - part 6#Records Report|Records Report]] shows a number of interesting records(mostly age related) in your database, like oldest living person, youngest mother,etc.
===Tag Report===
The [[Gramps 5.1 Wiki Manual - Reports - part 6#Tag Report|Tag Report]] lists primary objects - persons, families, and notes - who match the selected tag.

= Web Pages =
[[Gramps_5.1_Wiki_Manual_-_Reports_-_part_7#Web_Pages|Web Pages]] for use on your personal website or to give away as a standalone report.
===Narrated Web Site===
One of the reports in this category is the [[Gramps 5.1 Wiki Manual - Reports - part 7#Narrated Web Site|Narrated Web Site report]]. It generates a web site (that is, a set of linked web pages), for a set of selected individuals.
===Web Calendar===
The [[Gramps 5.1 Wiki Manual - Reports - part 7#Web Calendar|Web Calendar]] is a Report that creates webpages showing events for the selected individuals as a set of monthly calendars.
===Dynamic Web Report===
The [[Addon:DynamicWeb_report|Dynamic Web Report]] Addon creates interactive web pages of the family tree database with options allowing a wide range of customization.

This addon is based on the [[Gramps_5.1_Wiki_Manual_-_Reports_-_part_7#Narrated_Web_Site|Narrative Web Report]] native Gramps report.

{{Man warn|This section is a placeholder.|Addons don't belong in this part of the manual. This section was created to compensate for an incorrect address used by the {{man button|[[Addon:DynamicWeb_report#Help_for_the_report_generation|Help]]}} button in the addon and has been corrected as of the [https://github.com/gramps-project/addons-source/commit/c9099d9ee4358658988929efa04b8a40d02db1eb 0.0.82 version] released 3 Jan 2020. The new version links to the actual [[Addon:DynamicWeb_report|webpage for the Dynamic Web Report]]}}


= Quick Views =
[[Gramps_5.1_Wiki_Manual_-_Reports_-_part_8#Quick_Views|Quick Views]] are reports that are available in the context menus of person, family, ... They maybe created by users, even with limited programming knowledge.

{{-}}
{{man index|Gramps 5.1 Wiki Manual - Gramplets|Gramps 5.1 Wiki Manual - Reports - part 1|5.1}}
{{languages|Gramps 5.1 Wiki Manual - Reports}}
{{grampsmanualcopyright}}

[[Category:Documentation]]
[[Category:Plugins]]

Addon:GetGOV

2022-07-24T16:10:29Z

Codefarmer: Link to bugs tagged GetGOV

{{languages|Addon:GetGOV}}
{{Third-party plugin}}
[[File:GetGOV-Gramplet-addon-detached-51.png|300px|right|thumb|GetGOV gramplet]]
The {{man label|GetGOV Gramplet}} is designed to download place information from the [http://gov.genealogy.net/search/index GOV gazetteer]. This information can include

* Geographical location (lat-lon coordinates)
* Foreign and former names
* Past affiliation or hierarchy of enclosed-by places.

Instead of the default [[Gramps_{{Version manual}}_Wiki_Manual_-_Settings#ID_Format|Place ID Format numbering (Pxxxx)]] for the imported places, the GOV-id will be used as the Place ID. If additional imports are performed, duplicate places (even part of the Enclosed By) will be automatically merged.

=Usage=
It is designed to be installed as a gramplet on the [[Gramps_{{Version manual}}_Wiki_Manual_-_Categories#Places_Category|Places Category (List/Tree) view]].
===== Version 5.x =====
The language is set in the {{man menu|Edit -> Preferences..}} tabs {{man label|Display}} and is described in the [[Gramps_{{Version manual}}_Wiki_Manual_-_Settings#Place_Format_Editor|Place Format Editor]]. This is used as the preferred language for place names and types which are imported. The default language is German.

===== Version 4.2 =====
If the {{man menu|Preferences -> Places}} tabs {{man label|Language}} is set, then this is used as the preferred language for place names and types which are imported, otherwise, the preference is German.

{{-}}
== Example ==

This example shows how the gramplet would be used with the GOV gazetteer website to import the place Frommenhausen.

[[File:GOVscreenshot.png|600px|right]]
Log into the [http://gov.genealogy.net/search/index GOV gazetteer] website.
{{-}}

[[File:GOVresults.png|600px|right]]
Find the appropriate GOV-id for the place of interest. In the illustration, the search for the city Frommenhausen was used. The result identifies the appropriate GOV-id as <code>FROSENJN48KK</code>.
{{-}}

[[File:FrommenhausenDetails.png|600px|right]]
To see what data will be imported, you can drill down in to the GOV-id.
{{-}}

[[File:GetGOVgramplet.png|600px|right]]
Enter the GOV-id into the GetGOV gramplet on the Places view.
{{-}}

[[File:GetGOVimport.png|600px|right]]
The resulting places with Latitude and Longitude are loaded. Note that the Place Type is in the same language as the Place. Note that the ID is the GOV-id and not the default <code>Pxxxx</code> numbering. If you use the Reorder Gramps IDs tool, it will change the ID to the default <code>Pxxxx</code> numbering. Later use of this gramplet may import duplicate items (with different ID) since the Gramps ID is no longer the GOV-id and duplicates will not be identified. For instance, if you import <code>FROSENJN48KK</code> and then use the Reorder Gramps ID tool to reset the Gramps ID, if you reimport FROSENJN48KK or any other GOV place that is already imported, you will have duplicate places for every item imported.
{{-}}

[[File:GetGOVresultsaltname.png|600px|right]]
This illustrates that multiple alternate names will be loaded if they are in the GOV database. Deutschland is the Primary name and there are multiple alternate names in different languages in this illustration.
{{-}}
[[File:GetGOVresultsenclosed.png|600px|right]]
The Place hierarchy is also loaded as defined in the GOV database. This includes the Enclosed By information which may be time-dependent as illustrated.
{{-}}

= Issues =
* If you use the Reorder Gramps IDs tool, it will change the ID to the default Pxxx numbering. Later use of this gramplet will import duplicate items (with different ID) since the Gramps ID is no longer the GOV-id and duplicates will not be identified.

= Known Bugs =
* Here's a current list of [https://gramps-project.org/bugs/search.php?project_id=8&sticky=on&sort=last_updated&dir=DESC&hide_status=90&tag_string=GetGOV&match_type=0 open bugs tagged GetGOV] in Mantis Bug Tracker.
* {{bug|11596}} Place format Language setting is not honored unless it is in lower case
* {{bug|10980}} Some places are shown as "?" if imported via getGOV third party addon
* {{bug|10773}} Places view shows all alternate names - even those with different languages
* {{bug|11680}} GetGOV crashes Gramps when GOV gazetteer website ( http://gov.genealogy.net ) is not available

= See also =
* [[Addon:GeoName]] - downloads place information from the GeoNames gazetteer.

[[Category:Plugins]]
[[Category:Addons]]
[[Category:Developers/General]]

Addons development

2022-04-23T22:01:56Z

Codefarmer: Remove stray incomplete sentence

{{man tip|Information on developing Gramps addons|If you are looking for addons to install, visit: [[Third-party Addons]]}}
{{man warn|Note that this article anticipates that most addons will be developed under Linux.|([[Getting started with Gramps development|Linux is the principal development platform.]]) While it is possible to do so under Windows or MacOS, some of the steps will differ and the documented processes have not been as thoroughly reviewed. So developer beware. See [[Portal:Developers]]}}
If you are developing a [[Third-party Addons|Third-party Addon]]; this page documents the API, methods, and best practices for Gramps 4.2 and later.

==What can addons extend?==
Addons for Gramps can extend the program in many different ways. You can add any of the following [https://github.com/gramps-project/gramps/blob/master/gramps/gen/plug/_pluginreg.py types] of addons:

#Report
#Quickreport
#Tool
#Importer
#Exporter
#Doc creator
#Plugin lib
#Map service
#Gramps View
#Relationships
#Gramplet
#Sidebar
#Database (Introduced Gramps 5.x and greater)
#Rule (Introduced Gramps 5.1.x and greater)

==Writing an addon==
Writing an addon is fairly straightforward if you have just a little bit of Python experience. And sharing your addon is the right thing to do. The general steps to writing an addon and sharing your own addons are:

# [[#Develop_your_addon|Develop your addon]]
# [[#Create_a_Gramps_Plugin_Registration_file|Create a Gramps Plugin Registration file (.gpr.py)]]
# [[#internationalization|Invite translation of your addon]] into multiple natural languages
# [[#Package_your_addon|Package your addon]]
# [[#List_and_document_your_addon_on_the_wiki|Document your addon]] and publish it to the addon list
# [[#List_your_addon_in_the_Gramps_Plugin_Manager|Register your addon with the Plugin Manager]]
# [[#Announce_it_on_the_Gramps_mailing_list|Announce it on the Gramps mailing list]] - Let users know it exist and how to use it.
# [[#Support_it_through_issue_tracker|Support it through the issue tracker]]
# [[#Maintain_the_code_as_Gramps_continues_to_evolve|Maintain the code]] as Gramps continues to evolve

We'll now expand upon each of these steps individually.

== Develop your addon ==

The [http://github.com/gramps-project/addons-source addons-source] git repository has the following structure:

* /addons-source
** /''IndividualNameOfAddon1''
** /''IndividualNameOfAddon2''
** ...

The [http://github.com/gramps-project/addons addons] git repository has the following structure:

* /addons
** /gramps42
*** /download
*** /listings
** /gramps50
*** /download
*** /listings
** /gramps51
*** /download
*** /listings

The [http://github.com/gramps-project/addons-source addons-source] repository holds the source code for the addons with branches holding the version for different gramps. If you are working on an addon for gramps for the current Gramps {{man version}} public release, be sure to use the gramps51 git branch, as the default is master branch for the developmental pre-release. (Currently gramps 5.2, which is not the typical target for addons.)

Example commands are shown below referring to the public release rather than the master branch.

The developers are currently merging changes to the most recent maintenance branch into master as necessary, so you don't have to do anything for that unless you are in a hurry.

=== Get a local copy of Gramps and its addons ===

These steps show how to download the addon sources.

# Get an https://github.com/join account if you don't already have one.
# Request GIT write access for the https://github.com/gramps-project/addons-source project by emailing the [[Contact#Mailing_lists|gramps-devel mailing list]]
See also [[Brief_introduction_to_Git|git introduction]] for instructions on installing git and getting basic settings configured. Also [https://help.github.com/articles/generating-an-ssh-key/ Connecting to GitHub with SSH] will help with setting up credentials for GitHub.
To fully build and advertise a new addon will require local copies of the three repositories, the 'addons-source', 'addons' and the main Gramps source 'gramps'.

This wiki assumes that all three git repositories local locations are put into the same base directory and named with the repository names in order for the make.py script commands to work as shown. From the base directory, run the following commands to create a copy of each repository. If you want to use SSH;

git clone git@github.com:gramps-project/addons-source.git addons-source
git clone git@github.com:gramps-project/addons.git addons
git clone git@github.com:gramps-project/gramps.git gramps

or if you want to use a web url:

git clone https://github.com/gramps-project/addons-source.git addons-source
git clone https://github.com/gramps-project/addons.git addons
git clone https://github.com/gramps-project/gramps.git gramps

To switch to a local copy of the gramps51 branch:

cd addons-source
git checkout -b gramps51 origin/maintenance/gramps51

or to work in the master branch:

cd addons-source
git checkout -b gramps52 origin/master

=== Other pre-requisites ===
{{man warn|These instructions, the make.py script etc.|are designed to operate in a Linux environment. {{man menu|They won't work on Windows without modifications.}}}}
* Gramps uses Python version 3.2 or higher. You must have at least that version installed. If you have installed Gramps 4.2 or higher on your Linux system already, then a sufficient version of Python will be present. If you have more than one version of Python installed, then you must use the correct version for these scripts. On some systems, both Python 2.x and 3.x are installed. It is possible that the normal invocation of <code>python</code> starts up Python 2.x, and that to start up Python 3.x requires invoking with <code>python3</code> or <code>python3.4</code> etc. You can test the version by <code>python –version</code> or <code>python3 –version</code>. If this is so, replace any usage of 'python' in the examples below with the appropriate invocation.
* The make.py used in construction of the addons requires that the LANGUAGE environment variable be set to 'en_US.UTF-8'.
* The make.py used in construction of the addons requires that the GRAMPSPATH environment variable be set to your path to the Gramps source tree.
* intltool must be installed;
: <code>sudo apt-get install intltool</code>

For example if your home directory is '/home/name' and you use the suggested path names, use
: <code>GRAMPSPATH=/home/name/gramps LANGUAGE='en_US.UTF-8' python3 make.py ...</code>
to replace the <code>./make.py</code> in the examples below.

=== Create your addon subdirectory ===
* Make a new project directory in addons-source:
: <code>mkdir NewProjectName</code>

===Follow the development API for your tool===
Create your NewProjectName.py and NewProjectName.gpr.py files.

Follow the development API for your tool, [[Report-writing_tutorial|report]], view, or [[Gramplets]]. Place all of your associated .py, .glade, etc. files in this directory. For general information on Gramps development see [[Portal:Developers]] and [[Writing a plugin|Writing a Plugin]] specifically.

=== Test your addon as you develop ===

{{man warn|{{bug|10436}} Symlinks to folders in gramps plugin dir are not scanned}}

To test your addon as you develop it is suggested that you copy your NewProjectName plugin into your Gramps user plugin directory from your addon development directory, prior to testing. Or just edit in the Gramps user plugin directory until it is ready to publish, then copy back to your addon development directory.

Your installed Gramps will search this folder (and subdirectories) for .gpr.py files, and add them to the plugin list.

If you have code that you want to share between addons, you don't need to do anything special. Gramps adds each directory in which a .gpr.py is found onto the PYTHONPATH which is searched when you perform an import. Thus "import NewProjectName" will work from another addon. You should always make sure you name your addons with a name appropriate for Python imports.

=== Commit your changes ===
To commit your changes so that others can see your addon source.

* Remove the files using the ''clean'' command that should not be added to GitHub (eg files(template.pot/ locale etc)):
: <code>./make.py gramps51 clean NewProjectName</code>
* Add the project to the repository:
: <code>git add NewProjectName</code>
* Commit it with an appropriate message
: <code>git commit -m "A message describing what this addon is"</code>

Before committing additional edits to your addon, you should:

* to make sure that outside changes do not affect your commit
: <code>git pull --rebase</code>
* only the files you changed should be in this list
: <code>git status</code>
* Commit it with an appropriate message
: <code>git commit -m "A message describing the changes"</code>

If you have been given 'push' rights to GitHub 'gramps-project/addons-source', and when you are sure you are done and want to publish to the repository:

* to make sure that outside changes do not affect your commit
: <code>git pull --rebase</code>
: <code>git push origin gramps51</code>

Also you may want to [[Addons_development#Package_your_addon |Package your addon]] so it can be downloaded via the plugin manager.

=== Config ===

Some addons may want to have persistent data (data settings that remain between sessions). You can handle this yourself, or you can use Gramps' built-in configure system.

At the top of the source file of your addon, you would do this:

from config import config as configman
config = configman.register_manager("grampletname")
# register the values to save:
config.register("section.option-name1", value1)
config.register("section.option-name2", value2)
...
# load an existing file, if one:
config.load()
# save it, it case it didn't exist:
config.save()

This will create the file "grampletname.ini" and put in the same directory as the addon. If the config file already exists, it remains intact.

In the addon, you can then:

x = config.get("section.option-name1")
config.set("section.option-name1", 3)

and when this code is exiting, you might want to save the config. In a Gramplet that would be:

def on_save(self):
config.save()

If your code is a system-level file, then you might want to save the config in the Gramps system folder:

config = configman.register_manager("system", use_config_path=True)

This, however, would be rare; most .ini files would go into the plugins directory.

In other code that might use this config file, you would do this:

from config import config as configman
config = configman.get_manager("grampletname")
x = config.get("section.option-name1")

=== Localization ===

For general help on translations in Gramps, see [[Coding for translation]]. However, that will only use translations that come with Gramps, or allows you to contribute translations to the Gramps core. To have your own managed translations that will be packaged with your addon, read the rest of this page.
Note that these instructions will only work for Python strings, if you have a glade file, it will not get translated.

For any addon which you have translations into other languages, you will need to add a way to retrieve the translation. You need to add this to the top of your NewProjectName.py file:

from gramps.gen.const import GRAMPS_LOCALE as glocale
_ = glocale.get_addon_translator(__file__).gettext

Then you can use the standard "_()" function to translate phrases in your addon.

You can use one of a few different types of translation functions:

# gettext
# lgettext
# ngettext
# lngettext
# sgettext

These have become obsolete in Gramps 4; gettext, ngettext, and sgettext always return translated strings in unicode for consistent portability between Python 2 and Python3.

See the [http://docs.python.org/3/library/gettext.html#the-gnutranslations-class python documentation] for documentation of gettext and ngettext. The "l" versions return the string encoded according to the [http://docs.python.org/3/library/locale.html#locale.setlocale currently set locale]; the "u" versions return unicode strings in Python2 and are not available in Python 3.

'''sgettext''' is a Gramps extension that filters out clarifying comments for translators, such as
_("Remaining names | rest")
Where "rest" is the English string that we want to present and "Remaining names" is a hint for translators.

==== Commands to compile translations ====

To build and compile translations for all projects to their download/Addon.addon.tgz files:

: <code>python3 make.py gramps51 build all</code>

To compile translations for all projects :

: <code>python3 make.py gramps51 compile all</code>

== Create a Gramps Plugin Registration file ==

First, create the NewProjectName.gpr.py file. The registration takes this general form:

<pre>
register(PTYPE,
gramps_target_version = "5.1",
version = "1.0.0",
ATTR = value,
)
</pre>

[https://github.com/gramps-project/gramps/blob/master/gramps/gen/plug/_pluginreg.py#L76 PTYPE] is TOOL, GRAMPLET, REPORT, QUICKVIEW, IMPORT, EXPORT, DOCGEN, GENERAL, MAPSERVICE, VIEW, or RELCALC.

ATTR depends on the PTYPE. But you must have '''gramps_target_version''' and '''version'''. '''gramps_target_version''' should be a string of the form "X.Y" version number matching Gramps X major, Y minor integer. '''version''' is a string of the form "X.Y.Z" representing the version of your addon. X, Y, and Z should all be integers.

Here is a sample Tool GPR file:

<pre>
register(TOOL,
id = 'AttachSource',
name = _("Attach Source"),
description = _("Attaches a shared source to multiple objects."),
version = '1.0.0',
gramps_target_version = '5.1',
status = STABLE,
fname = 'AttachSourceTool.py',
authors = ["Douglas S. Blank"],
authors_email = ["doug.blank@gmail.com"],
category = TOOL_DBPROC,
toolclass = 'AttachSourceWindow',
optionclass = 'AttachSourceOptions',
tool_modes = [TOOL_MODE_GUI]
)
</pre>

You can see examples of the kinds of addons [https://github.com/gramps-project/gramps/plugins here] (for example, see [https://github.com/gramps-project/gramps/plugins/drawreport/drawplugins.gpr.py gramps/plugins/drawreport/drawplugins.gpr.py]) and see the full documentation [https://github.com/gramps-project/gramps/gen/plug/_pluginreg.py here] in the comments and docstrings.

Note that this .gpr.py will automatically use translations if you have them (see below). That is, the function "_" is predefined to use your locale translations; you only need to mark the text with _("TEXT") and include a translation of "TEXT" in your translation file. For example, in the above example, _("Attach Source") is marked for translation. If you have developed and packaged your addon with translation support, then that phrase will be converted into the user's language.

=== Report plugins ===
The possible report categories are (gen/plug/_pluginreg.py):
<pre>
#possible report categories
CATEGORY_TEXT = 0
CATEGORY_DRAW = 1
CATEGORY_CODE = 2
CATEGORY_WEB = 3
CATEGORY_BOOK = 4
CATEGORY_GRAPHVIZ = 5
REPORT_CAT = [ CATEGORY_TEXT, CATEGORY_DRAW, CATEGORY_CODE,
CATEGORY_WEB, CATEGORY_BOOK, CATEGORY_GRAPHVIZ]
</pre>

Each report category has a set of standards and interface. The categories CATEGORY_TEXT and CATEGORY_DRAW use the Document interface of Gramps. See also [[Report API]] for a draft view on this.

The application programming interface or API for reports is treated at [[Report-writing_tutorial]]. For general information on Gramps development see [[Portal:Developers]] and [[Writing a plugin|Writing a Plugin]] specifically.

=== General plugins ===

The plugin framework also allows you to create generic plugins for use. This includes the ability to create libraries of functions, and plugins of your own design.

==== Example: A library of functions ====

In this example, a file name library.py will be imported at time of registration (when Gramps starts):

<pre>
# file: library.gpr.py

register(GENERAL,
id = 'My Library',
name = _("My Library"),
description = _("Provides a library for doing something."),
version = '1.0',
gramps_target_version = '5.1',
status = STABLE,
fname = 'library.py',
load_on_reg = True,
)
</pre>

The code in the file library.py will be imported when Gramps begins. You can access the loaded module in other code by issuing an "import library" as Python keeps track of files already imported. However, the amount of useful code that you can run when the program is imported is limited. You might like to have the code do something that requires a dbstate or uistate object, and neither of these is available when just importing a file.

If "load_on_reg" was not True, then this code would be unavailable until manually loaded. There is no automatic mechanism in Gramps to load GENERAL plugins automatically.

In addition to importing a file at startup, one can also run a single function inside a GENERAL plugin, and it will be passed the dbstate, the uistate, and the plugin data. The function must be called "load_on_reg", and take those three parameters, like this:

<pre>
# file: library.py

def load_on_reg(dbstate, uistate, plugin):
"""
Runs when plugin is registered.
"""
print("Hello World!")
</pre>

Here, you could connect signals to the dbstate, open windows, etc.

Another example of what one can do with the plugin interface is to create a general purpose plugin framework for use by other plugins. Here is the basis for a plugin system that:

* allows plugins to list data files
* allows the plugin to process all of the data files

First, the gpr.py file:

<pre>

register(GENERAL,
id = "ID",
category = "CATEGORY",
load_on_reg = True,
process = "FUNCTION_NAME",
)
</pre>

This example uses three new features:

# GENERAL plugins can have a category
# GENERAL plugins can have a load_on_reg function that returns data
# GENERAL plugins can have a function (called "process") which will process the data

If you (or someone else) create additional general plugins of this category, and they follow your load_on_reg data format API, then they could be used just like your original data. For example, here is an additional general plugin in the 'WEBSTUFF' category:

<pre>
# anew.gpr.py

register(GENERAL,
id = 'a new plugin',
category = "WEBSTUFF",
version = '1.0',
gramps_target_version = '5.1',
data = ["a", "b", "c"],
)
</pre>

This doesn't have load_on_reg = True, nor does it have a fname or process, but it does set the data directly in the .gpr.py file. Then we have the following results:

<pre>
>>> from gui.pluginmanager import GuiPluginManager
>>> PLUGMAN = GuiPluginManager.get_instance()
>>> PLUGMAN.get_plugin_data('WEBSTUFF')
["a", "b", "c", "Stylesheet.css", "Another.css"]
>>> PLUGMAN.process_plugin_data('WEBSTUFF')
["A", "B", "C", "STYLESHEET.CSS", "ANOTHER.CSS"]
</pre>

=== Registered GENERAL Categories ===

The following are the published secondary plugins API's (type GENERAL, with the following categories):

==== WEBSTUFF ====

A sample gpr.py file:

<pre>
# stylesheet.gpr.py

register(GENERAL,
id = 'system stylesheets',
category = "WEBSTUFF",
name = _("CSS Stylesheets"),
description = _("Provides a collection of stylesheets for the web"),
version = '1.0',
gramps_target_version = '5.1',
fname = "stylesheet.py",
load_on_reg = True,
process = "process_list",
)
</pre>

Here is the associated program:

<pre>
# file: stylesheet.py

def load_on_reg(dbstate, uistate, plugin):
"""
Runs when plugin is registered.
"""
return ["Stylesheet.css", "Another.css"]

def process_list(files):
return [file.upper() for file in files]
</pre>

==== Filters ====

For example:

<pre>
register(GENERAL,
category="Filters",
...
load_on_reg = True
)
</pre>

<pre>
def load_on_reg(dbstate, uistate, plugin):
# returns a function that takes a namespace, 'Person', 'Family', etc.

def filters(namespace):
print("Ok...", plugin.category, namespace, uistate)
# return a Filter object here
return filters
</pre>


== Get translators to translate your addon into multiple languages ==

If you [[#Localization|designed for localization]], the addon will begin supporting a single language. Make your addon inviting for volunteers to translate it into their native language.
* Initialize and update the <code>template.pot</code> for your addon:
: <code>cd ~/addons-source</code>
: <code>./make.py gramps51 init NewProjectName</code>
* You should edit the header of <code>template.pot</code> with your information, so it gets copied to individual language files.
* Initialize a language for your addon (say French, fr):
: <code>./make.py gramps51 init NewProjectName fr</code>
* Update it from gramps and other addons:
: <code>./make.py gramps51 update NewProjectName fr</code>
* Edit the translations file manually:
: <code>/NewProjectName/po/fr-local.po</code>
* Compile the language:
: <code>./make.py gramps51 compile NewProjectName</code>
* Add or update your local language file, and commit changes:
: <code>git add NewProjectName/po/fr-local.po</code>
: <code>git commit NewProjectName/po/fr-local.po -m "Added fr po file"</code>
* If you have been given 'push' rights to GitHub 'gramps-project/addons-source', then;
: <code>git push origin gramps51</code>

== Package your addon ==

To create a downloadable package:

: <code>./make.py gramps51 build NewProjectName</code> or
: <code>./make.py gramps52 build NewProjectName</code> for the master branch.

This will automatically include the following files in your build:

* *.py
* *.glade
* *.xml
* *.txt
* locale/*/LC_MESSAGES/*.mo

Starting with Gramp 5.0, if you have additional files beyond those listed above, you should create a MANIFEST file in the root of your addon folder listing the files (or pattern) one per line, like this sample MANIFEST file:

<pre>
README.md
extra_dir/*
help_files/docs/help.html
</pre>

{{man note|Note:|Running the command <code>make.py xxx build</code> will increment the third number in your dotted version number of all addons in the <code>*.gpr.py</code> file. Consider this number to be a "build number".}}

This will leave your 'addons-source' with untracked changes according to git. You should delete the 'NewProjectName/locale' directory. The updated 'NewProjectName/NewProjectName.gpr.py ' is ready to add and commit the next time you make other changes.
: <code>rm –rf –v 'NewProjectName/locale'</code>

Then add the package to GitHub:

<pre> cd '~/addons'
git add gramps51/download/NewProjectName.addon.tgz
git commit -m "Added new plugin: NewProjectName"</pre>
or (for the master branch);
<pre> cd '~/addons'
git add gramps52/download/NewProjectName.addon.tgz
git commit -m " Added new plugin: NewProjectName"</pre>

== List your addon in the Gramps Plugin Manager==

{{man warn|Gramps needs to have been built|Make sure you have already built gramps51 or master. Change to the appropriate git branch in your gramps directory, and run <code>python3 setup.py build</code> See [[Linux:Build_from_source]]}}

To create a listing:

: <code>cd '~/gramps-addons'</code> or wherever you have built your addon
: <code>GRAMPSPATH=path/to/your/gramps/install ./make.py gramps51 listing NewProjectName</code>
or (for the master branch);
: <code>cd '~/gramps-addons'</code> or wherever you have built your addon
: <code>GRAMPSPATH=path/to/your/gramps/install ./make.py gramps52 listing NewProjectName</code>

That will create a series of files in the <tt>../listings/</tt> directory.

Then add the updated listing to GitHub:

<pre> cd '~/addons'
git add gramps51/listings/*
git commit -m "Added new plugin to listings: NewProjectName"</pre>
or (for the master branch);
<pre> cd '~/addons'
git add gramps52/listings/*
git commit -m " Added new plugin to listings: NewProjectName"</pre>

== List and document your addon on the wiki==

===List your addon===
Add a short description of your addon to the Addons list by editing the current release listing eg: [[5.1_Addons]] or if the addon is meant for a future release [[5.2_Addons]] when available.

==== Example addon template ====
Examine the listing for other addons and refer to the [[Addon list legend]] for details of on the meaning of each columns.
<pre>
|- 
|
|
|
|
|
|
|
|
|-
</pre>

===Document your addon===
Document the addon in the wiki using the page name format of {{man menu|Addon:NewProjectName}} examine the other addon support pages for the general format to use.
{{man tip|Hint on creating a new wiki page.|To create a new wiki page use the search box to search for the name of your page that doesn't exist then on the search results page you will be provided with a link to create the new page, by selecting and you can add your content}}

====Example addon article====
Consider including the following information:

<pre>

{{Third-party plugin}}


== Usage ==

=== Configure Options ===

==Features==

== Prerequisites ==

== Issues ==


[[Category:Addons]]
[[Category:Plugins]]
[[Category:Developers/General]]
</pre>

== Announce it on the Gramps mailing list ==
Join the [[Contact#Mailing_lists|Gramps Mailing lists]] and announce it to the users with general information on why you created and how to use it.

== Support it through issue tracker ==

Become a user on the [https://gramps-project.org/bugs/view_all_bug_page.php Gramps MantisBT (Mantis BugTracker)].
and please check it regularly. There is no automated notification of issues (and possible feature requests) related to your addon when reported by users.

Users tend to not understand coding and they make assumptions. So be kind and guiding if a report is ambiguous or inaccurate. A negative remark from an addon developer or anyone can be very discouraging.

== Maintain the code as Gramps continues to evolve ==

Remember that Gramps addons exist for many reasons and there are many
Gramps developers that do support addons in various ways (translations,
triage, keeping in sync with master, download infrastructure, etc).

Some reasons why the addons exist; they provide:
* A quick way for anyone to share their work; the Gramps-project has never denied adding a addon.
* A method to continuously update and develop a stand-alone component, often before being officially accepted.
* A place for controversial plugins that will never be accepted into core, but are loved by many users (eg, Data Entry Gramplet).
* A place for experimental components to live.
== Example code adding common enhancements ==
* Copy all the Gramplet's output to a system clipboard via context pop-up menu : Enhancement request {{bug|11573}}, [https://github.com/gramps-project/gramps/pull/1014/commits/72012e13b4ca15caca4b7f36fdb9702c1fd470fd example pull]
* add a custom [[Gramps_Glossary#viewmode|View Mode]] toolbar icon via the <code>.gpr.py</code> : [https://github.com/gramps-project/gramps/pull/1017 Pull 1017 Discussion], [https://github.com/gramps-project/gramps/pull/1017/commits/76e41d546d6ec519dd78fbe07f663135b5c79351 example Pull]

= Resources =
* [[Brief_introduction_to_Git|Git introduction]]
* [[Getting started with Gramps development]]
* [[Portal:Developers]]
* [https://gramps-project.org/docs/gen/gen_plug.html?highlight=include_in_listing#module-gramps.gen.plug._pluginreg Registration Module]

;Gramps Addons site for Gramps 4.2 and newer
* https://github.com/gramps-project/addons-source - Source code (Git)
* https://github.com/gramps-project/addons - downloadable .tgz files
;Gramps Addons site for Gramps 4.1 and older
* For 4.1.x and earlier, see [[Addons development old]].

[[Category:Developers/General]]
[[Category:Developers/Tutorials]]
[[Category:Plugins]]
[[Category:Reports]]
[[Category:Gramplets]]
[[Category:Addons]]

Addons development

2022-04-23T21:56:42Z

Codefarmer: Using home directory isn't really required; clear up conflicting text in favor of 'base directory' terminology

{{man tip|Information on developing Gramps addons|If you are looking for addons to install, visit: [[Third-party Addons]]}}
{{man warn|Note that this article anticipates that most addons will be developed under Linux.|([[Getting started with Gramps development|Linux is the principal development platform.]]) While it is possible to do so under Windows or MacOS, some of the steps will differ and the documented processes have not been as thoroughly reviewed. So developer beware. See [[Portal:Developers]]}}
If you are developing a [[Third-party Addons|Third-party Addon]]; this page documents the API, methods, and best practices for Gramps 4.2 and later.

==What can addons extend?==
Addons for Gramps can extend the program in many different ways. You can add any of the following [https://github.com/gramps-project/gramps/blob/master/gramps/gen/plug/_pluginreg.py types] of addons:

#Report
#Quickreport
#Tool
#Importer
#Exporter
#Doc creator
#Plugin lib
#Map service
#Gramps View
#Relationships
#Gramplet
#Sidebar
#Database (Introduced Gramps 5.x and greater)
#Rule (Introduced Gramps 5.1.x and greater)

==Writing an addon==
Writing an addon is fairly straightforward if you have just a little bit of Python experience. And sharing your addon is the right thing to do. The general steps to writing an addon and sharing your own addons are:

# [[#Develop_your_addon|Develop your addon]]
# [[#Create_a_Gramps_Plugin_Registration_file|Create a Gramps Plugin Registration file (.gpr.py)]]
# [[#internationalization|Invite translation of your addon]] into multiple natural languages
# [[#Package_your_addon|Package your addon]]
# [[#List_and_document_your_addon_on_the_wiki|Document your addon]] and publish it to the addon list
# [[#List_your_addon_in_the_Gramps_Plugin_Manager|Register your addon with the Plugin Manager]]
# [[#Announce_it_on_the_Gramps_mailing_list|Announce it on the Gramps mailing list]] - Let users know it exist and how to use it.
# [[#Support_it_through_issue_tracker|Support it through the issue tracker]]
# [[#Maintain_the_code_as_Gramps_continues_to_evolve|Maintain the code]] as Gramps continues to evolve

We'll now expand upon each of these steps individually.

== Develop your addon ==

The [http://github.com/gramps-project/addons-source addons-source] git repository has the following structure:

* /addons-source
** /''IndividualNameOfAddon1''
** /''IndividualNameOfAddon2''
** ...

The [http://github.com/gramps-project/addons addons] git repository has the following structure:

* /addons
** /gramps42
*** /download
*** /listings
** /gramps50
*** /download
*** /listings
** /gramps51
*** /download
*** /listings

The [http://github.com/gramps-project/addons-source addons-source] repository holds the source code for the addons with branches holding the version for different gramps. If you are working on an addon for gramps for the current Gramps {{man version}} public release, be sure to use the gramps51 git branch, as the default is master branch for the developmental pre-release. (Currently gramps 5.2, which is not the typical target for addons.)

Example commands are shown below referring to the public release rather than the master branch.

The developers are currently merging changes to the most recent maintenance branch into master as necessary, so you don't have to do anything for that unless you are in a hurry.

=== Get a local copy of Gramps and its addons ===

These steps show how to download the addon sources.

# Get an https://github.com/join account if you don't already have one.
# Request GIT write access for the https://github.com/gramps-project/addons-source project by emailing the [[Contact#Mailing_lists|gramps-devel mailing list]]
See also [[Brief_introduction_to_Git|git introduction]] for instructions on installing git and getting basic settings configured. Also [https://help.github.com/articles/generating-an-ssh-key/ Connecting to GitHub with SSH] will help with setting up credentials for GitHub.
To fully build and advertise a new addon will require local copies of the three repositories, the 'addons-source', 'addons' and the main Gramps source 'gramps'.

This wiki assumes that all three git repositories local locations are put into the same base directory and named with the repository names in order for the make.py script commands to work as shown. From the base directory, run the following commands to create a copy of each repository. If you want to use SSH;

git clone git@github.com:gramps-project/addons-source.git addons-source
git clone git@github.com:gramps-project/addons.git addons
git clone git@github.com:gramps-project/gramps.git gramps

or if you want to use a web url:

git clone https://github.com/gramps-project/addons-source.git addons-source
git clone https://github.com/gramps-project/addons.git addons
git clone https://github.com/gramps-project/gramps.git gramps

To switch to a local copy of the gramps51 branch:

cd addons-source
git checkout -b gramps51 origin/maintenance/gramps51

or to work in the master branch:

cd addons-source
git checkout -b gramps52 origin/master

=== Other pre-requisites ===
{{man warn|These instructions, the make.py script etc.|are designed to operate in a Linux environment. {{man menu|They won't work on Windows without modifications.}}}}
* Gramps uses Python version 3.2 or higher. You must have at least that version installed. If you have installed Gramps 4.2 or higher on your Linux system already, then a sufficient version of Python will be present. If you have more than one version of Python installed, then you must use the correct version for these scripts. On some systems, both Python 2.x and 3.x are installed. It is possible that the normal invocation of <code>python</code> starts up Python 2.x, and that to start up Python 3.x requires invoking with <code>python3</code> or <code>python3.4</code> etc. You can test the version by <code>python –version</code> or <code>python3 –version</code>. If this is so, replace any usage of 'python' in the examples below with the appropriate invocation.
* The make.py used in construction of the addons requires that the LANGUAGE environment variable be set to 'en_US.UTF-8'.
* The make.py used in construction of the addons requires that the GRAMPSPATH environment variable be set to your path to the Gramps source tree.
* intltool must be installed;
: <code>sudo apt-get install intltool</code>

For example if your home directory is '/home/name' and you use the suggested path names, use
: <code>GRAMPSPATH=/home/name/gramps LANGUAGE='en_US.UTF-8' python3 make.py ...</code>
to replace the <code>./make.py</code> in the examples below.

=== Create your addon subdirectory ===
* Make a new project directory in addons-source:
: <code>mkdir NewProjectName</code>

===Follow the development API for your tool===
Create your NewProjectName.py and NewProjectName.gpr.py files.

Follow the development API for your tool, [[Report-writing_tutorial|report]], view, or [[Gramplets]]. Place all of your associated .py, .glade, etc. files in this directory. For general information on Gramps development see [[Portal:Developers]] and [[Writing a plugin|Writing a Plugin]] specifically.

=== Test your addon as you develop ===

{{man warn|{{bug|10436}} Symlinks to folders in gramps plugin dir are not scanned}}

To test your addon as you develop it is suggested that you copy your NewProjectName plugin into your Gramps user plugin directory from your addon development directory, prior to testing. Or just edit in the Gramps user plugin directory until it is ready to publish, then copy back to your addon development directory.

Your installed Gramps will search this folder (and subdirectories) for .gpr.py files, and add them to the plugin list.

If you have code that you want to share between addons, you don't need to do anything special. Gramps adds each directory in which a .gpr.py is found onto the PYTHONPATH which is searched when you perform an import. Thus "import NewProjectName" will work from another addon. You should always make sure you name your addons with a name appropriate for Python imports.

=== Commit your changes ===
To commit your changes so that others can see your addon source.

* Remove the files using the ''clean'' command that should not be added to GitHub (eg files(template.pot/ locale etc)):
: <code>./make.py gramps51 clean NewProjectName</code>
* Add the project to the repository:
: <code>git add NewProjectName</code>
* Commit it with an appropriate message
: <code>git commit -m "A message describing what this addon is"</code>

Before committing additional edits to your addon, you should:

* to make sure that outside changes do not affect your commit
: <code>git pull --rebase</code>
* only the files you changed should be in this list
: <code>git status</code>
* Commit it with an appropriate message
: <code>git commit -m "A message describing the changes"</code>

If you have been given 'push' rights to GitHub 'gramps-project/addons-source', and when you are sure you are done and want to publish to the repository:

* to make sure that outside changes do not affect your commit
: <code>git pull --rebase</code>
: <code>git push origin gramps51</code>

Also you may want to [[Addons_development#Package_your_addon |Package your addon]] so it can be downloaded via the plugin manager.

=== Config ===

Some addons may want to have persistent data (data settings that remain between sessions). You can handle this yourself, or you can use Gramps' built-in configure system.

At the top of the source file of your addon, you would do this:

from config import config as configman
config = configman.register_manager("grampletname")
# register the values to save:
config.register("section.option-name1", value1)
config.register("section.option-name2", value2)
...
# load an existing file, if one:
config.load()
# save it, it case it didn't exist:
config.save()

This will create the file "grampletname.ini" and put in the same directory as the addon. If the config file already exists, it remains intact.

In the addon, you can then:

x = config.get("section.option-name1")
config.set("section.option-name1", 3)

and when this code is exiting, you might want to save the config. In a Gramplet that would be:

def on_save(self):
config.save()

If your code is a system-level file, then you might want to save the config in the Gramps system folder:

config = configman.register_manager("system", use_config_path=True)

This, however, would be rare; most .ini files would go into the plugins directory.

In other code that might use this config file, you would do this:

from config import config as configman
config = configman.get_manager("grampletname")
x = config.get("section.option-name1")

=== Localization ===

For general help on translations in Gramps, see [[Coding for translation]]. However, that will only use translations that come with Gramps, or allows you to contribute translations to the Gramps core. To have your own managed translations that will be packaged with your addon, read the rest of this page.
Note that these instructions will only work for Python strings, if you have a glade file, it will not get translated.

For any addon which you have translations into other languages, you will need to add a way to retrieve the translation. You need to add this to the top of your NewProjectName.py file:

from gramps.gen.const import GRAMPS_LOCALE as glocale
_ = glocale.get_addon_translator(__file__).gettext

Then you can use the standard "_()" function to translate phrases in your addon.

You can use one of a few different types of translation functions:

# gettext
# lgettext
# ngettext
# lngettext
# sgettext

These have become obsolete in Gramps 4; gettext, ngettext, and sgettext always return translated strings in unicode for consistent portability between Python 2 and Python3.

See the [http://docs.python.org/3/library/gettext.html#the-gnutranslations-class python documentation] for documentation of gettext and ngettext. The "l" versions return the string encoded according to the [http://docs.python.org/3/library/locale.html#locale.setlocale currently set locale]; the "u" versions return unicode strings in Python2 and are not available in Python 3.

'''sgettext''' is a Gramps extension that filters out clarifying comments for translators, such as
_("Remaining names | rest")
Where "rest" is the English string that we want to present and "Remaining names" is a hint for translators.

==== Commands to compile translations ====

To build and compile translations for all projects to their download/Addon.addon.tgz files:

: <code>python3 make.py gramps51 build all</code>

To compile translations for all projects :

: <code>python3 make.py gramps51 compile all</code>

== Create a Gramps Plugin Registration file ==

First, create the NewProjectName.gpr.py file. The registration takes this general form:

<pre>
register(PTYPE,
gramps_target_version = "5.1",
version = "1.0.0",
ATTR = value,
)
</pre>

[https://github.com/gramps-project/gramps/blob/master/gramps/gen/plug/_pluginreg.py#L76 PTYPE] is TOOL, GRAMPLET, REPORT, QUICKVIEW, IMPORT, EXPORT, DOCGEN, GENERAL, MAPSERVICE, VIEW, or RELCALC.

ATTR depends on the PTYPE. But you must have '''gramps_target_version''' and '''version'''. '''gramps_target_version''' should be a string of the form "X.Y" version number matching Gramps X major, Y minor integer. '''version''' is a string of the form "X.Y.Z" representing the version of your addon. X, Y, and Z should all be integers.

Here is a sample Tool GPR file:

<pre>
register(TOOL,
id = 'AttachSource',
name = _("Attach Source"),
description = _("Attaches a shared source to multiple objects."),
version = '1.0.0',
gramps_target_version = '5.1',
status = STABLE,
fname = 'AttachSourceTool.py',
authors = ["Douglas S. Blank"],
authors_email = ["doug.blank@gmail.com"],
category = TOOL_DBPROC,
toolclass = 'AttachSourceWindow',
optionclass = 'AttachSourceOptions',
tool_modes = [TOOL_MODE_GUI]
)
</pre>

You can see examples of the kinds of addons [https://github.com/gramps-project/gramps/plugins here] (for example, see [https://github.com/gramps-project/gramps/plugins/drawreport/drawplugins.gpr.py gramps/plugins/drawreport/drawplugins.gpr.py]) and see the full documentation [https://github.com/gramps-project/gramps/gen/plug/_pluginreg.py here] in the comments and docstrings.

Note that this .gpr.py will automatically use translations if you have them (see below). That is, the function "_" is predefined to use your locale translations; you only need to mark the text with _("TEXT") and include a translation of "TEXT" in your translation file. For example, in the above example, _("Attach Source") is marked for translation. If you have developed and packaged your addon with translation support, then that phrase will be converted into the user's language.

=== Report plugins ===
The possible report categories are (gen/plug/_pluginreg.py):
<pre>
#possible report categories
CATEGORY_TEXT = 0
CATEGORY_DRAW = 1
CATEGORY_CODE = 2
CATEGORY_WEB = 3
CATEGORY_BOOK = 4
CATEGORY_GRAPHVIZ = 5
REPORT_CAT = [ CATEGORY_TEXT, CATEGORY_DRAW, CATEGORY_CODE,
CATEGORY_WEB, CATEGORY_BOOK, CATEGORY_GRAPHVIZ]
</pre>

Each report category has a set of standards and interface. The categories CATEGORY_TEXT and CATEGORY_DRAW use the Document interface of Gramps. See also [[Report API]] for a draft view on this.

The application programming interface or API for reports is treated at [[Report-writing_tutorial]]. For general information on Gramps development see [[Portal:Developers]] and [[Writing a plugin|Writing a Plugin]] specifically.

=== General plugins ===

The plugin framework also allows you to create generic plugins for use. This includes the ability to create libraries of functions, and plugins of your own design.

==== Example: A library of functions ====

In this example, a file name library.py will be imported at time of registration (when Gramps starts):

<pre>
# file: library.gpr.py

register(GENERAL,
id = 'My Library',
name = _("My Library"),
description = _("Provides a library for doing something."),
version = '1.0',
gramps_target_version = '5.1',
status = STABLE,
fname = 'library.py',
load_on_reg = True,
)
</pre>

The code in the file library.py will be imported when Gramps begins. You can access the loaded module in other code by issuing an "import library" as Python keeps track of files already imported. However, the amount of useful code that you can run when the program is imported is limited. You might like to have the code do something that requires a dbstate or uistate object, and neither of these is available when just importing a file.

If "load_on_reg" was not True, then this code would be unavailable until manually loaded. There is no automatic mechanism in Gramps to load GENERAL plugins automatically.

In addition to importing a file at startup, one can also run a single function inside a GENERAL plugin, and it will be passed the dbstate, the uistate, and the plugin data. The function must be called "load_on_reg", and take those three parameters, like this:

<pre>
# file: library.py

def load_on_reg(dbstate, uistate, plugin):
"""
Runs when plugin is registered.
"""
print("Hello World!")
</pre>

Here, you could connect signals to the dbstate, open windows, etc.

Another example of what one can do with the plugin interface is to create a general purpose plugin framework for use by other plugins. Here is the basis for a plugin system that:

* allows plugins to list data files
* allows the plugin to process all of the data files

First, the gpr.py file:

<pre>

register(GENERAL,
id = "ID",
category = "CATEGORY",
load_on_reg = True,
process = "FUNCTION_NAME",
)
</pre>

This example uses three new features:

# GENERAL plugins can have a category
# GENERAL plugins can have a load_on_reg function that returns data
# GENERAL plugins can have a function (called "process") which will process the data

If you (or someone else) create additional general plugins of this category, and they follow your load_on_reg data format API, then they could be used just like your original data. For example, here is an additional general plugin in the 'WEBSTUFF' category:

<pre>
# anew.gpr.py

register(GENERAL,
id = 'a new plugin',
category = "WEBSTUFF",
version = '1.0',
gramps_target_version = '5.1',
data = ["a", "b", "c"],
)
</pre>

This doesn't have load_on_reg = True, nor does it have a fname or process, but it does set the data directly in the .gpr.py file. Then we have the following results:

<pre>
>>> from gui.pluginmanager import GuiPluginManager
>>> PLUGMAN = GuiPluginManager.get_instance()
>>> PLUGMAN.get_plugin_data('WEBSTUFF')
["a", "b", "c", "Stylesheet.css", "Another.css"]
>>> PLUGMAN.process_plugin_data('WEBSTUFF')
["A", "B", "C", "STYLESHEET.CSS", "ANOTHER.CSS"]
</pre>

=== Registered GENERAL Categories ===

The following are the published secondary plugins API's (type GENERAL, with the following categories):

==== WEBSTUFF ====

A sample gpr.py file:

<pre>
# stylesheet.gpr.py

register(GENERAL,
id = 'system stylesheets',
category = "WEBSTUFF",
name = _("CSS Stylesheets"),
description = _("Provides a collection of stylesheets for the web"),
version = '1.0',
gramps_target_version = '5.1',
fname = "stylesheet.py",
load_on_reg = True,
process = "process_list",
)
</pre>

Here is the associated program:

<pre>
# file: stylesheet.py

def load_on_reg(dbstate, uistate, plugin):
"""
Runs when plugin is registered.
"""
return ["Stylesheet.css", "Another.css"]

def process_list(files):
return [file.upper() for file in files]
</pre>

==== Filters ====

For example:

<pre>
register(GENERAL,
category="Filters",
...
load_on_reg = True
)
</pre>

<pre>
def load_on_reg(dbstate, uistate, plugin):
# returns a function that takes a namespace, 'Person', 'Family', etc.

def filters(namespace):
print("Ok...", plugin.category, namespace, uistate)
# return a Filter object here
return filters
</pre>


== Get translators to translate your addon into multiple languages ==

If you [[#Localization|designed for localization]], the addon will begin supporting a single language. Make your addon inviting for volunteers to translate it into their native language.
* Initialize and update the <code>template.pot</code> for your addon:
: <code>cd ~/addons-source</code>
: <code>./make.py gramps51 init NewProjectName</code>
* You should edit the header of <code>template.pot</code> with your information, so it gets copied to individual language files.
* Initialize a language for your addon (say French, fr):
: <code>./make.py gramps51 init NewProjectName fr</code>
* Update it from gramps and other addons:
: <code>./make.py gramps51 update NewProjectName fr</code>
* Edit the translations file manually:
: <code>/NewProjectName/po/fr-local.po</code>
* Compile the language:
: <code>./make.py gramps51 compile NewProjectName</code>
* Add or update your local language file, and commit changes:
: <code>git add NewProjectName/po/fr-local.po</code>
: <code>git commit NewProjectName/po/fr-local.po -m "Added fr po file"</code>
* If you have been given 'push' rights to GitHub 'gramps-project/addons-source', then;
: <code>git push origin gramps51</code>

== Package your addon ==

To create a downloadable package:

: <code>./make.py gramps51 build NewProjectName</code> or
: <code>./make.py gramps52 build NewProjectName</code> for the master branch.

Note that the

This will automatically include the following files in your build:

* *.py
* *.glade
* *.xml
* *.txt
* locale/*/LC_MESSAGES/*.mo

Starting with Gramp 5.0, if you have additional files beyond those listed above, you should create a MANIFEST file in the root of your addon folder listing the files (or pattern) one per line, like this sample MANIFEST file:

<pre>
README.md
extra_dir/*
help_files/docs/help.html
</pre>

{{man note|Note:|Running the command <code>make.py xxx build</code> will increment the third number in your dotted version number of all addons in the <code>*.gpr.py</code> file. Consider this number to be a "build number".}}

This will leave your 'addons-source' with untracked changes according to git. You should delete the 'NewProjectName/locale' directory. The updated 'NewProjectName/NewProjectName.gpr.py ' is ready to add and commit the next time you make other changes.
: <code>rm –rf –v 'NewProjectName/locale'</code>

Then add the package to GitHub:

<pre> cd '~/addons'
git add gramps51/download/NewProjectName.addon.tgz
git commit -m "Added new plugin: NewProjectName"</pre>
or (for the master branch);
<pre> cd '~/addons'
git add gramps52/download/NewProjectName.addon.tgz
git commit -m " Added new plugin: NewProjectName"</pre>

== List your addon in the Gramps Plugin Manager==

{{man warn|Gramps needs to have been built|Make sure you have already built gramps51 or master. Change to the appropriate git branch in your gramps directory, and run <code>python3 setup.py build</code> See [[Linux:Build_from_source]]}}

To create a listing:

: <code>cd '~/gramps-addons'</code> or wherever you have built your addon
: <code>GRAMPSPATH=path/to/your/gramps/install ./make.py gramps51 listing NewProjectName</code>
or (for the master branch);
: <code>cd '~/gramps-addons'</code> or wherever you have built your addon
: <code>GRAMPSPATH=path/to/your/gramps/install ./make.py gramps52 listing NewProjectName</code>

That will create a series of files in the <tt>../listings/</tt> directory.

Then add the updated listing to GitHub:

<pre> cd '~/addons'
git add gramps51/listings/*
git commit -m "Added new plugin to listings: NewProjectName"</pre>
or (for the master branch);
<pre> cd '~/addons'
git add gramps52/listings/*
git commit -m " Added new plugin to listings: NewProjectName"</pre>

== List and document your addon on the wiki==

===List your addon===
Add a short description of your addon to the Addons list by editing the current release listing eg: [[5.1_Addons]] or if the addon is meant for a future release [[5.2_Addons]] when available.

==== Example addon template ====
Examine the listing for other addons and refer to the [[Addon list legend]] for details of on the meaning of each columns.
<pre>
|- 
|
|
|
|
|
|
|
|
|-
</pre>

===Document your addon===
Document the addon in the wiki using the page name format of {{man menu|Addon:NewProjectName}} examine the other addon support pages for the general format to use.
{{man tip|Hint on creating a new wiki page.|To create a new wiki page use the search box to search for the name of your page that doesn't exist then on the search results page you will be provided with a link to create the new page, by selecting and you can add your content}}

====Example addon article====
Consider including the following information:

<pre>

{{Third-party plugin}}


== Usage ==

=== Configure Options ===

==Features==

== Prerequisites ==

== Issues ==


[[Category:Addons]]
[[Category:Plugins]]
[[Category:Developers/General]]
</pre>

== Announce it on the Gramps mailing list ==
Join the [[Contact#Mailing_lists|Gramps Mailing lists]] and announce it to the users with general information on why you created and how to use it.

== Support it through issue tracker ==

Become a user on the [https://gramps-project.org/bugs/view_all_bug_page.php Gramps MantisBT (Mantis BugTracker)].
and please check it regularly. There is no automated notification of issues (and possible feature requests) related to your addon when reported by users.

Users tend to not understand coding and they make assumptions. So be kind and guiding if a report is ambiguous or inaccurate. A negative remark from an addon developer or anyone can be very discouraging.

== Maintain the code as Gramps continues to evolve ==

Remember that Gramps addons exist for many reasons and there are many
Gramps developers that do support addons in various ways (translations,
triage, keeping in sync with master, download infrastructure, etc).

Some reasons why the addons exist; they provide:
* A quick way for anyone to share their work; the Gramps-project has never denied adding a addon.
* A method to continuously update and develop a stand-alone component, often before being officially accepted.
* A place for controversial plugins that will never be accepted into core, but are loved by many users (eg, Data Entry Gramplet).
* A place for experimental components to live.
== Example code adding common enhancements ==
* Copy all the Gramplet's output to a system clipboard via context pop-up menu : Enhancement request {{bug|11573}}, [https://github.com/gramps-project/gramps/pull/1014/commits/72012e13b4ca15caca4b7f36fdb9702c1fd470fd example pull]
* add a custom [[Gramps_Glossary#viewmode|View Mode]] toolbar icon via the <code>.gpr.py</code> : [https://github.com/gramps-project/gramps/pull/1017 Pull 1017 Discussion], [https://github.com/gramps-project/gramps/pull/1017/commits/76e41d546d6ec519dd78fbe07f663135b5c79351 example Pull]

= Resources =
* [[Brief_introduction_to_Git|Git introduction]]
* [[Getting started with Gramps development]]
* [[Portal:Developers]]
* [https://gramps-project.org/docs/gen/gen_plug.html?highlight=include_in_listing#module-gramps.gen.plug._pluginreg Registration Module]

;Gramps Addons site for Gramps 4.2 and newer
* https://github.com/gramps-project/addons-source - Source code (Git)
* https://github.com/gramps-project/addons - downloadable .tgz files
;Gramps Addons site for Gramps 4.1 and older
* For 4.1.x and earlier, see [[Addons development old]].

[[Category:Developers/General]]
[[Category:Developers/Tutorials]]
[[Category:Plugins]]
[[Category:Reports]]
[[Category:Gramplets]]
[[Category:Addons]]

Addons development

2022-02-25T02:35:28Z

Codefarmer: Link to addons-source GitHub repo

{{man tip|Information on developing Gramps addons|If you are looking for addons to install, visit: [[Third-party Addons]]}}
{{man warn|Note that this article anticipates that most addons will be developed under Linux.|([[Getting started with Gramps development|Linux is the principal development platform.]]) While it is possible to do so under Windows or MacOS, some of the steps will differ and the documented processes have not been as thoroughly reviewed. So developer beware. See [[Portal:Developers]]}}
If you are developing a [[Third-party Addons|Third-party Addon]]; this page documents the API, methods, and best practices for Gramps 4.2 and later.

==What can addons extend?==
Addons for Gramps can extend the program in many different ways. You can add any of the following [https://github.com/gramps-project/gramps/blob/master/gramps/gen/plug/_pluginreg.py types] of addons:

#Report
#Quickreport
#Tool
#Importer
#Exporter
#Doc creator
#Plugin lib
#Map service
#Gramps View
#Relationships
#Gramplet
#Sidebar
#Database (Introduced Gramps 5.x and greater)
#Rule (Introduced Gramps 5.1.x and greater)

==Writing an addon==
Writing an addon is fairly straightforward if you have just a little bit of Python experience. And sharing your addon is the right thing to do. The general steps to writing an addon and sharing your own addons are:

# [[#Develop_your_addon|Develop your addon]]
# [[#Create_a_Gramps_Plugin_Registration_file|Create a Gramps Plugin Registration file (.gpr.py)]]
# [[#internationalization|Invite translation of your addon]] into multiple natural languages
# [[#Package_your_addon|Package your addon]]
# [[#List_and_document_your_addon_on_the_wiki|Document your addon]] and publish it to the addon list
# [[#List_your_addon_in_the_Gramps_Plugin_Manager|Register your addon with the Plugin Manager]]
# [[#Announce_it_on_the_Gramps_mailing_list|Announce it on the Gramps mailing list]] - Let users know it exist and how to use it.
# [[#Support_it_through_issue_tracker|Support it through the issue tracker]]
# [[#Maintain_the_code_as_Gramps_continues_to_evolve|Maintain the code]] as Gramps continues to evolve

We'll now expand upon each of these steps individually.

== Develop your addon ==

The [http://github.com/gramps-project/addons-source addons-source] git repository has the following structure:

* /addons-source
** /''IndividualNameOfAddon1''
** /''IndividualNameOfAddon2''
** ...

The [http://github.com/gramps-project/addons add-ons] git repository has the following structure:

* /addons
** /gramps42
*** /download
*** /listings
** /gramps50
*** /download
*** /listings
** /gramps51
*** /download
*** /listings

The [http://github.com/gramps-project/addons-source addons-source] repository holds the source code for the addons with branches holding the version for different gramps. If you are working on an addon for gramps for the current Gramps {{man version}} public release, be sure to use the gramps51 git branch, as the default is master branch for the developmental pre-release. (Currently gramps 5.2, which is not the typical target for addons.)

Example commands are shown below referring to the public release rather than the master branch.

The developers are currently merging changes to the most recent maintenance branch into master as necessary, so you don't have to do anything for that unless you are in a hurry.

=== Get a local copy of Gramps and its addons ===

These steps show how to download the addon sources.

# Get an https://github.com/join account if you don't already have one.
# Request GIT write access for the https://github.com/gramps-project/addons-source project by emailing the [[Contact#Mailing_lists|gramps-devel mailing list]]
See also [[Brief_introduction_to_Git|git introduction]] for instructions on installing git and getting basic settings configured. Also https://help.github.com/articles/generating-an-ssh-key/ will help with setting up credentials for GitHub.
To fully build and advertise a new addon will require local copies of the three repositories, the 'addons-source', 'addons' and the main Gramps source 'gramps'.

This wiki assumes that the three git repositories local locations are all to be put into the users' home directory and named with the repository names.

The three directories '''must''' be named as shown, and in the same base directory in order for the make.py script to work properly, however they don't have to be located directory in the users home directory.

From your home directory;

git clone git@github.com:gramps-project/addons-source.git addons-source
git clone git@github.com:gramps-project/addons.git addons
git clone git@github.com:gramps-project/gramps.git gramps

or if you do not have a Github account:

git clone https://github.com/gramps-project/addons-source.git addons-source
git clone https://github.com/gramps-project/addons.git addons
git clone https://github.com/gramps-project/gramps.git gramps

This will create a copy of the addons-source tree in your home directory at "~/addons-source", and the other trees at their respective locations as well.

To switch to a local copy of the gramps51 branch:

cd addons-source
git checkout -b gramps51 origin/maintenance/gramps51

or to work in the master branch:

cd addons-source
git checkout -b gramps52 origin/master

=== Other pre-requisites ===
{{man warn|These instructions, the make.py script etc.|are designed to operate in a Linux environment. {{man menu|They won't work on Windows without modifications.}}}}
* Gramps uses Python version 3.2 or higher. You must have at least that version installed. If you have installed Gramps 4.2 or higher on your Linux system already, then a sufficient version of Python will be present. If you have more than one version of Python installed, then you must use the correct version for these scripts. On some systems, both Python 2.x and 3.x are installed. It is possible that the normal invocation of <code>python</code> starts up Python 2.x, and that to start up Python 3.x requires invoking with <code>python3</code> or <code>python3.4</code> etc. You can test the version by <code>python –version</code> or <code>python3 –version</code>. If this is so, replace any usage of 'python' in the examples below with the appropriate invocation.
* The make.py used in construction of the addons requires that the LANGUAGE environment variable be set to 'en_US.UTF-8'.
* The make.py used in construction of the addons requires that the GRAMPSPATH environment variable be set to your path to the Gramps source tree.
* intltool must be installed;
: <code>sudo apt-get install intltool</code>

For example if your home directory is '/home/name' and you use the suggested path names, use
: <code>GRAMPSPATH=/home/name/gramps LANGUAGE='en_US.UTF-8' python3 make.py ...</code>
to replace the <code>./make.py</code> in the examples below.

=== Create your addon subdirectory ===
* Make a new project directory in addons-source:
: <code>mkdir NewProjectName</code>

===Follow the development API for your tool===
Create your NewProjectName.py and NewProjectName.gpr.py files.

Follow the development API for your tool, [[Report-writing_tutorial|report]], view, or [[Gramplets]]. Place all of your associated .py, .glade, etc. files in this directory. For general information on Gramps development see [[Portal:Developers]] and [[Writing a plugin|Writing a Plugin]] specifically.

=== Test your addon as you develop ===

{{man warn|{{bug|10436}} Symlinks to folders in gramps plugin dir are not scanned}}

To test your addon as you develop it is suggested that you copy your NewProjectName plugin into your Gramps user plugin directory from your addon development directory, prior to testing. Or just edit in the Gramps user plugin directory until it is ready to publish, then copy back to your addon development directory.

Your installed Gramps will search this folder (and subdirectories) for .gpr.py files, and add them to the plugin list.

If you have code that you want to share between addons, you don't need to do anything special. Gramps adds each directory in which a .gpr.py is found onto the PYTHONPATH which is searched when you perform an import. Thus "import NewProjectName" will work from another addon. You should always make sure you name your addons with a name appropriate for Python imports.

=== Commit your changes ===
To commit your changes so that others can see your addon source.

* Remove the files using the ''clean'' command that should not be added to GitHub (eg files(template.pot/ locale etc)):
: <code>./make.py gramps51 clean NewProjectName</code>
* Add the project to the repository:
: <code>git add NewProjectName</code>
* Commit it with an appropriate message
: <code>git commit -m "A message describing what this addon is"</code>

Before committing additional edits to your addon, you should:

* to make sure that outside changes do not affect your commit
: <code>git pull --rebase</code>
* only the files you changed should be in this list
: <code>git status</code>
* Commit it with an appropriate message
: <code>git commit -m "A message describing the changes"</code>

If you have been given 'push' rights to GitHub 'gramps-project/addons-source', and when you are sure you are done and want to publish to the repository:

* to make sure that outside changes do not affect your commit
: <code>git pull --rebase</code>
: <code>git push origin gramps51</code>

Also you may want to [[Addons_development#Package_your_addon |Package your addon]] so it can be downloaded via the plugin manager.

=== Config ===

Some addons may want to have persistent data (data settings that remain between sessions). You can handle this yourself, or you can use Gramps' built-in configure system.

At the top of the source file of your addon, you would do this:

from config import config as configman
config = configman.register_manager("grampletname")
# register the values to save:
config.register("section.option-name1", value1)
config.register("section.option-name2", value2)
...
# load an existing file, if one:
config.load()
# save it, it case it didn't exist:
config.save()

This will create the file "grampletname.ini" and put in the same directory as the addon. If the config file already exists, it remains intact.

In the addon, you can then:

x = config.get("section.option-name1")
config.set("section.option-name1", 3)

and when this code is exiting, you might want to save the config. In a Gramplet that would be:

def on_save(self):
config.save()

If your code is a system-level file, then you might want to save the config in the Gramps system folder:

config = configman.register_manager("system", use_config_path=True)

This, however, would be rare; most .ini files would go into the plugins directory.

In other code that might use this config file, you would do this:

from config import config as configman
config = configman.get_manager("grampletname")
x = config.get("section.option-name1")

=== Localization ===

For general help on translations in Gramps, see [[Coding for translation]]. However, that will only use translations that come with Gramps, or allows you to contribute translations to the Gramps core. To have your own managed translations that will be packaged with your addon, read the rest of this page.
Note that these instructions will only work for Python strings, if you have a glade file, it will not get translated.

For any addon which you have translations into other languages, you will need to add a way to retrieve the translation. You need to add this to the top of your NewProjectName.py file:

from gramps.gen.const import GRAMPS_LOCALE as glocale
_ = glocale.get_addon_translator(__file__).gettext

Then you can use the standard "_()" function to translate phrases in your addon.

You can use one of a few different types of translation functions:

# gettext
# lgettext
# ngettext
# lngettext
# sgettext

These have become obsolete in Gramps 4; gettext, ngettext, and sgettext always return translated strings in unicode for consistent portability between Python 2 and Python3.

See the [http://docs.python.org/3/library/gettext.html#the-gnutranslations-class python documentation] for documentation of gettext and ngettext. The "l" versions return the string encoded according to the [http://docs.python.org/3/library/locale.html#locale.setlocale currently set locale]; the "u" versions return unicode strings in Python2 and are not available in Python 3.

'''sgettext''' is a Gramps extension that filters out clarifying comments for translators, such as
_("Remaining names | rest")
Where "rest" is the English string that we want to present and "Remaining names" is a hint for translators.

==== Commands to compile translations ====

To build and compile translations for all projects to their download/Addon.addon.tgz files:

: <code>python3 make.py gramps51 build all</code>

To compile translations for all projects :

: <code>python3 make.py gramps51 compile all</code>

== Create a Gramps Plugin Registration file ==

First, create the NewProjectName.gpr.py file. The registration takes this general form:

<pre>
register(PTYPE,
gramps_target_version = "5.1",
version = "1.0.0",
ATTR = value,
)
</pre>

[https://github.com/gramps-project/gramps/blob/master/gramps/gen/plug/_pluginreg.py#L76 PTYPE] is TOOL, GRAMPLET, REPORT, QUICKVIEW, IMPORT, EXPORT, DOCGEN, GENERAL, MAPSERVICE, VIEW, or RELCALC.

ATTR depends on the PTYPE. But you must have '''gramps_target_version''' and '''version'''. '''gramps_target_version''' should be a string of the form "X.Y" version number matching Gramps X major, Y minor integer. '''version''' is a string of the form "X.Y.Z" representing the version of your addon. X, Y, and Z should all be integers.

Here is a sample Tool GPR file:

<pre>
register(TOOL,
id = 'AttachSource',
name = _("Attach Source"),
description = _("Attaches a shared source to multiple objects."),
version = '1.0.0',
gramps_target_version = '5.1',
status = STABLE,
fname = 'AttachSourceTool.py',
authors = ["Douglas S. Blank"],
authors_email = ["doug.blank@gmail.com"],
category = TOOL_DBPROC,
toolclass = 'AttachSourceWindow',
optionclass = 'AttachSourceOptions',
tool_modes = [TOOL_MODE_GUI]
)
</pre>

You can see examples of the kinds of addons [https://github.com/gramps-project/gramps/plugins here] (for example, see [https://github.com/gramps-project/gramps/plugins/drawreport/drawplugins.gpr.py gramps/plugins/drawreport/drawplugins.gpr.py]) and see the full documentation [https://github.com/gramps-project/gramps/gen/plug/_pluginreg.py here] in the comments and docstrings.

Note that this .gpr.py will automatically use translations if you have them (see below). That is, the function "_" is predefined to use your locale translations; you only need to mark the text with _("TEXT") and include a translation of "TEXT" in your translation file. For example, in the above example, _("Attach Source") is marked for translation. If you have developed and packaged your addon with translation support, then that phrase will be converted into the user's language.

=== Report plugins ===
The possible report categories are (gen/plug/_pluginreg.py):
<pre>
#possible report categories
CATEGORY_TEXT = 0
CATEGORY_DRAW = 1
CATEGORY_CODE = 2
CATEGORY_WEB = 3
CATEGORY_BOOK = 4
CATEGORY_GRAPHVIZ = 5
REPORT_CAT = [ CATEGORY_TEXT, CATEGORY_DRAW, CATEGORY_CODE,
CATEGORY_WEB, CATEGORY_BOOK, CATEGORY_GRAPHVIZ]
</pre>

Each report category has a set of standards and interface. The categories CATEGORY_TEXT and CATEGORY_DRAW use the Document interface of Gramps. See also [[Report API]] for a draft view on this.

The application programming interface or API for reports is treated at [[Report-writing_tutorial]]. For general information on Gramps development see [[Portal:Developers]] and [[Writing a plugin|Writing a Plugin]] specifically.

=== General plugins ===

The plugin framework also allows you to create generic plugins for use. This includes the ability to create libraries of functions, and plugins of your own design.

==== Example: A library of functions ====

In this example, a file name library.py will be imported at time of registration (when Gramps starts):

<pre>
# file: library.gpr.py

register(GENERAL,
id = 'My Library',
name = _("My Library"),
description = _("Provides a library for doing something."),
version = '1.0',
gramps_target_version = '5.1',
status = STABLE,
fname = 'library.py',
load_on_reg = True,
)
</pre>

The code in the file library.py will be imported when Gramps begins. You can access the loaded module in other code by issuing an "import library" as Python keeps track of files already imported. However, the amount of useful code that you can run when the program is imported is limited. You might like to have the code do something that requires a dbstate or uistate object, and neither of these is available when just importing a file.

If "load_on_reg" was not True, then this code would be unavailable until manually loaded. There is no automatic mechanism in Gramps to load GENERAL plugins automatically.

In addition to importing a file at startup, one can also run a single function inside a GENERAL plugin, and it will be passed the dbstate, the uistate, and the plugin data. The function must be called "load_on_reg", and take those three parameters, like this:

<pre>
# file: library.py

def load_on_reg(dbstate, uistate, plugin):
"""
Runs when plugin is registered.
"""
print("Hello World!")
</pre>

Here, you could connect signals to the dbstate, open windows, etc.

Another example of what one can do with the plugin interface is to create a general purpose plugin framework for use by other plugins. Here is the basis for a plugin system that:

* allows plugins to list data files
* allows the plugin to process all of the data files

First, the gpr.py file:

<pre>

register(GENERAL,
id = "ID",
category = "CATEGORY",
load_on_reg = True,
process = "FUNCTION_NAME",
)
</pre>

This example uses three new features:

# GENERAL plugins can have a category
# GENERAL plugins can have a load_on_reg function that returns data
# GENERAL plugins can have a function (called "process") which will process the data

If you (or someone else) create additional general plugins of this category, and they follow your load_on_reg data format API, then they could be used just like your original data. For example, here is an additional general plugin in the 'WEBSTUFF' category:

<pre>
# anew.gpr.py

register(GENERAL,
id = 'a new plugin',
category = "WEBSTUFF",
version = '1.0',
gramps_target_version = '5.1',
data = ["a", "b", "c"],
)
</pre>

This doesn't have load_on_reg = True, nor does it have a fname or process, but it does set the data directly in the .gpr.py file. Then we have the following results:

<pre>
>>> from gui.pluginmanager import GuiPluginManager
>>> PLUGMAN = GuiPluginManager.get_instance()
>>> PLUGMAN.get_plugin_data('WEBSTUFF')
["a", "b", "c", "Stylesheet.css", "Another.css"]
>>> PLUGMAN.process_plugin_data('WEBSTUFF')
["A", "B", "C", "STYLESHEET.CSS", "ANOTHER.CSS"]
</pre>

=== Registered GENERAL Categories ===

The following are the published secondary plugins API's (type GENERAL, with the following categories):

==== WEBSTUFF ====

A sample gpr.py file:

<pre>
# stylesheet.gpr.py

register(GENERAL,
id = 'system stylesheets',
category = "WEBSTUFF",
name = _("CSS Stylesheets"),
description = _("Provides a collection of stylesheets for the web"),
version = '1.0',
gramps_target_version = '5.1',
fname = "stylesheet.py",
load_on_reg = True,
process = "process_list",
)
</pre>

Here is the associated program:

<pre>
# file: stylesheet.py

def load_on_reg(dbstate, uistate, plugin):
"""
Runs when plugin is registered.
"""
return ["Stylesheet.css", "Another.css"]

def process_list(files):
return [file.upper() for file in files]
</pre>

==== Filters ====

For example:

<pre>
register(GENERAL,
category="Filters",
...
load_on_reg = True
)
</pre>

<pre>
def load_on_reg(dbstate, uistate, plugin):
# returns a function that takes a namespace, 'Person', 'Family', etc.

def filters(namespace):
print("Ok...", plugin.category, namespace, uistate)
# return a Filter object here
return filters
</pre>


== Get translators to translate your addon into multiple languages ==

If you [[#Localization|designed for localization]], the addon will begin supporting a single language. Make your add-on inviting for volunteers to translate it into their native language.
* Initialize and update the <code>template.pot</code> for your addon:
: <code>cd ~/addons-source</code>
: <code>./make.py gramps51 init NewProjectName</code>
* You should edit the header of <code>template.pot</code> with your information, so it gets copied to individual language files.
* Initialize a language for your addon (say French, fr):
: <code>./make.py gramps51 init NewProjectName fr</code>
* Update it from gramps and other addons:
: <code>./make.py gramps51 update NewProjectName fr</code>
* Edit the translations file manually:
: <code>/NewProjectName/po/fr-local.po</code>
* Compile the language:
: <code>./make.py gramps51 compile NewProjectName</code>
* Add or update your local language file, and commit changes:
: <code>git add NewProjectName/po/fr-local.po</code>
: <code>git commit NewProjectName/po/fr-local.po -m "Added fr po file"</code>
* If you have been given 'push' rights to GitHub 'gramps-project/addons-source', then;
: <code>git push origin gramps51</code>

== Package your addon ==

To create a downloadable package:

: <code>./make.py gramps51 build NewProjectName</code> or
: <code>./make.py gramps52 build NewProjectName</code> for the master branch.

Note that the

This will automatically include the following files in your build:

* *.py
* *.glade
* *.xml
* *.txt
* locale/*/LC_MESSAGES/*.mo

Starting with Gramp 5.0, if you have additional files beyond those listed above, you should create a MANIFEST file in the root of your addon folder listing the files (or pattern) one per line, like this sample MANIFEST file:

<pre>
README.md
extra_dir/*
help_files/docs/help.html
</pre>

{{man note|Note:|Running the command <code>make.py xxx build</code> will increment the third number in your dotted version number of all addons in the <code>*.gpr.py</code> file. Consider this number to be a "build number".}}

This will leave your 'addons-source' with untracked changes according to git. You should delete the 'NewProjectName/locale' directory. The updated 'NewProjectName/NewProjectName.gpr.py ' is ready to add and commit the next time you make other changes.
: <code>rm –rf –v 'NewProjectName/locale'</code>

Then add the package to GitHub:

<pre> cd '~/addons'
git add gramps51/download/NewProjectName.addon.tgz
git commit -m "Added new plugin: NewProjectName"</pre>
or (for the master branch);
<pre> cd '~/addons'
git add gramps52/download/NewProjectName.addon.tgz
git commit -m " Added new plugin: NewProjectName"</pre>

== List your addon in the Gramps Plugin Manager==

{{man warn|Gramps needs to have been built|Make sure you have already built gramps51 or master. Change to the appropriate git branch in your gramps directory, and run <code>python3 setup.py build</code> See [[Linux:Build_from_source]]}}

To create a listing:

: <code>cd '~/gramps-addons'</code> or wherever you have built your addon
: <code>GRAMPSPATH=path/to/your/gramps/install ./make.py gramps51 listing NewProjectName</code>
or (for the master branch);
: <code>cd '~/gramps-addons'</code> or wherever you have built your addon
: <code>GRAMPSPATH=path/to/your/gramps/install ./make.py gramps52 listing NewProjectName</code>

That will create a series of files in the <tt>../listings/</tt> directory.

Then add the updated listing to GitHub:

<pre> cd '~/addons'
git add gramps51/listings/*
git commit -m "Added new plugin to listings: NewProjectName"</pre>
or (for the master branch);
<pre> cd '~/addons'
git add gramps52/listings/*
git commit -m " Added new plugin to listings: NewProjectName"</pre>

== List and document your addon on the wiki==

===List your addon===
Add a short description of your addon to the Addons list by editing the current release listing eg: [[5.1_Addons]] or if the addon is meant for a future release [[5.2_Addons]] when available.

==== Example addon template ====
Examine the listing for other addons and refer to the [[Plugin list legend]] for details of on the meaning of each columns.
<pre>
|- 
|
|
|
|
|
|
|
|
|-
</pre>

===Document your addon===
Document the addon in the wiki using the page name format of {{man menu|Addon:NewProjectName}} examine the other addon support pages for the general format to use.
{{man tip|Hint on creating a new wiki page.|To create a new wiki page use the search box to search for the name of your page that doesn't exist then on the search results page you will be provided with a link to create the new page, by selecting and you can add your content}}

====Example addon article====
Consider including the following information:

<pre>

{{Third-party plugin}}


== Usage ==

=== Configure Options ===

==Features==

== Prerequisites ==

== Issues ==


[[Category:Addons]]
[[Category:Plugins]]
[[Category:Developers/General]]
</pre>

== Announce it on the Gramps mailing list ==
Join the [[Contact#Mailing_lists|Gramps Mailing lists]] and announce it to the users with general information on why you created and how to use it.

== Support it through issue tracker ==

Become a user on the [https://gramps-project.org/bugs/view_all_bug_page.php Gramps MantisBT (Mantis BugTracker)].
and please check it regularly. There is no automated notification of issues (and possible feature requests) related to your addon when reported by users.

Users tend to not understand coding and they make assumptions. So be kind and guiding if a report is ambiguous or inaccurate. A negative remark from an addon developer or anyone can be very discouraging.

== Maintain the code as Gramps continues to evolve ==

Remember that Gramps addons exist for many reasons and there are many
Gramps developers that do support addons in various ways (translations,
triage, keeping in sync with master, download infrastructure, etc).

Some reasons why the addons exist; they provide:
* A quick way for anyone to share their work; the Gramps-project has never denied adding a addon.
* A method to continuously update and develop a stand-alone component, often before being officially accepted.
* A place for controversial plugins that will never be accepted into core, but are loved by many users (eg, Data Entry Gramplet).
* A place for experimental components to live.
== Example code adding common enhancements ==
* Copy all the Gramplet's output to a system clipboard via context pop-up menu : Enhancement request {{bug|11573}}, [https://github.com/gramps-project/gramps/pull/1014/commits/72012e13b4ca15caca4b7f36fdb9702c1fd470fd example pull]
* add a custom [[Gramps_Glossary#viewmode|View Mode]] toolbar icon via the <code>.gpr.py</code> : [https://github.com/gramps-project/gramps/pull/1017 Pull 1017 Discussion], [https://github.com/gramps-project/gramps/pull/1017/commits/76e41d546d6ec519dd78fbe07f663135b5c79351 example Pull]

= Resources =
* [[Brief_introduction_to_Git|Git introduction]]
* [[Getting started with Gramps development]]
* [[Portal:Developers]]
* [https://gramps-project.org/docs/gen/gen_plug.html?highlight=include_in_listing#module-gramps.gen.plug._pluginreg Registration Module]

;Gramps Addons site for Gramps 4.2 and newer
* https://github.com/gramps-project/addons-source - Source code (Git)
* https://github.com/gramps-project/addons - downloadable .tgz files
;Gramps Addons site for Gramps 4.1 and older
* For 4.1.x and earlier, see [[Addons development old]].

[[Category:Developers/General]]
[[Category:Developers/Tutorials]]
[[Category:Plugins]]
[[Category:Reports]]
[[Category:Gramplets]]
[[Category:Addons]]

Download

2022-01-22T02:58:45Z

Codefarmer: Specify more clearly the missing translations error message

{{languages|Download}}
[[File:Gramp-Small-background-wiki-2020.jpg|120px|left]]
'''Research, organize and share your family tree with Gramps.'''

Gramps is a free software project and community. We strive to produce a genealogy program that is both intuitive for hobbyists and feature-complete for professional genealogists. It is a community project, created, developed and governed by genealogists.

{{man note|{{Man menu|Gramps '''Current version: '''{{version}}''' Released: '''2021-07-26'''}}|''Different data format to the GRAMPS 3.4 series. Full Python 3 support only as [https://www.python.org/doc/sunset-python-2/ Python 2 support dropped]. Uses GTK+ 3 GUI. Default database is now SQLite. Lot of updates see: ''[[Gramps 5.1 Wiki Manual - What's new?|What's new?]]{{-}}
[[File:Linux_220x261.png|128px|link=Download#Linux]] [[File:windows_180x160.png|128px|link=Download#MS_Windows]] [[File:macos_200x200.png|128px|link=Download#macOS]] [[File:Bsd daemon.png|128px|link=Download#BSD]]}}

== Linux ==

[[File:Linux_220x261.png|128px|left|link=Download#Linux]]

Before upgrading your distribution: Use your '''earlier version of Gramps''' to [[How_to_make_a_backup#Gramps_version_3.3_and_later|backup]] your Family Trees to the hardy and portable [[#1|XML format1]].

<big>
[[Download#Linux distributions|via Distributions]]
    
[[Download#Flathub|via Flathub]]
    
[[Download#Linux:_Install_latest_version|Latest version ({{version}}) (advanced users only)]]</big>
{{-}}

== MS Windows ==
[[File:windows_180x160.png|128px|left|link=Download#MS_Windows]]

Before downloading the All-In-One software installer bundle for Windows: Use your '''earlier version of Gramps''' to [[How_to_make_a_backup#Gramps_version_3.3_and_later|backup]] your Family Trees to the hardy and portable [[#1|XML format1]].

This installer supports Microsoft Windows in all versions [http://windows.microsoft.com/en-au/windows/lifecycle Vista/7] and later. The 64-bit versions of Windows allow more efficient access to more resources.

(''Please note: Gramps prefers the Python-3.5 and Gtk-3.18 libraries and newer. Those libraries have dropped support for Windows XP. But Gramps can still be run on Windows XP with earlier library versions, i.e., Python3.4.4 and Gtk-3.16'')

<big>
*[{{github_url}}/releases/download/v{{version_windows_AIO64}}/{{filename_windows_AIO64}}.exe Windows Installer (64-bit) {{version_windows_AIO64}}]
*[{{github_url}}/releases/download/v{{version_windows_AIO32}}/{{filename_windows_AIO32}}.exe Windows Installer (32-bit) {{version_windows_AIO32}}]</big>


After download: '''double-click to install Gramps'''. By default: new releases will be added in a new directory and earlier installations of Gramps will ''not'' be overwritten; the language will be a [[#Missing_other_languages|mix of British and US English]].

{{man tip|Shortcuts|During installation, one shortcut is placed on the desktop and two shortcuts are added the Start menu. ''Please only use the 'console' secondary shortcut when performing diagnostics requested by a developer.'' 1) ''GrampsAIO'''XX''' ''{{version}}'' {{man menu| ← for normal use of Gramps}} 2) ''GrampsAIO'''XX''' ''{{version}}''-console}}

Normally, when you try to load your old Family Tree you can allow it to be upgraded if necessary, and it will be opened. Should this fail for any reason, '''Create''' a new Family Tree and [[How_to_restore_a_backup|'''Import''' the back-up]] into this new Tree.

Use the Windows AIO (All-In-One) version, please use the download links above. For more information about individual versions, console and debug modes, release notes, etc., look at [[GrampsAIO cx freeze-based|this page]] (English only). Or, you might want to look at the description of what is meant by an [[All_In_One_Gramps_Software_Bundle_for_Windows|All In One Bundle.]]

=== Alternative independent installation ===
[[File:Gramps-release.png|left]]
If needed, there are alternatives to the All-In-One installer.

==== PortableApps.com ====
A [https://portableapps.com/apps/education/gramps_portable '''PortableApps''' version] will run from an external device without the requirement of installing on the OS drive. PortableApps installations are not for touchscreen-based mobile devices. They just allow the application to run from external storage, USB thumbdrives.

As of {{CURRENTDAYNAME}}, {{CURRENTDAY}} {{CURRENTMONTHNAMEGEN}} {{CURRENTYEAR}}, the most current Gramps release is the {{TEMPLATE:version}} version.

You can download the '''{{Version_windows_portable}} Gramps Portable version''' from:
* the [https://portableapps.com/apps/education/gramps_portable Gramps Portable project] page in their [https://portableapps.com/apps/education/ Education] category.

Note that '''PortableApps.com''' also has a Legacy 3.4.9 version of Gramps available -- although it is not recommended for general use; just for recovering older format databases.
* [http://sourceforge.net/projects/portableapps/files/Gramps%20Portable/ GrampsPortable_3.4.9.paf.exe] (29.0 MB)

[http://portableapps.com/apps/education/gramps_portable Portable Gramps from PortableApps.com] includes all dependencies required for Windows. ''Note:You can install it on C: then to run Gramps type C:\PortableApps\GrampsPortable\GrampsPortable.exe (Or the path you installed it to) or make a shortcut to that file on your desktop or start-menu.'' By Bart.S - '''[http://portableapps.com/blog/84601 Please report packaging issues to the author.]''' (2012-09-07)

==== Chocolatey NuGet Package ====
You may also install using the alternative independent Gramps Chocolatey NuGet Package

Chocolatey NuGet is a Machine Package Manager, somewhat like apt-get, but built with Windows in mind.

* [https://chocolatey.org/packages/gramps/ Gramps Chocolatey Package]

==== Gramps for Windows with MSYS2 ====

How to use [https://www.msys2.org/ MSYS2] to run latest Gramps development version from source in 64bit Windows.

* [[Gramps for Windows with MSYS2]]

{{-}}

=== Missing other languages ===
[[File:Microsoft Window Gramps AIO Installer Choose Components-Selection-51.png|right|thumb|450px|Microsoft Window Gramps AIO Installer Choose Components-Selection window.]]
The default Gramps AIO installer will embed the US dialect of English for the interface with the British spellcheck dictionary.

If you prefer a different language (or spell with the US or Australian dialects of English), please ensure that you pay special attention to the Choose Components phase of the installation.

To install a language other than English, select from both the '''Translations''' ''and'' '''Dictionaries''' during the Choose Components phase of the installation.

Even your primary language is installed by default, you might anticipate the need to spellcheck Notes in other than the British dialect of English. Be certain to select the appropriate languages from '''Dictionaries'''. Gramps will not access your Operating System's native dictionary.

There is no simple facility for adding interface or dictionary languages after installation.
{{-}}



== macOS ==

[[File:macos_200x200.png|128px|left|link=Download#Mac_OS_X]]

Before downloading the ready-to-run stand-alone bundle: Use your '''earlier version of Gramps''' to [[How_to_make_a_backup#Gramps_version_3.3_and_later|backup]] your Family Trees to the hardy and portable [[#1|XML format1]]. Read the [[Mac OS X:Application package|before installation]] instructions.

Tested for compatibility with Apple macOS/Mac OS X versions 10.5 ([https://wikipedia.org/wiki/Mac_OS_X_Leopard Leopard]) through 11 ([https://wikipedia.org/wiki/MacOS_Big_Sur Big Sur]). ''Help determining your Operating System version can be found in the [https://support.apple.com/en-us/HT201260 HT201260 Apple Support article.]''

<big>
* [{{github_url}}/releases/download/v{{version_Mac}}/{{Filename_mac_intel}}.dmg Intel {{version_Mac}}]
</big>

After download: Double-click the .dmg file to mount the disk (note: your browser may do this for you automatically). Next, drag the Gramps application to your application folder and double-click to launch it. (For Apple Mac OS X, alternatively, you can click and hold on the disk icon at the top of the window of the mounted disk, and then option-drag to the Applications folder. This will create a new folder containing all the files, including the README and NEWS.)

Normally, when you try to load your old Family Tree you can allow it to be upgraded if necessary, and it will be opened. Should this fail for any reason, '''Create''' a new Family Tree and [[How_to_restore_a_backup|'''Import''' the back-up]] into this new Tree.

=== Alternative independent installation ===
[[File:Gramps-release.png|left]]
Alternatively, Gramps can also be installed on macOS using either the MacPorts or Homebrew package manager systems.

{{-}}
==== MacPorts ====

MacPorts is a package manager for Apple Mac.

* [[Mac_OS_X:Build_from_source:MacPorts]]

{{-}}

==== Homebrew ====
[https://wikipedia.org/wiki/Homebrew_(package_manager) Homebrew] is an open-source package manager for macOS (and Linux).

See https://github.com/homebrew/

{{-}}

=== Adding additional Spell Checking languages on macOS ===
{{man tip|[[Mac_OS_X:Application_package#Dictionaries|Spell Checking:]]|Gramps uses a different spell checker than the one provided by Mac OS X, with different spelling dictionary requirements. We can't easily provide dictionaries for all of the supported languages in the bundle, but they're easily downloaded from [https://extensions.openoffice.org/ OpenOffice.org's website]. Download the language you want and save it, then navigate to the download in Finder. Most browsers have a downloads window that offers "Show in Finder" in its context menu. Change the file extension from <tt>oxt</tt> to <tt>zip</tt>, then from the context menu select '''Open with... Archive Utility''' to decompress it. In the decompressed folder or perhaps in a subfolder you'll find the dictionary files in pairs, <tt>foo.aff</tt> and <tt>foo.dic</tt>. Some languages have more than one pair with a README file to explain why. Select a pair and copy it to /Library/Dictionaries (you'll have to authenticate with an administrator id and password), and if 'foo' isn't already a language or locale code, make it one. For example, the French package includes several pairs with names like <tt>fr-moderne.aff</tt> and <tt>fr-moderne.dic</tt>. The spell checker doesn't recognize those names, so when you copy them to /Library/Dictionaries you must rename them to <tt>fr.aff</tt> and <tt>fr.dic</tt> or <tt>fr_FR.aff</tt> and <tt>fr_FR.dic</tt>. You can have more than one dictionary pair installed if you use several languages, but one '''must''' match the language you use for Gramps or spell checking won't be enabled at all.}}

{{-}}

== Linux and BSD distributions ==
{{man note|These packages are built and supported by the [https://en.wikipedia.org/wiki/Linux_distribution distros].|If your distribution is not listed you may possibly find it listed on [https://repology.org/metapackage/gramps/versions ''Repology''] Please report any problems with them to the package maintainer.}}
Most Linux distributions come bundled with a version of Gramps, though it's not always the most recent version and it may not have been installed by default. Still it is recommended to use the Gramps version that comes with your distribution.

Below are ways to install Gramps on some of the more popular distributions:

{| {{prettytable}}
!style="width: 85pt;" | Distribution
!GUI Package manager
!Current versions
!Notes
|-
|[[File:Debianopenlogo-32.png|link=https://packages.debian.org/search?keywords=gramps]]''' [[Debian]] '''
|Add/Remove Software
|
* Debian 8 ("jessie")(old old old stable): Gramps 4.1.1
* Debian 9 ("stretch") (old old stable): Gramps 4.2.5
* Debian 9 ("stretch")([https://packages.debian.org/stretch-backports/gramps backports]): Gramps 5.0.1
* Debian 10 ("buster") (old stable): Gramps 5.0.1
* Debian 10 ("buster")([https://packages.debian.org/buster-backports/gramps backports]) (stable): Gramps 5.1.2
* Debian 11 ("bullseye")(stable): Gramps 5.1.3
* bookworm (testing): Gramps 5.1.4
* [http://packages.debian.org/sid/gramps sid (unstable)]: Gramps 5.1.4
|[http://packages.debian.org/search?keywords=gramps available versions]
|-
|[[File:Ubuntu_32x32.png]] '''[https://ubuntu.com/ Ubuntu]'''
|Software Centre
|
* Xenial (16.04 LTS): Gramps: 4.2.2
* Xenial (16.04 LTS): Gramps: 4.2.6 ([https://launchpad.net/~rosco2/+archive/ubuntu/backports Backport])
* Bionic Beaver (18.04 LTS): Gramps: 5.0.0
* Eoan (19.10): Gramps: 5.0.1
* Focal (20.04 LTS): Gramps: 5.1.2
* Groovy Gorilla (Development: 20.10): Gramps: 5.1.3
|[http://packages.ubuntu.com/search?keywords=gramps&searchon=names available versions]/ (Also see: [https://launchpad.net/~rosco2/+archive/ubuntu/backports Backports])
|-
|[[File:Farm-Fresh linux mint.png]]''' [https://www.linuxmint.com/ Linux Mint]'''
|Software Manager
|
* 18.x(Gramps 4.2.2~dfsg-1)
* 19.x(Gramps 4.2.8)
* 20.x(Gramps 5.1.2)
|
* Use the "Software Manager" to install a recent version.
* Manually install the most current version of Gramps using the following [https://forums.linuxmint.com/viewtopic.php?t=220159 instructions] from the ''Linux Mint Forums''
* [http://community.linuxmint.com/software/view/gramps Old versions available from Linuxmint]
|-
|[[File:Fedora_32x32.png]] '''[https://getfedora.org/ Fedora]'''
|Add/Remove Software (Gnome) or Software Management (KDE)
|
* Rawhide (Gramps 5.1.4)
* Fedora 33 (Gramps 5.1.4)
* Fedora 34 (Gramps 5.1.4)
* Fedora 35 (Gramps 5.1.4)
|[https://koji.fedoraproject.org/koji/packageinfo?packageID=1969 available versions]
|-
|'''[https://www.mageia.org/en/ Mageia]'''
||[https://wiki.mageia.org/en/Installing_and_removing_software drakrpm (or rpmdrake)]
|
* Mageia [https://madb.mageia.org/package/show/name/gramps/release/cauldron/ Caulron]: Gramps 5.1.4
* Mageia 7.1: Gramps 5.0.1
|[http://mageia.madb.org/package/show/name/gramps Mageia App Db - gramps]
|-
|[[File:OpenSUSE-distribution-icon.png|32px]] '''[https://www.opensuse.org/ openSUSE]'''
|[https://en.opensuse.org/YaST_Software_Management YaST]
|
* openSUSE Tumbleweed: Gramps 5.1.4
* openSUSE Leap 15.2: Gramps 4.2.8
* openSUSE Leap 15.1: Gramps 4.2.8
* openSUSE Leap 15.0: Gramps 4.2.8
|[https://software.opensuse.org/package/gramps available versions] The most recent version can usually be installed from the 'openSUSE BuildService - GNOME:Apps' repository
|-
|[[File:Slackware-distribution-icon.jpg|32px]] '''[http://www.slackware.com/ Slackware]'''
|
|
* 14.2: Gramps 4.2.6
* 14.2: Gramps 5.1.2 - [https://slackbuilds.org/repository/14.2/misc/gramps/?search=gramps slackbuilds.org]
* 14.1: Gramps 4.0.3
|[https://pkgs.org/search/?q=gramps available versions]
|-
|[[File:archlinux-icon-crystal-32.svg]] '''[https://www.archlinux.org/ Arch Linux]'''
| [https://wiki.archlinux.org/index.php/pacman pacman]
|
* Gramps 5.1.4
|[https://www.archlinux.org/packages/community/any/gramps/ available versions]
|-
|[[File:Gentoo-distribution-icon.png|32px]]'''[https://gentoo.org Gentoo Linux]'''
|
|
* Gramps 5.1.4
|[https://packages.gentoo.org/packages/app-misc/gramps available versions]
|-
|'''[https://www.netbsd.org/ NetBSD]'''
|
|
* NetBSD: [http://pkgsrc.se/databases/gramps5 Gramps 5.1.2]
|
|-
|'''[https://www.freebsd.org/ FreeBSD]'''
|
|
* FreeBSD: Gramps 4.2.8
* [https://www.freshports.org/science/gramps/ FreshPorts: Gramps 5.1.4]
|
|-
|'''[https://www.openbsd.org/ OpenBSD]'''
|
|
* OpenBSD: Gramps 5.1.3
|[http://openports.se/misc/gramps available versions]
|-
|
|
|
|
|}

{{-}}

== Linux: Install latest version ==

If your distribution doesn't ship with Gramps or you wish to install a different version than it ships with, you could try to install the latest version of Gramps manually.

{{man warn|1=Warning before attempting this use your existing installation to [[How to make a backup|make a Gramps XML backup]]|2=This should only be attempted by experienced users, and after you have backed up your Family Tree.

The version of Gramps that has been included in your distribution will have been tested to work with the components in that distribution. If you try to install a different version of Gramps there is a possibility that the components needed for the new version of Gramps are not available for your distribution, or they are available, but don't work properly. You might not discover that there is a problem till you have already done some work with the new version of Gramps.

If you already have Gramps installed, and you are only making a 'point' upgrade (i.e. from Gramps x.y.z to x.y.z+1, e.g. from 3.4.3 to 3.4.4), then it is likely but not certain that Gramps will continue to work. However, if the change is much greater, especially if it is a major version change (e.g. from 2.y.z to 3.y.z), then the danger that it does not work properly is much greater.}}

=== Debian-based ===
For [[File:Debianopenlogo-32.png|link=Download#Debian-based]]'''[[Debian|Debian-based linux distributions]]''' (Which includes [[File:Ubuntu_32x32.png|link=Download#Debian-based]]''' Ubuntu ''') [{{github_url}}/releases/v{{version}} Download the .deb file]. Double-click on the downloaded .deb file or (for some distributions, e.g. Mint Debian) run the following command from the directory where the file was saved ({{man menu|change the filename to match the one you downloaded}}).

sudo dpkg -i gramps_{{version}}-1_all.deb

If you have an error about having unmet dependencies run:

sudo apt-get -f install

to install the dependencies.

If you see an error about an incomplete GTK installation and missing language translations when starting Gramps, run

sudo apt install language-pack-gnome-en

to install the proper language pack. You may need to replace 'en' with your own language code, like 'nl' for Dutch.

==== Useful command lines ====
Before upgrading you can[https://sourceforge.net/p/gramps/mailman/message/35460486/]:

* Find out what version you are running, by using this:

dpkg-query -s gramps

that queries the package and gives you info about it.

* If you are committed to an upgrade then make sure you have backed up you Family Trees to Gramps XML then run :

sudo dpkg -r gramps

this will remove the current gramps package (assuming its a python3 version older versions could be python-gramps )

* To stop Ubuntu updating gramps (to possibly an older version from Ubuntu!) you may need to run:

sudo apt-mark hold gramps

'''Upgrade is then complete.'''

=== Flathub ===

Gramps 5.1.4 is available in a flatpak at flathub.

{{man note|Please use your existing installation to backup your database before proceeding.|Also, it is a good idea to [[Gramps_5.1_Wiki_Manual_-_Manage_Family_Trees#Converting_a_BSDDB_Family_Tree_to_SQLite|convert your database to SQLite]] even though there is currently BSDDB3 support in the 5.1.4 flatpak.}}

First set up flatpak and the flathub repository on your system, there are instructions for various distributions at https://flatpak.org/setup/

Second, you can use the blue install button at https://flathub.org/apps/details/org.gramps_project.Gramps if you set your software manager up to work with flathub, or use the command below in a terminal for a system wide installation if you have sudo privileges:

flatpak install flathub org.gramps_project.Gramps

{{-}}

=== For other distributions ===
For other distributions, [[File:Download_link.png|150px|link={{github_url}}/releases/v{{version}}]] the source and follow the instructions for [[Linux:Build from source]]

== BSD ==

[[File:Bsd daemon.png|128px|left|link=Download#BSD]]

Before upgrading your distribution: Use your '''old version of Gramps''' to [[How_to_make_a_backup#Gramps_version_3.3_and_later|backup]] your Family Trees [[#1|[1]]].

<big>
[[Download#Linux and BSD distributions|via Distributions]]
    
[[Download#Linux:_Install_latest_version|Latest version (advanced users only)]]</big>

See also:
* [[BSD platforms]]
{{-}}

== Linux Live CD ==

{{man warn|Note that both Live CD demonstrations use an old version of Gramps and it is not recommended for general use}}

[[File:Download_link.png|150px|left|link=https://sourceforge.net/projects/gramps/files/gramps-cdrom/lgenealogy-6.1-desktop-i386.iso/download]]
'''Linux live CD Demonstration''' includes Gramps {{Version Linux Live CD}} pre-installed to trial, without touching anything on the hard drive. To start this boot the Computer with this Live Linux Desktop on a CD in the CD/DVD-ROM Drive. (Requires that you write this image to a CD-ROM using CD-Burner software eg:Nero, Imgburn..). [[Linux_Genealogy_CD#Download_the_CD|Download the CD]] (727 MB). The [[Linux Genealogy CD|Linux Genealogy CD is based on Ubuntu 10.10 (Maverick Meerkat)]]. If you are interested in Gramps, but are afraid to actually install it or unable to install it (not your PC, windows, no internet at home, work laptop, ...), then try out our [[Linux Genealogy CD]]. It runs without installing on the hard disk and contains a collection of open source, free, genealogy programs. You can then install latest [http://www.ubuntulinux.org/ Ubuntu] and Gramps from the CD anytime you like.
{{-}}

== Online Demonstration ==
{{man note|Note|This is a commercial limited trial and not endorsed by the Gramps-project. Beware of third parties having your genealogical data.}}

You can also try an online demonstration of Gramps on rollApp:
* https://www.rollapp.com/app/gramps
Select '''Launch Online''' then '''Test Drive(Opening/saving files will not be available)'''

{{-}}

== Notes ==

[1]
Backup to Gramps XML. You will find backup in the Family Tree menu of recent Gramps versions, otherwise use export in the same menu but '''uncheck privacy options''' in the Exporter Assistant in order to export all data. See : [[How to make a backup]]

== See also ==
* [[Previous releases of Gramps]]

[[Category:Documentation]]

All In One Gramps Software Bundle for Windows

2022-01-18T16:19:45Z

Codefarmer: /* Installation folder */ Provide examples of Gramps installation path.

{{man warn|Gramps 3.4 and earlier.|Any files listed here may be '''not suitable''' for normal every day use! (My lawyer advised me to say that, but many people are using this and have reported no problems at all.) Any comments and help (e.g. on wiki pages) are welcome. Josip {{man menu|For Gramps 4.x and newer see [[GrampsAIO-4]]}}}}

The '''Gramps "software bundle" for Windows''' or '''GrampsAIO''' is an all-in-one (a.k.a. "AIO") installation package of Gramps which includes all dependencies for the Windows platform. (See also [[Gramps and Windows]].)

Not only are all dependencies included ("bundled"), so that users do not have to first manually install each one of them, but they are
installed in such a fashion that Gramps can easily find them.

For the technically sophisticated, GrampsAIO is rebuild-able: it contains an install script which can make a new installable program from the installed one.

For example somebody might like to repackage Gramps with their code changes, or favorite addons, or even their own family trees, etc.

==Technical details==
The Windows logic for this bundle is that the first entry in the search path is the current working directory... the one in which the program is started. So, if any Gramps dependency is in that same working directory, there is no need to look further for that dependency in a system folder. This eliminates the possibility of loading an incompatible one -- thus "dependency hell" is avoided. This is also the reason why GrampsAIO must be started from its own folder. Also, in newer Windows versions there may be security restriction with shell scripts so GrampsAIO does not use one.)

==Installation folder==
This distribution is directory based, which means it loads all dependencies from the directory in which they have been installed.

That folder's location depends on whether the person doing the installation has administrative rights on the Windows machine. If an administrator installs it, the directory may be chosen. In that case, the default suggestion being <code>%ProgramFiles%\GrampsAIO</code> (for example <code>C:\Program Files\GrampsAIO</code>). If a non-administrator installs it, it will be placed in the user's personal workspace, in <code>%APPDATA%\GrampsAIO</code> (for example <code>C:\Documents and Settings\Jones\Application Data\GrampsAIO</code>).

As an example, a user with administrator rights using GrampsAOI-{{template:Version windows AIO64}}_win64.exe installer and accepting the standard destination folder during installation, <code>C:\Program Files\GrampsAOI64-{{template:Version windows AIO64}}</code> would be the location for the Gramps executable. While not common, installing the 32-bit version of Gramps on a 64-bit OS, the path would be <code>C:\Program Files (x86)\GrampsAIO32-{{template:Version windows AIO32}}</code>. Finally, if you chose to install Gramps in a non-standard directory, use that folder path instead instead.

To use it from the console (cmd.exe prompt), you must first go to the directory where the dependencies were installed (<code>GrampsAIO\bin</code>); for example:

<code>
cd C:\GrampsAIO\bin; python -EO ..\share\gramps\gramps.py
</code>

(but the installation may have been put somewhere else and so you should probably first search for the GrampsAIO\bin folder to make sure).

==Why GrampsAIO was made==
* easy installation:
** no searching web for appropriate packages
** one click install
* no dependency hell:
** all libraries work together
** on upgrade of a library all other libraries are rebuilt with that version

==How GrampsAIO was made==
* Place all software Gramps needs in one package:
# all core non-python libraries and applications
# any optional non-python libraries and applications
# python bindings for core libraries
# python bindings for optional libraries
* use NSIS (Nullsoft Script-able Install System)

==Software releases:==

The preferred way to get the GrampsAIO bundle is to download it from the official Gramps software repository. See [[Download#MS Windows|Download]] for the current version and link to it.

You can follow progress of GrampAIO-4 bundle development at their [[GrampsAIO-4|page]] Older versions or developmental versions are available directly from the GrampsAIO bundle's author. See below.

==See also==
*[https://nsis.sourceforge.io/Creating_language_files_and_integrating_with_MUI#Another_solution:_Native_PO_File_support Native PO File support] for NSIS (Nullsoft Scriptable Install System)
*[[GrampsAIO-3]]
*[[GrampsAIO-4]]
*[[GrampsAIO-4 package updating]]

[[Category:Developers/Packaging]]

Gramps 5.1 Wiki Manual - Command Line

2022-01-18T16:16:51Z

Codefarmer: Centralize installation folder information in All_In_One_Gramps_Software_Bundle_for_Windows > Installation folder section instead adding details here.

{{man index|Gramps 5.1 Wiki Manual - Keybindings|Gramps 5.1 Wiki Manual - User Directory|5.1}}
{{languages|Gramps_5.1_Wiki_Manual_-_Command_Line}}
{{#vardefine:chapter|C}}
{{#vardefine:figure|0}}
This appendix provides the reference to the command line capabilities available when launching Gramps from the terminal.

== Start Gramps through the Command Line ==

Normally Gramps is started through the graphical user interface (GUI) on [[Gramps_5.1_Wiki_Manual_-_Getting_started#Start_Gramps|your platform]].

It is also possible to start Gramps using a command line interface (CLI). CLI use can
* produce reports that are not available via the GUI,
* create reports, do conversions etc. without opening a window and
* can provide [[Gramps_5.1_Wiki_Manual_-_Main_Window#Seeing_all_the_error_messages|extra information]] in the event of problems.

This section of the user manual describes how to start Gramps through the CLI, and the features that are available.

The way you start Gramps through the CLI depends on the operating system you are using.

For simplicity of description, the examples of use below are written from the point of view of running Gramps on Linux. The examples would need to be changed for other platforms.

=== Linux ===

Only the Linux platform is officially supported as Gramps developers use and test the source code on that platform, fixing any problems that arise due to upgrades.

Assuming you have used the standard Package Manager (either through a CLI or a GUI) for your Linux distribution, you start Gramps through the CLI by typing
gramps

=== MS Windows ===

MS Windows is a [[Download|community supported]] platform. If you install the [[All_In_One_Gramps_Software_Bundle_for_Windows|Windows AIO bundle]], then this will place an icon on the desktop as well as a menu item in the 'Start' menu. However, the Gramps installation directory is not added to the system path and to run gramps via CLI, we need to know the path to that directory. To find the installation folder, refer to [[All_In_One_Gramps_Software_Bundle_for_Windows#Installation_folder|AIO bundle's installation folder section]].

To find the path using a shortcut icon instead,
* Right-click on the <code>GrampsAIO64 {{template:Version windows AIO64}}-console</code> application, or the corresponding item in the Start menu.
* Note down the file location (its "Start in' directory).
* Select the full path and copy ({{man key press|Ctrl|c}}) it.

To run Gramps from the command line, you'll need to start a console window:
* From the Start menu, start cmd.exe.
* Change directory to the installation directory you located.
* Type in or paste the path, surrounding it in quotes if there are spaces.
* Press {{man key press|Enter}}.

For example, this might be:
cd "C:\Program Files\GrampsAOI64-{{template:Version windows AIO64}}"
gramps

You may use any of the command-line options along with this. For example, to get a detailed listing of all of the Family Tree databases in your default Family Tree folder, you would append <code>-L</code>
cd "C:\Program Files\GrampsAOI64-{{template:Version windows AIO64}}"
gramps -L

See example usage https://github.com/gramps-project/addons-source/pull/121

=== MacOS ===

MacOS is a [[Download|community supported]] platform. If you download the MacOS disk image (.dmg), then you simply drag the application to your application folder (or anywhere else you want to store it) and start Gramps by double clicking on the application in the normal way. The Homebrew package manager[https://github.com/Homebrew] also allows for installation of the application in the usual Applications folder.

To run from the command line, you'll need to start Terminal, found in the Utilities folder of the main Applications folder (/Applications/Utilities). Once you have a terminal window open, at the prompt type
/path/to/Gramps.app/Contents/MacOS/Gramps
If you installed Gramps in Applications along with most of your other apps, as suggested above, that would be
/Applications/Gramps.app/Contents/MacOS/Gramps
You may use any of the command-line options along with this. For example, to get a detailed listing of all of the Family Tree databases in your default Family Tree folder, you would use
/Applications/Gramps.app/Contents/MacOS/Gramps -L

There are other ways to install Gramps for MacOS, but these are much more complicated and are not covered here.

== Python options ==

In the examples of different platforms above, and also in commands in various files you may see some options after the 'python' command, for example '-EO' in
"python3 -EO ..\share\gramps\gramps.py -L

It is important to distinguish between the '''python options''' in this case:
-EO
and the '''Gramps options''', in this case
-L

The '''python options''' that you may come across are:
* <code>-E</code> Ignore all PYTHON* environment variables, e.g. <code>PYTHONPATH</code> and <code>PYTHONHOME</code>, that might be set.
* <code>-O</code> Turn on basic optimizations. This changes the filename extension for compiled (bytecode) files from <code>.pyc</code> to <code>.pyo</code>. See also PYTHONOPTIMIZE.

The <code>-O</code> optimise flag has a number of effects in Gramps:
* If it is not turned on, an additional {{man menu|[[Gramps_5.1_Wiki_Manual_-_Tools#Debug|Debug]]}} entry appears in the {{man menu|[[Gramps_5.1_Wiki_Manual_-_Tools|Tools]]}} menu.
* If it is not turned on, [[Logging_system#So_how_logging_works_in_Gramps_after_all.3F|info logging messages are output]].
* If it is not turned on, [[Debugging_Gramps#Add_debug_statements|debug statements]] may be activated.
* If it is not turned on, additional features are available in the [[Gramps_5.1_Wiki_Manual_-_Plugin_Manager|Plugin Manager]].

The '''Gramps options''' are described below.

== Available Gramps options ==

This section provides the reference list of all command line options available in Gramps. If you want to know more than just a list of options, see next sections: [[#Operation|Operation]] and [[#Examples| Examples]]. The summary below is printed by
gramps -h
or
gramps --help

<pre>
Usage: gramps.py [OPTION...]
--load-modules=MODULE1,MODULE2,... Dynamic modules to load

Help options
-?, --help Show this help message
--usage Display brief usage message

Application options
-O, --open=FAMILY_TREE Open Family Tree
-U, --username=USERNAME Database username
-P, --password=PASSWORD Database password
-C, --create=FAMILY_TREE Create on open if new Family Tree
-i, --import=FILENAME Import file
-e, --export=FILENAME Export file
-r, --remove=FAMILY_TREE_PATTERN Remove matching Family Tree(s) (use regular expressions)
-f, --format=FORMAT Specify Family Tree format
-a, --action=ACTION Specify action
-p, --options=OPTIONS_STRING Specify options
-d, --debug=LOGGER_NAME Enable debug logs
-l [FAMILY_TREE_PATTERN...] List Family Trees
-L [FAMILY_TREE_PATTERN...] List Family Trees in Detail
-t [FAMILY_TREE_PATTERN...] List Family Trees, tab delimited
-u, --force-unlock Force unlock of Family Tree
-s, --show Show config settings
-c, --config=[config.setting[:value]] Set config setting(s) and start Gramps
-y, --yes Don't ask to confirm dangerous actions (non-GUI mode only)
-q, --quiet Suppress progress indication output (non-GUI mode only)
-v, --version Show versions
-S, --safe Start Gramps in 'Safe mode'
(temporarily use default settings)
-D, --default=[APXFE] Reset settings to default;
A - addons are cleared
P - Preferences to default
X - Books are cleared, reports and tool settings to default
F - filters are cleared
E - Everything is set to default or cleared
</pre>

The usage message is as follows:

gramps --usage

<pre>
Example of usage of Gramps command line interface

1. To import four databases (whose formats can be determined from their names)
and then check the resulting database for errors, one may type:
gramps -i file1.ged -i file2.gpkg -i ~/db3.gramps -i file4.wft -a tool -p name=check.

2. To explicitly specify the formats in the above example, append filenames with appropriate -f options:
gramps -i file1.ged -f gedcom -i file2.gpkg -f gramps-pkg -i ~/db3.gramps -f gramps-xml -i file4.wft -f wft -a tool -p name=check.

3. To record the database resulting from all imports, supply -e flag
(use -f if the filename does not allow Gramps to guess the format):
gramps -i file1.ged -i file2.gpkg -e ~/new-package -f gramps-pkg

4. To save any error messages of the above example into files outfile and errfile, run:
gramps -i file1.ged -i file2.dpkg -e ~/new-package -f gramps-pkg >outfile 2>errfile

5. To import three databases and start interactive Gramps session with the result:
gramps -i file1.ged -i file2.gpkg -i ~/db3.gramps

6. To open a database and, based on that data, generate timeline report in PDF format
putting the output into the my_timeline.pdf file:
gramps -O 'Family Tree 1' -a report -p name=timeline,off=pdf,of=my_timeline.pdf

7. To generate a summary of a database:
gramps -O 'Family Tree 1' -a report -p name=summary

8. Listing report options
Use the name=timeline,show=all to find out about all available options for the timeline report.
To find out details of a particular option, use show=option_name , e.g. name=timeline,show=off string.
To learn about available report names, use name=show string.

9. To convert a Family Tree on the fly to a .gramps xml file:
gramps -O 'Family Tree 1' -e output.gramps -f gramps-xml

10. To generate a web site into an other locale (in German):
LANGUAGE=de_DE; LANG=de_DE.UTF-8 gramps -O 'Family Tree 1' -a report -p name=navwebpage,target=/../de

11. Finally, to start normal interactive session type:
gramps

Note: These examples are for bash shell.
Syntax may be different for other shells and for Windows.

</pre>

=== List options ===
Print a list of known family trees:

;Sparse
-l, List Family Trees

gramps -l

<pre>
List of known Family Trees in your database path

/home/<~username>/.gramps/grampsdb/5a46c1c3 with name "Example Family Tree"
</pre>
{{-}}

;Detailed
-L, List Family Trees in Detail

gramps -L

<pre>
Gramps Family Trees:
Family Tree "Example Family Tree":
Database: SQLite
Database module location: /usr/lib/python3.6/sqlite3/__init__.py
Database module version: 2.6.0
Database version: 3.21.0
Last accessed: 30/12/17 09:29:37
Locked?: False
Number of citations: 2854
Number of events: 3432
Number of families: 762
Number of media: 7
Number of notes: 19
Number of people: 2157
Number of places: 1294
Number of repositories: 3
Number of sources: 4
Number of tags: 2
Path: /home/<~username>/.gramps/grampsdb/5a46c1c3
Schema version: 18.0.0
</pre>

{{man note|Note that dates are shown in the default LOCALE format.|You change that at the system level. For example, on [[Gramps_Glossary#posix|POSIX]]-based systems you could use: <pre>LC_TIME=en_AU.UTF-8 gramps -L</pre>}}
{{-}}

=== Version options ===

-v or --version prints version of Gramps and dependencies,
information about environment settings and python and system paths

gramps -v

<pre>
Gramps Settings:
----------------
python : 3.7.5
gramps : 5.1.1
gtk++ : 3.24.12
pygobject : 3.34.0
pango : 1.42.3
cairo : 1.16.0
pycairo : 1.16.2
osmgpsmap : 1.0
GExiv2 : 0.10
ICU : 63.1
PyICU : 2.2
o.s. : linux
kernel : 5.3.0-24-generic

Environment settings:
---------------------
LANG : en_GB.UTF-8
LANGUAGE : en_GB:en
GRAMPSI18N: not set
GRAMPSHOME: not set
GRAMPSDIR : not set
PYTHONPATH:
/usr/lib/python3/dist-packages/gramps
/usr/bin
/usr/lib/python37.zip
/usr/lib/python3.7
/usr/lib/python3.7/lib-dynload
/usr/local/lib/python3.7/dist-packages
/usr/lib/python3/dist-packages

Non-python dependencies:
------------------------
Graphviz : 2.40
Ghostscr. : 9.27

System PATH env variable:
-------------------------
/usr/local/sbin
/usr/local/bin
/usr/sbin
/usr/bin
/sbin
/bin
/usr/games
/usr/local/games
/snap/bin

Databases:
-------------------------
bsddb :
version : 6.2.6
db version : 5.3.28
location : /usr/lib/python3/dist-packages/bsddb3/__init__.py
sqlite3 :
version : 3.29.0
py version : 2.6.0
location : /usr/lib/python3.7/sqlite3/__init__.py
</pre>

{{-}}

=== Format options ===

The format of any file destined for opening, importing, or exporting can be specified with the <pre>-f format</pre> option. The acceptable <tt>''format''</tt> values are listed below.

==== Full family tree support ====
These formats contain all your data that is present in a family tree.

* '''gramps''' - Gramps XML format: This format is available for import, and export. When not specified, it can be guessed if the filename ends with .gramps
* '''gpkg''' - Gramps package XML format: This format is available for import and export. When not specified, it can be guessed if the filename ends with .gpkg. This creates a zip package with your data as xml, and all your media files included
* '''grdb''' - pre Gramps 3.x database: This format is available for import to support the old file format of Gramps. Everything in the grdb file is imported. When not specified, it can be guessed if the filename ends with .grdb
* '''burn''' - GNOME iso burning: export, only available on GNOME where burn protocol exists

==== Reduced family tree support ====
These formats contain most, but not all data that can be created in Gramps

*'''ged''' - GEDCOM format: This format is available for import, and export. When not specified, it can be guessed if the filename ends with .ged
*'''gw''' - GeneWeb file: This format is available for import and export. When not specified, it can be guessed if the filename ends with .gw

==== Subset of your data ====
These formats contain a specific subset of your data

* '''csv''' - Comma Separated Value: This format is available for import and export. Be careful however, import must be as values created by the export function. Only a part of your data is contained in the output.
* '''vcf''' - VCard format: import and export
* '''vcs''' - VCalendar format: export
* '''def''' - old Pro-Gen format: import
* '''wft''' - Web Family Tree: This format is available for export only. When not specified, it can be guessed if the filename ends with .wft

=== Opening options ===

You can open a family tree, or you can ''open'' a file by importing it in an empty family tree.

To let Gramps handle this automatically, just supply the family tree or filename you want to open:

python gramps.py 'My Fam Tree'
python gramps.py JohnDoe.ged

The first opens a family tree, the second imports a GEDCOM into an empty family tree.

Additionally, you can pass Gramps the name of the family tree to be opened:

* use this option : <code>-O famtree</code> or <code>--open=famtree</code>

<code>-O</code>, Open of a family tree. This can be done also by just typing the name (name or database dir)

Examples:
python gramps.py 'Family Tree 1'
python gramps.py /home/cristina/.gramps/grampsdb/47320f3d
python gramps.py -O 'Family Tree 1'
python gramps.py -O /home/cristina/.gramps/grampsdb/47320f3d

{{Man tip| Tip |If no option is given, just a name, Gramps will ignore the rest of the command line arguments. Use the <code>-O</code> flag to open, <code>-i</code> to import, and do something with the data.}}

{{Man tip| Tip |Only family trees can be opened directly. For other formats, you will need to use the import option which will set up the empty database and then import data into it.}}

{{Man tip| Tip |Only a single family tree can be opened. If you need to combine data from several sources, you will need to use the import option.}}

=== Import options ===

The files destined for import can be specified with the <code>-i filename</code> or <code>--import=filename</code> option. The format can be specified with the <code>-f format</code> or <code>--format=format</code> option, immediately following the ''filename'' . If not specified, the guess will be attempted based on the ''filename''.

Example:
python gramps.py -i 'Family Tree 1' -i 'Family Tree 2'
python gramps.py -i test.grdb -i data.gramps

{{man tip | Tip |More than one file can be imported in one command. If this is the case, Gramps will incorporate the data from the next file into the database available at the moment.}}

When more than one input file is given, each has to be preceded by <code>-i</code> flag. The files are imported in the specified order, i.e. <code> -i file1 -i file2 </code> and <code> -i file2 -i file1 </code> might produce different Gramps IDs in the resulting database.

=== Export options ===

The files destined for export can be specified with the <code>-e filename</code> or <code>--export=filename</code> option. The format can be specified with the <code>-f</code> option immediately following the ''filename'' . If not specified, the guess will be attempted based on the ''filename'' . For iso format, the ''filename'' is actually the name of directory the Gramps database will be written into. For gramps-xml, gpkg, gedcom, wft, geneweb, and gramps-pkg, the ''filename'' is the name of the resulting file.

-e, export a family tree in required format. It is not possible to export to a family tree.

Example:
python gramps.py -i 'Family Tree 1' -i test.grdb -f grdb -e mergedDB.gramps
Note that above does not change 'Family Tree 1' as everything happens via a temporary database, whereas:
python gramps.py -O 'Family Tree 1' -i test.grdb -f grdb -e mergedDB.gramps
will import test.grdb into Family Tree 1, and then export to a file !

{{man tip| Exporting more files |More than one file can be exported in one command. If this is the case, Gramps will attempt to write several files using the data from the database available at the moment.}}

When more than one output file is given, each has to be preceded by <code>-e</code> flag. The files are written one by one, in the specified order.

=== Action options ===

The action to perform on the imported data can be specified with the <code>-a action</code> or <code>--action=action</code> option. This is done after all imports are successfully completed.

The following actions remain the same:

*''report'': This action allows producing reports from the command line.

*''tool'': This action allows to run a tool from the command line.

Reports and tools generally have many options of their own, so these actions should be followed by the report/tool option string. The string is given using the <code>-p option_string</code> or <code>--options=option_string</code> option.

The actions available in older versions of Gramps which were relocated in Gramps 3.3 are:

*''summary'': This action was the same as {{man menu|Reports ->View ->Summary}}. In Gramps 3.3 it was replaced by (or renamed to) '''-a report -p name=summary'''.

*''check'': This action was the same as {{man menu|Tools ->Database Processing ->Check and Repair}}. In Gramps 3.3 it was replaced by (or renamed to) '''-a tool -p name=check'''.

==== report action option ====
You can generate most reports from the command line using the report action.

An example:
gramps -O "Family Tree 1" -a report -p "name=family_group,style=default,off=html,of=test.html"

You can provide the css style to use here with the css option:
gramps -O "Family Tree 1" -a report -p "name=family_group,style=default,off=html,of=test.html,css=Web_Nebraska.css"
or without css in the html output:
gramps -O "Family Tree 1" -a report -p "name=family_group,style=default,off=html,of=test.html,css="

{{man tip| Report option string |The report option string should satisfy the following conditions: It must not contain any spaces (due to the general nature of the command line interface). If some arguments need to include spaces, the string should be enclosed with quotation marks. Option string must list pairs of option names and values. Within a pair, option name and value must be separated by the equal sign. Different pairs must be separated by commas.}}

Most of the report options are specific for every report. However, there are some common options.

*<code>name=report_name</code>: This mandatory option determines which report will be generated.
{{man note|Report names|If the supplied report_name does not correspond to any available report, an error message will be printed followed by this list of available reports. 
<pre>
Available names are:
ancestor_chart - Ancestor Tree
ancestor_report - Ahnentafel Report
AncestorFill - AncestorFill
birthday_report - Birthday and Anniversary Report
calendar - Calendar
d3-ancestralcollapsibletree - Ancestral Collapsible Tree
d3-ancestralfanchart - Ancestral Fan Chart
d3-descendantindentedtree - Descendant Indented Tree
database-differences-report - Database Differences Report
denominoviso - DenominoViso
descend_chart - Descendant Tree
descend_report - Descendant Report
DescendantBook - Descendant Book
Descendants Lines - Descendants Lines
det_ancestor_report - Detailed Ancestral Report
det_descendant_report - Detailed Descendant Report
DetailedDescendantBook - Detailed Descendant Book
double_cousins - Double Cousins
DynamicWeb - Dynamic Web Report
endofline_report - End of Line Report
family_descend_chart - Family Descendant Tree
family_group - Family Group Report
familylines_graph - Family Lines Graph
FamilySheet - Family Sheet
FamilyTree - Family Tree
fan_chart - Fan Chart
gt_ancestor - Ancestor Tree
gt_descendant - Descendant Tree
gt_grandparent - Grandparent Tree
gt_sandclock - Sandclock Tree
gt_sandclock_family - Sandclock Tree for a Family
Heatmap - Heatmap
hourglass_graph - Hourglass Graph
indiv_complete - Complete Individual Report
kinship_report - Kinship Report
LastChangeReport - Last Change Report
LinesOfDescendency - Lines of Descendency Report
ListeEclair - Tiny Tafel
MediaReport - Media Report
navwebpage - Narrated Web Site
networkchart - Network Chart
notelinkreport - Note Link Report
number_of_ancestors - Number of Ancestors Report
PedigreeChart - Pedigree Chart
PersonEverythingReport - PersonEverything Report
place_report - Place Report
records - Records Report
rel_graph - Relationship Graph
Repositories Report - Repositories Report
SourcesCitationsReport - Sources and Citations Report
statistics_chart - Statistics Charts
summary - Database Summary Report
tag_report - Tag Report
timeline - Timeline Chart
TimePedigreeHTML - Timeline Pedigree Report
TodoReport - Todo Report
WebCal - Web Calendar
</pre>}}
*<code>of=</code>: output filename and optional destination folder/directory eg: <code>of="C:\Users\<username>\Desktop\FamilyTree.odt"</code>
*<code>off=</code>: output format. These are the extension an output format makes available, eg, pdf, html, doc, ...
*<code>style=</code>: for text reports, the stylesheet to use. Defaults to 'default'.
*<code>show=all</code>: This will produce the list of names for all options available for a given report.
*<code>show=option_name</code>: This will print the description of the functionality supplied by the option_name, as well as what are the acceptable types and values for this option.

So, to learn to use a report, do for example:
gramps -O "Family Tree 1" -a report -p "name=family_group,show=all"

{{man tip| Tip |If an option is not supplied, the last used value will be used. If this report has never been generated before, then the value from last generated report will be used when applicable. Otherwise, the default value will be used.}}

When more than one output action is given, each has to be preceded by <code>-a</code> flag. The actions are performed one by one, in the specified order.

{{man tip| lists |Some reports have options or arguments which are interpreted (by the report) to be on multiple lines. For instance some reports allow you to format how the information will be shown, perhaps with a name on one line and the person's birth date on the next line. Such multiple-line options or arguments are called "lists" by Gramps.}}

On the command line such lists must always start with a left square bracket <code>[</code> and must always end with a right square bracket <code>]</code> but since such square brackets are usually "special" to the "shell" (they mean something to the command interpreter
you are typing the command to), you must "escape" them so that they are ignored by your shell.

The details vary with each shell but (in linux/UNIX) usually you can precede such a square bracket with a backslash <code>\</code> or put quotation marks around the square bracket, usually either "single" or "double" ones.

The Hourglass Graph report allows you to put a "note" at the top of the report and such a "note" is an example of a "list" option. Here is an example:
gramps -O "Family Tree 1" -a report -p name=hourglass_graph,note='[line one,line two]'
which shows that inside such a list different lines are separated by commas, and that spaces are acceptable since the quotation marks are already there for the square brackets.

But if you want to have a comma inside your report you have to somehow tell Gramps that comma is not one which separates lines. You do that by enclosing the line with the comma in quotation marks (either single or double).

But if you are already using a set of quotation marks (to enclose your square brackets) you have to use the other type to enclose
the line with your comma. Here is an example:
gramps -O "Family Tree 1" -a report -p name=hourglass_graph,note="['line one, also line one','line two, also line two']"

It is possible to include any character in a list but the details are beyond the scope of this command-line introduction to Gramps.

You will need to know the precise methods available in your particular command shell interpreter to include a character which is "special" to your shell or "special" to Gramps (like the comma in the example above) but in general you will have to "escape" it twice, once to your shell and once again to Gramps, since you don't want your shell to think it is some instruction it should pay attention to and you don't want Gramps to think that either.

==== tool action option ====
You can run most tools from the command line using the 'tool' action.
To see which ones, say:
gramps -O "Family Tree 1" -a tool -p show=all
To see a tool's available options, for instance the "verify" tool:
gramps -O "Family Tree 1" -a tool -p name=verify,show=all
To run a tool, for instance the "verify" tool:
gramps -O "Family Tree 1" -a tool -p name=verify

{{man note|Tool names|If the supplied tool_name does not correspond to any available tool, an error message will be printed followed by this list of available tools. 
<pre>
Available names are:
check - Check and Repair Database
chtype - Rename Event Types
dgenstats - Dump Gender Statistics
evname - Extract Event Description
rebuild - Rebuild Secondary Indexes
rebuild_genstats - Rebuild Gender Statistics
rebuild_refmap - Rebuild Reference Maps
reorder_ids - Reorder Gramps IDs
test_for_date_parser_and_displayer - Check Localized Date Displayer and Parser
testcasegenerator - Generate Testcases for Persons and Families
verify - Verify the Data
</pre>}}

==== book action option ====
{{man note|New feature|Added in Gramps 5.0}}
You can run books from the command line using the 'book' action.
To see which ones, say:
gramps -O "Family Tree 1" -a book
To see a book's available options, for instance a book called "mybook":
gramps -O "Family Tree 1" -a book -p name=mybook,show=all
To run a book, for instance a book called "mybook":
gramps -O "Family Tree 1" -a book -p name=mybook

{{man note|Book names|If the supplied book_name does not correspond to any available Book, an error message will be printed followed by this list of available Books. eg: Example listing only as the Books will be whatever you have named them. 
<pre>
Available names are:
Granny Jones
Grampa John
Smith Family History
</pre>}}

=== Force unlock option ===

*<code>-u</code>: you can extend the <code>-O</code> flag with <code>-u</code> to force a locked family to be unlocked. This allows you to recover from a crash that leaves the family tree (database) locked, from the command line.

An example (to unlock the "Family Tree 1" database):
:<code>gramps -O "Family Tree 1" -a report -u > /dev/null</code>

{{man note|Note|It is not possible to open family trees that need repair from the command line.}}

See also:
* [[Gramps_5.1_Wiki_Manual_-_Manage_Family_Trees#Unlocking_a_Family_Tree|Manage Family Trees:Unlocking a Family Tree]]

=== Configuration (config) option ===
When all configuration variable(s) are set Gramps will start with these new values.

These options can takes three forms:
{{man note|Note|Except for examples <tt>1</tt> and <tt>3.2</tt>, All the following examples, use <code>behavior.database-path</code> as the configuration variable to change.}}

;1) See all config values: <code>-s</code> or <code>--show</code>
 For example:
gramps --show
<pre>
Gramps config settings from /home/<~username>/.gramps/gramps50/gramps.ini:
export.proxy-order=[['privacy', 0], ['living', 0], ['person', 0], ['note', 0], ['reference', 0]]

database.compress-backup=True
database.backend='bsddb'
database.backup-path='/home/<~username>'
database.port=''
database.autobackup=0
database.path='/home/<~username>/.gramps/grampsdb'
database.host=''
database.backup-on-exit=True

geography.lock=False
....
</pre>

{{-}}

;2) See a single config value: <code>--config=database.path</code> or <code>-c database.path</code>
 For example:
gramps --config=database.path
<pre>
Current Gramps config setting: database.path:'/home/<~username>/.gramps/grampsdb'
</pre>

3) Set a value: <code>--config=behavior.database-path:'/media/mydb'</code> or <code>-c behavior.database-path:'/media/mydb'</code>
 For example:

3.1) Set a value to its default: <code>--config=behavior.database-path:DEFAULT</code> or <code>-c behavior.database-path:DEFAULT</code>
 For example:

3.2) Set more than one value: <code>--config=behavior.use-tips:False --config=behavior.autoload:True</code> or <code>-c behavior.use-tips:False -c behavior.autoload:True</code>
 For example:
=== Safe mode ===
<code>gramps -S</code> or <code>gramps --safe</code>

This CLI command starts Gramps as if it had never been installed before. In this mode, any previous family trees can still be loaded, as long as they were stored in the default folder. All other settings, filters, books, addons etc. are either cleared or returned to their default values. Other CLI commands can be used, or, if none, Gramps will start the GUI. Nothing except the actual family tree data is saved.

Note that this is typically used to see if Gramps behaves better when it is running as if with a totally 'clean' install. It is NOT permanent (if you want that see [[#Defaults|Defaults]] below), if you start Gramps normally after using this command all of your previous settings etc. are still there.

This actually works by setting the folder that Gramps uses to store its user data (except for family trees) to a temporary directory, which is deleted when Gramps closes.
=== Defaults ===
<code>gramps -D E</code> or <code>gramps --default=E</code>

This CLI command causes Gramps to clear out or return to defaults the desired settings.
The family tree databases are NOT cleared out or removed.
The sub-commands (replace the 'E' from the example command line above with one or more of
the subcommand characters) are:

*<code>A</code> Addons are cleared. Any installed addons are removed, along with their settings.
*<code>F</code> Filters are cleared. Any custom filters are removed.
*<code>P</code> Preferences are returned to their default values.
*<code>X</code> Books are cleared, Reports and Tools settings are returned to their default values.
*<code>Z</code> Old '.zip' files from family tree version upgrades are deleted.
*<code>E</code> Everything except the actual family tree data is returned to default settings. This does all of the above as well as a few more items; deletes thumbnails, maps, and the user CSS (used in web reports).

For example:
gramps -D AP
will cause Gramps to remove all the Addons and to reset Preferences to their default values.
== Operation ==

If the first argument on the command line does not start with a dash (i.e. no flag), Gramps will attempt to open the file with the name given by the first argument and start an interactive session, ignoring the rest of the command line arguments.

If the <code>-O</code> flag is given, then Gramps will try opening the supplied file name and then work with that data, as instructed by the further command line parameters.

{{man note|1=Note |2=Only one file can be opened in a single invocation of Gramps. If you need to get data from multiple sources, use the importing options by using <code>-i</code> flag.}}

With or without the <code>-O</code> flag, there could be multiple imports, exports, and actions specified further on the command line by using <code>-i</code> , <code>-e</code> , and <code>-a</code> flags.

The order of <code>-i</code> , <code>-e</code> , or <code>-a</code> options with respect to each does not matter. The actual execution order always is: all imports (if any) -> all exports (if any) -> all actions (if any).

{{man note| Note |But opening must always be first!}}

If no <code>-O</code> or <code>-i</code> option is given, Gramps will launch its main window and start the usual interactive session with the empty database, since there is no data to process, anyway. (Unless you have already expressed a "preference" that it start with the last database it used.)

If no <code>-e</code> or <code>-a</code> options are given, Gramps will launch its main window and start the usual interactive session with the database resulted from opening and all imports (if any). This database resides in a directory under the ''<code>~/.gramps/grampsdb/</code>'' directory.

Any errors encountered during import, export, or action, will be either dumped to stdout (if these are exceptions handled by Gramps) or to stderr (if these are not handled). Use usual shell redirections of stdout and stderr to save messages and errors in files.

== Examples ==

*To import four databases (whose formats can be determined from their names) and then check the resulting database for errors, one may type:

:<code>gramps -i file1.ged -i file2.gpkg -i ~/db3.gramps -i file4.wft -a check</code>

*To explicitly specify the formats in the above example, append filenames with appropriate -f options:

:<code>gramps -i file1.ged -f gedcom -i file2.gpkg -f gramps-pkg -i ~/db3.gramps -f gramps-xml -i file4.wft -f wft -a check</code>

*To record the database resulting from all imports, supply -e flag (use -f if the filename does not allow Gramps to guess the format):

:<code>gramps -i file1.ged -i file2.gpkg -e ~/new-package -f gramps-pkg</code>

*To save any error messages of the above example into files outfile and errfile, run:

:<code>gramps -i file1.ged -i file2.dpkg -e ~/new-package -f gramps-pkg >outfile 2>errfile </code>

*To import three databases and start interactive Gramps session with the result:

:<code>gramps -i file1.ged -i file2.gpkg -i ~/db3.gramps </code>

*To open a database and, based on that data, generate timeline report in PDF format putting the output into the my_timeline.pdf file:

:<code>gramps -O 'Family Tree 1' -a report -p name=timeline,off=pdf,of=my_timeline.pdf </code>

{{man tip|1=Listing report options |2=Use the <code>''name=timeline,show=all''</code> to find out about all available options for the timeline report. To find out details of a particular option, use <code>''show=option_name''</code> , e.g. <code>''name=timeline,show=off''</code> string. To learn about available report names, use <code>''name=show''</code> string.}}

*To convert the bsddb database on the fly to a .gramps xml file:

:<code>gramps -O 'Family Tree 1' -e output.gramps -f gramps-xml</code>

* To generate a web site into an other locale (in German):

:<code>LANGUAGE=de_DE; LANG=de_DE.UTF-8 gramps -O 'Family Tree 1' -a report -p name=navwebpage,target=/../de </code>

*Finally, to start normal interactive session type:

:<code>gramps</code>

== Environment variables==

{{man warn|Warning|Gramps can take advantage of the following [[Gramps_and_Windows#Environmental_Variables|environment variables]] ('''Only change them if you know what are you doing.''')}}

===GRAMPSHOME===
* '''GRAMPSHOME''' - if set, [[Gramps_and_Windows#Setting_the_configuration_path|override default path]] to profile allowing user to use an external network drive to store data and all settings. For technically advanced users who run multiple versions of Gramps, setting a different $GRAMPSHOME is a way to avoid interference between the different versions in the Gramps [[Gramps_Glossary#user_directory|User Directory]]. It can also be used to configure Gramps to [[Run_Gramps_from_a_portable_drive|run from a portable drive]] or to prepare for a [[Installation|manual installation]]. The path can also be used to configure the path to a [[Gramps_for_Windows_with_MSYS2#Keep_your_GRAMPSHOME_separate|separate test Tree]] or [[Getting_started_with_Gramps_development|development Tree]].

For example <pre>GRAMPSHOME=$HOME/familytrees/paternal</pre>

===LANG, LANGUAGE, LC_MESSAGE, LC_TIME ===
* '''LANG''', '''LANGUAGE''', '''LC_MESSAGES''', and '''LC_TIME''' - are used by Gramps to determine which language file(s) should be loaded. See locale(1) for a general discussion of '''LANG''', '''LC_MESSAGES''', and '''LC_TIME'''. Note that in addition to setting date formats (which are overridden in Gramps with Preferences settings) '''LC_TIME''' also sets the language used for words in dates like month and day names and ''in the context of dates'' words like ''about'', ''between'', and ''before''. '''LANGUAGE''' is a comma-separated list of language codes (''not locales'', though certain languages like pt_BR or cn_TW are regional variants) that sets a preference-ordered list of desired translations. It will override '''LANG''' but not '''LC_MESSAGES''' or '''LC_TIME'''.

{{man note|MacOSX|Because of the way launching with Finder works, the environment variables for the Gramps.app bundle are hard-coded in <code>Gramps.app/Contents/MacOS/Gramps</code>. If for some reason you need to change them, edit that file with TextEdit; be sure to save it back as plain text. See as well [[Run_GRAMPS_in_another_locale#Change_Mac_OS_X_application_defaults|setting locale]] for an alternative to using the '''LANG''' and '''LANGUAGE''' environment variables.}}

===GRAMPSI18N===
* [[Translating_Gramps#.24GRAMPSI18N_.28for_your_locale.29| $GRAMPSI18N (for your locale) ]] - The LANG assumes the Gramps translations are installed globally. If this is not the case, you need to [[Translating_Gramps#.24GRAMPSI18N_.28for_your_locale.29|give Gramps the directory]] where the translations will be found. This can be used to temporarily [[Howto:Change_the_language_of_reports|change the language for Reports]] being generated.

A translation is called <code>gramps.mo</code>, you can find it in Linux with the locate command. For example, if you have Swedish in directory <code>/home/me/gramps/mo/sv/gramps.mo</code>, you can direct Gramps there using:
GRAMPSI18N=/home/me/gramps/mo LC_ALL=C.UTF-8 LANG="sv" python3 gramps

===GRAMPSDIR===
* The environment variable GRAMPSDIR is the path to your [[Translating_Gramps#gramps.sh|Gramps directory]].

===GRAMPS_RESOURCES===
* The environment variable GRAMPS_RESOURCES is the path to Gramps built-in resources files. You should only change this if you are using Gramps from source code or a custom environment. An indicator that you need to set this variable is if you receive one of the following errors:
** ''Encoding error while parsing resource path''
** ''Failed to open resource file''
** ''Resource Path {invalid/path/to/resources} is invalid''
** ''Unable to determine resource path''

Example [[Linux:Build_from_source#Running_from_a_tarball_release|usage]]:
GRAMPS_RESOURCES=/home/username/gramps/branches/maintenance/gramps51/build/lib.linux-x86_64-2.7/ PYTHONPATH=$GRAMPS_RESOURCES:$PYTHONPATH ./gramps

{{-}}
{{man index|Gramps 5.1 Wiki Manual - Keybindings|Gramps 5.1 Wiki Manual - User Directory|5.1}}
{{languages|Gramps_5.1_Wiki_Manual_-_Command_Line}}
{{grampsmanualcopyright}}

[[Category:Documentation]]

Gramps 5.1 Wiki Manual - Command Line

2022-01-18T15:49:50Z

Codefarmer: Locating path to gramps executable on Windows

{{man index|Gramps 5.1 Wiki Manual - Keybindings|Gramps 5.1 Wiki Manual - User Directory|5.1}}
{{languages|Gramps_5.1_Wiki_Manual_-_Command_Line}}
{{#vardefine:chapter|C}}
{{#vardefine:figure|0}}
This appendix provides the reference to the command line capabilities available when launching Gramps from the terminal.

== Start Gramps through the Command Line ==

Normally Gramps is started through the graphical user interface (GUI) on [[Gramps_5.1_Wiki_Manual_-_Getting_started#Start_Gramps|your platform]].

It is also possible to start Gramps using a command line interface (CLI). CLI use can
* produce reports that are not available via the GUI,
* create reports, do conversions etc. without opening a window and
* can provide [[Gramps_5.1_Wiki_Manual_-_Main_Window#Seeing_all_the_error_messages|extra information]] in the event of problems.

This section of the user manual describes how to start Gramps through the CLI, and the features that are available.

The way you start Gramps through the CLI depends on the operating system you are using.

For simplicity of description, the examples of use below are written from the point of view of running Gramps on Linux. The examples would need to be changed for other platforms.

=== Linux ===

Only the Linux platform is officially supported as Gramps developers use and test the source code on that platform, fixing any problems that arise due to upgrades.

Assuming you have used the standard Package Manager (either through a CLI or a GUI) for your Linux distribution, you start Gramps through the CLI by typing
gramps

=== MS Windows ===

MS Windows is a [[Download|community supported]] platform. If you install the [[All_In_One_Gramps_Software_Bundle_for_Windows|Windows AIO bundle]], then this will place an icon on the desktop as well as a menu item in the 'Start' menu. However, the Gramps installation directory is not added to the system path and to run gramps via CLI, we need to know the path to that directory. There are several ways to find the path, including by examining the program's shortcut in the start menu, taskbar or the start menu, or by locating the running executable's path in Task Manager. In most cases the path will be the default as described below.

As an example, using GrampsAOI-{{template:Version windows AIO64}}_win64.exe installer and accepting the standard destination folder during installation, <code>C:\Program Files\GrampsAOI64-{{template:Version windows AIO64}}</code> would be the location for the Gramps executable. While not common, if you installed the 32-bit version of Gramps on a 64-bit OS, the path would be <code>C:\Program Files (x86)\GrampsAIO32-{{template:Version windows AIO32}}</code>. Finally, if you chose to install Gramps in a non-standard directory, use that folder path instead instead. Use Windows File Explorer to confirm that the path is correct before continuing on.

To find the path using a shortcut icon,
* Right-click on the <code>GrampsAIO64 {{template:Version windows AIO64}}-console</code> application, or the corresponding item in the Start menu.
* Note down the file location (its "Start in' directory).
* Select the full path and copy ({{man key press|Ctrl|c}}) it.

To run Gramps from the command line, you'll need to start a console window:
* From the Start menu, start cmd.exe.
* Change directory to the installation directory you located.
* Type in or paste the path, surrounding it in quotes if there are spaces.
* Press {{man key press|Enter}}.

For example, this might be:
cd "C:\Program Files\GrampsAOI64-{{template:Version windows AIO64}}"
gramps

You may use any of the command-line options along with this. For example, to get a detailed listing of all of the Family Tree databases in your default Family Tree folder, you would append <code>-L</code>
cd "C:\Program Files\GrampsAOI64-{{template:Version windows AIO64}}"
gramps -L

See example usage https://github.com/gramps-project/addons-source/pull/121

=== MacOS ===

MacOS is a [[Download|community supported]] platform. If you download the MacOS disk image (.dmg), then you simply drag the application to your application folder (or anywhere else you want to store it) and start Gramps by double clicking on the application in the normal way. The Homebrew package manager[https://github.com/Homebrew] also allows for installation of the application in the usual Applications folder.

To run from the command line, you'll need to start Terminal, found in the Utilities folder of the main Applications folder (/Applications/Utilities). Once you have a terminal window open, at the prompt type
/path/to/Gramps.app/Contents/MacOS/Gramps
If you installed Gramps in Applications along with most of your other apps, as suggested above, that would be
/Applications/Gramps.app/Contents/MacOS/Gramps
You may use any of the command-line options along with this. For example, to get a detailed listing of all of the Family Tree databases in your default Family Tree folder, you would use
/Applications/Gramps.app/Contents/MacOS/Gramps -L

There are other ways to install Gramps for MacOS, but these are much more complicated and are not covered here.

== Python options ==

In the examples of different platforms above, and also in commands in various files you may see some options after the 'python' command, for example '-EO' in
"python3 -EO ..\share\gramps\gramps.py -L

It is important to distinguish between the '''python options''' in this case:
-EO
and the '''Gramps options''', in this case
-L

The '''python options''' that you may come across are:
* <code>-E</code> Ignore all PYTHON* environment variables, e.g. <code>PYTHONPATH</code> and <code>PYTHONHOME</code>, that might be set.
* <code>-O</code> Turn on basic optimizations. This changes the filename extension for compiled (bytecode) files from <code>.pyc</code> to <code>.pyo</code>. See also PYTHONOPTIMIZE.

The <code>-O</code> optimise flag has a number of effects in Gramps:
* If it is not turned on, an additional {{man menu|[[Gramps_5.1_Wiki_Manual_-_Tools#Debug|Debug]]}} entry appears in the {{man menu|[[Gramps_5.1_Wiki_Manual_-_Tools|Tools]]}} menu.
* If it is not turned on, [[Logging_system#So_how_logging_works_in_Gramps_after_all.3F|info logging messages are output]].
* If it is not turned on, [[Debugging_Gramps#Add_debug_statements|debug statements]] may be activated.
* If it is not turned on, additional features are available in the [[Gramps_5.1_Wiki_Manual_-_Plugin_Manager|Plugin Manager]].

The '''Gramps options''' are described below.

== Available Gramps options ==

This section provides the reference list of all command line options available in Gramps. If you want to know more than just a list of options, see next sections: [[#Operation|Operation]] and [[#Examples| Examples]]. The summary below is printed by
gramps -h
or
gramps --help

<pre>
Usage: gramps.py [OPTION...]
--load-modules=MODULE1,MODULE2,... Dynamic modules to load

Help options
-?, --help Show this help message
--usage Display brief usage message

Application options
-O, --open=FAMILY_TREE Open Family Tree
-U, --username=USERNAME Database username
-P, --password=PASSWORD Database password
-C, --create=FAMILY_TREE Create on open if new Family Tree
-i, --import=FILENAME Import file
-e, --export=FILENAME Export file
-r, --remove=FAMILY_TREE_PATTERN Remove matching Family Tree(s) (use regular expressions)
-f, --format=FORMAT Specify Family Tree format
-a, --action=ACTION Specify action
-p, --options=OPTIONS_STRING Specify options
-d, --debug=LOGGER_NAME Enable debug logs
-l [FAMILY_TREE_PATTERN...] List Family Trees
-L [FAMILY_TREE_PATTERN...] List Family Trees in Detail
-t [FAMILY_TREE_PATTERN...] List Family Trees, tab delimited
-u, --force-unlock Force unlock of Family Tree
-s, --show Show config settings
-c, --config=[config.setting[:value]] Set config setting(s) and start Gramps
-y, --yes Don't ask to confirm dangerous actions (non-GUI mode only)
-q, --quiet Suppress progress indication output (non-GUI mode only)
-v, --version Show versions
-S, --safe Start Gramps in 'Safe mode'
(temporarily use default settings)
-D, --default=[APXFE] Reset settings to default;
A - addons are cleared
P - Preferences to default
X - Books are cleared, reports and tool settings to default
F - filters are cleared
E - Everything is set to default or cleared
</pre>

The usage message is as follows:

gramps --usage

<pre>
Example of usage of Gramps command line interface

1. To import four databases (whose formats can be determined from their names)
and then check the resulting database for errors, one may type:
gramps -i file1.ged -i file2.gpkg -i ~/db3.gramps -i file4.wft -a tool -p name=check.

2. To explicitly specify the formats in the above example, append filenames with appropriate -f options:
gramps -i file1.ged -f gedcom -i file2.gpkg -f gramps-pkg -i ~/db3.gramps -f gramps-xml -i file4.wft -f wft -a tool -p name=check.

3. To record the database resulting from all imports, supply -e flag
(use -f if the filename does not allow Gramps to guess the format):
gramps -i file1.ged -i file2.gpkg -e ~/new-package -f gramps-pkg

4. To save any error messages of the above example into files outfile and errfile, run:
gramps -i file1.ged -i file2.dpkg -e ~/new-package -f gramps-pkg >outfile 2>errfile

5. To import three databases and start interactive Gramps session with the result:
gramps -i file1.ged -i file2.gpkg -i ~/db3.gramps

6. To open a database and, based on that data, generate timeline report in PDF format
putting the output into the my_timeline.pdf file:
gramps -O 'Family Tree 1' -a report -p name=timeline,off=pdf,of=my_timeline.pdf

7. To generate a summary of a database:
gramps -O 'Family Tree 1' -a report -p name=summary

8. Listing report options
Use the name=timeline,show=all to find out about all available options for the timeline report.
To find out details of a particular option, use show=option_name , e.g. name=timeline,show=off string.
To learn about available report names, use name=show string.

9. To convert a Family Tree on the fly to a .gramps xml file:
gramps -O 'Family Tree 1' -e output.gramps -f gramps-xml

10. To generate a web site into an other locale (in German):
LANGUAGE=de_DE; LANG=de_DE.UTF-8 gramps -O 'Family Tree 1' -a report -p name=navwebpage,target=/../de

11. Finally, to start normal interactive session type:
gramps

Note: These examples are for bash shell.
Syntax may be different for other shells and for Windows.

</pre>

=== List options ===
Print a list of known family trees:

;Sparse
-l, List Family Trees

gramps -l

<pre>
List of known Family Trees in your database path

/home/<~username>/.gramps/grampsdb/5a46c1c3 with name "Example Family Tree"
</pre>
{{-}}

;Detailed
-L, List Family Trees in Detail

gramps -L

<pre>
Gramps Family Trees:
Family Tree "Example Family Tree":
Database: SQLite
Database module location: /usr/lib/python3.6/sqlite3/__init__.py
Database module version: 2.6.0
Database version: 3.21.0
Last accessed: 30/12/17 09:29:37
Locked?: False
Number of citations: 2854
Number of events: 3432
Number of families: 762
Number of media: 7
Number of notes: 19
Number of people: 2157
Number of places: 1294
Number of repositories: 3
Number of sources: 4
Number of tags: 2
Path: /home/<~username>/.gramps/grampsdb/5a46c1c3
Schema version: 18.0.0
</pre>

{{man note|Note that dates are shown in the default LOCALE format.|You change that at the system level. For example, on [[Gramps_Glossary#posix|POSIX]]-based systems you could use: <pre>LC_TIME=en_AU.UTF-8 gramps -L</pre>}}
{{-}}

=== Version options ===

-v or --version prints version of Gramps and dependencies,
information about environment settings and python and system paths

gramps -v

<pre>
Gramps Settings:
----------------
python : 3.7.5
gramps : 5.1.1
gtk++ : 3.24.12
pygobject : 3.34.0
pango : 1.42.3
cairo : 1.16.0
pycairo : 1.16.2
osmgpsmap : 1.0
GExiv2 : 0.10
ICU : 63.1
PyICU : 2.2
o.s. : linux
kernel : 5.3.0-24-generic

Environment settings:
---------------------
LANG : en_GB.UTF-8
LANGUAGE : en_GB:en
GRAMPSI18N: not set
GRAMPSHOME: not set
GRAMPSDIR : not set
PYTHONPATH:
/usr/lib/python3/dist-packages/gramps
/usr/bin
/usr/lib/python37.zip
/usr/lib/python3.7
/usr/lib/python3.7/lib-dynload
/usr/local/lib/python3.7/dist-packages
/usr/lib/python3/dist-packages

Non-python dependencies:
------------------------
Graphviz : 2.40
Ghostscr. : 9.27

System PATH env variable:
-------------------------
/usr/local/sbin
/usr/local/bin
/usr/sbin
/usr/bin
/sbin
/bin
/usr/games
/usr/local/games
/snap/bin

Databases:
-------------------------
bsddb :
version : 6.2.6
db version : 5.3.28
location : /usr/lib/python3/dist-packages/bsddb3/__init__.py
sqlite3 :
version : 3.29.0
py version : 2.6.0
location : /usr/lib/python3.7/sqlite3/__init__.py
</pre>

{{-}}

=== Format options ===

The format of any file destined for opening, importing, or exporting can be specified with the <pre>-f format</pre> option. The acceptable <tt>''format''</tt> values are listed below.

==== Full family tree support ====
These formats contain all your data that is present in a family tree.

* '''gramps''' - Gramps XML format: This format is available for import, and export. When not specified, it can be guessed if the filename ends with .gramps
* '''gpkg''' - Gramps package XML format: This format is available for import and export. When not specified, it can be guessed if the filename ends with .gpkg. This creates a zip package with your data as xml, and all your media files included
* '''grdb''' - pre Gramps 3.x database: This format is available for import to support the old file format of Gramps. Everything in the grdb file is imported. When not specified, it can be guessed if the filename ends with .grdb
* '''burn''' - GNOME iso burning: export, only available on GNOME where burn protocol exists

==== Reduced family tree support ====
These formats contain most, but not all data that can be created in Gramps

*'''ged''' - GEDCOM format: This format is available for import, and export. When not specified, it can be guessed if the filename ends with .ged
*'''gw''' - GeneWeb file: This format is available for import and export. When not specified, it can be guessed if the filename ends with .gw

==== Subset of your data ====
These formats contain a specific subset of your data

* '''csv''' - Comma Separated Value: This format is available for import and export. Be careful however, import must be as values created by the export function. Only a part of your data is contained in the output.
* '''vcf''' - VCard format: import and export
* '''vcs''' - VCalendar format: export
* '''def''' - old Pro-Gen format: import
* '''wft''' - Web Family Tree: This format is available for export only. When not specified, it can be guessed if the filename ends with .wft

=== Opening options ===

You can open a family tree, or you can ''open'' a file by importing it in an empty family tree.

To let Gramps handle this automatically, just supply the family tree or filename you want to open:

python gramps.py 'My Fam Tree'
python gramps.py JohnDoe.ged

The first opens a family tree, the second imports a GEDCOM into an empty family tree.

Additionally, you can pass Gramps the name of the family tree to be opened:

* use this option : <code>-O famtree</code> or <code>--open=famtree</code>

<code>-O</code>, Open of a family tree. This can be done also by just typing the name (name or database dir)

Examples:
python gramps.py 'Family Tree 1'
python gramps.py /home/cristina/.gramps/grampsdb/47320f3d
python gramps.py -O 'Family Tree 1'
python gramps.py -O /home/cristina/.gramps/grampsdb/47320f3d

{{Man tip| Tip |If no option is given, just a name, Gramps will ignore the rest of the command line arguments. Use the <code>-O</code> flag to open, <code>-i</code> to import, and do something with the data.}}

{{Man tip| Tip |Only family trees can be opened directly. For other formats, you will need to use the import option which will set up the empty database and then import data into it.}}

{{Man tip| Tip |Only a single family tree can be opened. If you need to combine data from several sources, you will need to use the import option.}}

=== Import options ===

The files destined for import can be specified with the <code>-i filename</code> or <code>--import=filename</code> option. The format can be specified with the <code>-f format</code> or <code>--format=format</code> option, immediately following the ''filename'' . If not specified, the guess will be attempted based on the ''filename''.

Example:
python gramps.py -i 'Family Tree 1' -i 'Family Tree 2'
python gramps.py -i test.grdb -i data.gramps

{{man tip | Tip |More than one file can be imported in one command. If this is the case, Gramps will incorporate the data from the next file into the database available at the moment.}}

When more than one input file is given, each has to be preceded by <code>-i</code> flag. The files are imported in the specified order, i.e. <code> -i file1 -i file2 </code> and <code> -i file2 -i file1 </code> might produce different Gramps IDs in the resulting database.

=== Export options ===

The files destined for export can be specified with the <code>-e filename</code> or <code>--export=filename</code> option. The format can be specified with the <code>-f</code> option immediately following the ''filename'' . If not specified, the guess will be attempted based on the ''filename'' . For iso format, the ''filename'' is actually the name of directory the Gramps database will be written into. For gramps-xml, gpkg, gedcom, wft, geneweb, and gramps-pkg, the ''filename'' is the name of the resulting file.

-e, export a family tree in required format. It is not possible to export to a family tree.

Example:
python gramps.py -i 'Family Tree 1' -i test.grdb -f grdb -e mergedDB.gramps
Note that above does not change 'Family Tree 1' as everything happens via a temporary database, whereas:
python gramps.py -O 'Family Tree 1' -i test.grdb -f grdb -e mergedDB.gramps
will import test.grdb into Family Tree 1, and then export to a file !

{{man tip| Exporting more files |More than one file can be exported in one command. If this is the case, Gramps will attempt to write several files using the data from the database available at the moment.}}

When more than one output file is given, each has to be preceded by <code>-e</code> flag. The files are written one by one, in the specified order.

=== Action options ===

The action to perform on the imported data can be specified with the <code>-a action</code> or <code>--action=action</code> option. This is done after all imports are successfully completed.

The following actions remain the same:

*''report'': This action allows producing reports from the command line.

*''tool'': This action allows to run a tool from the command line.

Reports and tools generally have many options of their own, so these actions should be followed by the report/tool option string. The string is given using the <code>-p option_string</code> or <code>--options=option_string</code> option.

The actions available in older versions of Gramps which were relocated in Gramps 3.3 are:

*''summary'': This action was the same as {{man menu|Reports ->View ->Summary}}. In Gramps 3.3 it was replaced by (or renamed to) '''-a report -p name=summary'''.

*''check'': This action was the same as {{man menu|Tools ->Database Processing ->Check and Repair}}. In Gramps 3.3 it was replaced by (or renamed to) '''-a tool -p name=check'''.

==== report action option ====
You can generate most reports from the command line using the report action.

An example:
gramps -O "Family Tree 1" -a report -p "name=family_group,style=default,off=html,of=test.html"

You can provide the css style to use here with the css option:
gramps -O "Family Tree 1" -a report -p "name=family_group,style=default,off=html,of=test.html,css=Web_Nebraska.css"
or without css in the html output:
gramps -O "Family Tree 1" -a report -p "name=family_group,style=default,off=html,of=test.html,css="

{{man tip| Report option string |The report option string should satisfy the following conditions: It must not contain any spaces (due to the general nature of the command line interface). If some arguments need to include spaces, the string should be enclosed with quotation marks. Option string must list pairs of option names and values. Within a pair, option name and value must be separated by the equal sign. Different pairs must be separated by commas.}}

Most of the report options are specific for every report. However, there are some common options.

*<code>name=report_name</code>: This mandatory option determines which report will be generated.
{{man note|Report names|If the supplied report_name does not correspond to any available report, an error message will be printed followed by this list of available reports. 
<pre>
Available names are:
ancestor_chart - Ancestor Tree
ancestor_report - Ahnentafel Report
AncestorFill - AncestorFill
birthday_report - Birthday and Anniversary Report
calendar - Calendar
d3-ancestralcollapsibletree - Ancestral Collapsible Tree
d3-ancestralfanchart - Ancestral Fan Chart
d3-descendantindentedtree - Descendant Indented Tree
database-differences-report - Database Differences Report
denominoviso - DenominoViso
descend_chart - Descendant Tree
descend_report - Descendant Report
DescendantBook - Descendant Book
Descendants Lines - Descendants Lines
det_ancestor_report - Detailed Ancestral Report
det_descendant_report - Detailed Descendant Report
DetailedDescendantBook - Detailed Descendant Book
double_cousins - Double Cousins
DynamicWeb - Dynamic Web Report
endofline_report - End of Line Report
family_descend_chart - Family Descendant Tree
family_group - Family Group Report
familylines_graph - Family Lines Graph
FamilySheet - Family Sheet
FamilyTree - Family Tree
fan_chart - Fan Chart
gt_ancestor - Ancestor Tree
gt_descendant - Descendant Tree
gt_grandparent - Grandparent Tree
gt_sandclock - Sandclock Tree
gt_sandclock_family - Sandclock Tree for a Family
Heatmap - Heatmap
hourglass_graph - Hourglass Graph
indiv_complete - Complete Individual Report
kinship_report - Kinship Report
LastChangeReport - Last Change Report
LinesOfDescendency - Lines of Descendency Report
ListeEclair - Tiny Tafel
MediaReport - Media Report
navwebpage - Narrated Web Site
networkchart - Network Chart
notelinkreport - Note Link Report
number_of_ancestors - Number of Ancestors Report
PedigreeChart - Pedigree Chart
PersonEverythingReport - PersonEverything Report
place_report - Place Report
records - Records Report
rel_graph - Relationship Graph
Repositories Report - Repositories Report
SourcesCitationsReport - Sources and Citations Report
statistics_chart - Statistics Charts
summary - Database Summary Report
tag_report - Tag Report
timeline - Timeline Chart
TimePedigreeHTML - Timeline Pedigree Report
TodoReport - Todo Report
WebCal - Web Calendar
</pre>}}
*<code>of=</code>: output filename and optional destination folder/directory eg: <code>of="C:\Users\<username>\Desktop\FamilyTree.odt"</code>
*<code>off=</code>: output format. These are the extension an output format makes available, eg, pdf, html, doc, ...
*<code>style=</code>: for text reports, the stylesheet to use. Defaults to 'default'.
*<code>show=all</code>: This will produce the list of names for all options available for a given report.
*<code>show=option_name</code>: This will print the description of the functionality supplied by the option_name, as well as what are the acceptable types and values for this option.

So, to learn to use a report, do for example:
gramps -O "Family Tree 1" -a report -p "name=family_group,show=all"

{{man tip| Tip |If an option is not supplied, the last used value will be used. If this report has never been generated before, then the value from last generated report will be used when applicable. Otherwise, the default value will be used.}}

When more than one output action is given, each has to be preceded by <code>-a</code> flag. The actions are performed one by one, in the specified order.

{{man tip| lists |Some reports have options or arguments which are interpreted (by the report) to be on multiple lines. For instance some reports allow you to format how the information will be shown, perhaps with a name on one line and the person's birth date on the next line. Such multiple-line options or arguments are called "lists" by Gramps.}}

On the command line such lists must always start with a left square bracket <code>[</code> and must always end with a right square bracket <code>]</code> but since such square brackets are usually "special" to the "shell" (they mean something to the command interpreter
you are typing the command to), you must "escape" them so that they are ignored by your shell.

The details vary with each shell but (in linux/UNIX) usually you can precede such a square bracket with a backslash <code>\</code> or put quotation marks around the square bracket, usually either "single" or "double" ones.

The Hourglass Graph report allows you to put a "note" at the top of the report and such a "note" is an example of a "list" option. Here is an example:
gramps -O "Family Tree 1" -a report -p name=hourglass_graph,note='[line one,line two]'
which shows that inside such a list different lines are separated by commas, and that spaces are acceptable since the quotation marks are already there for the square brackets.

But if you want to have a comma inside your report you have to somehow tell Gramps that comma is not one which separates lines. You do that by enclosing the line with the comma in quotation marks (either single or double).

But if you are already using a set of quotation marks (to enclose your square brackets) you have to use the other type to enclose
the line with your comma. Here is an example:
gramps -O "Family Tree 1" -a report -p name=hourglass_graph,note="['line one, also line one','line two, also line two']"

It is possible to include any character in a list but the details are beyond the scope of this command-line introduction to Gramps.

You will need to know the precise methods available in your particular command shell interpreter to include a character which is "special" to your shell or "special" to Gramps (like the comma in the example above) but in general you will have to "escape" it twice, once to your shell and once again to Gramps, since you don't want your shell to think it is some instruction it should pay attention to and you don't want Gramps to think that either.

==== tool action option ====
You can run most tools from the command line using the 'tool' action.
To see which ones, say:
gramps -O "Family Tree 1" -a tool -p show=all
To see a tool's available options, for instance the "verify" tool:
gramps -O "Family Tree 1" -a tool -p name=verify,show=all
To run a tool, for instance the "verify" tool:
gramps -O "Family Tree 1" -a tool -p name=verify

{{man note|Tool names|If the supplied tool_name does not correspond to any available tool, an error message will be printed followed by this list of available tools. 
<pre>
Available names are:
check - Check and Repair Database
chtype - Rename Event Types
dgenstats - Dump Gender Statistics
evname - Extract Event Description
rebuild - Rebuild Secondary Indexes
rebuild_genstats - Rebuild Gender Statistics
rebuild_refmap - Rebuild Reference Maps
reorder_ids - Reorder Gramps IDs
test_for_date_parser_and_displayer - Check Localized Date Displayer and Parser
testcasegenerator - Generate Testcases for Persons and Families
verify - Verify the Data
</pre>}}

==== book action option ====
{{man note|New feature|Added in Gramps 5.0}}
You can run books from the command line using the 'book' action.
To see which ones, say:
gramps -O "Family Tree 1" -a book
To see a book's available options, for instance a book called "mybook":
gramps -O "Family Tree 1" -a book -p name=mybook,show=all
To run a book, for instance a book called "mybook":
gramps -O "Family Tree 1" -a book -p name=mybook

{{man note|Book names|If the supplied book_name does not correspond to any available Book, an error message will be printed followed by this list of available Books. eg: Example listing only as the Books will be whatever you have named them. 
<pre>
Available names are:
Granny Jones
Grampa John
Smith Family History
</pre>}}

=== Force unlock option ===

*<code>-u</code>: you can extend the <code>-O</code> flag with <code>-u</code> to force a locked family to be unlocked. This allows you to recover from a crash that leaves the family tree (database) locked, from the command line.

An example (to unlock the "Family Tree 1" database):
:<code>gramps -O "Family Tree 1" -a report -u > /dev/null</code>

{{man note|Note|It is not possible to open family trees that need repair from the command line.}}

See also:
* [[Gramps_5.1_Wiki_Manual_-_Manage_Family_Trees#Unlocking_a_Family_Tree|Manage Family Trees:Unlocking a Family Tree]]

=== Configuration (config) option ===
When all configuration variable(s) are set Gramps will start with these new values.

These options can takes three forms:
{{man note|Note|Except for examples <tt>1</tt> and <tt>3.2</tt>, All the following examples, use <code>behavior.database-path</code> as the configuration variable to change.}}

;1) See all config values: <code>-s</code> or <code>--show</code>
 For example:
gramps --show
<pre>
Gramps config settings from /home/<~username>/.gramps/gramps50/gramps.ini:
export.proxy-order=[['privacy', 0], ['living', 0], ['person', 0], ['note', 0], ['reference', 0]]

database.compress-backup=True
database.backend='bsddb'
database.backup-path='/home/<~username>'
database.port=''
database.autobackup=0
database.path='/home/<~username>/.gramps/grampsdb'
database.host=''
database.backup-on-exit=True

geography.lock=False
....
</pre>

{{-}}

;2) See a single config value: <code>--config=database.path</code> or <code>-c database.path</code>
 For example:
gramps --config=database.path
<pre>
Current Gramps config setting: database.path:'/home/<~username>/.gramps/grampsdb'
</pre>

3) Set a value: <code>--config=behavior.database-path:'/media/mydb'</code> or <code>-c behavior.database-path:'/media/mydb'</code>
 For example:

3.1) Set a value to its default: <code>--config=behavior.database-path:DEFAULT</code> or <code>-c behavior.database-path:DEFAULT</code>
 For example:

3.2) Set more than one value: <code>--config=behavior.use-tips:False --config=behavior.autoload:True</code> or <code>-c behavior.use-tips:False -c behavior.autoload:True</code>
 For example:
=== Safe mode ===
<code>gramps -S</code> or <code>gramps --safe</code>

This CLI command starts Gramps as if it had never been installed before. In this mode, any previous family trees can still be loaded, as long as they were stored in the default folder. All other settings, filters, books, addons etc. are either cleared or returned to their default values. Other CLI commands can be used, or, if none, Gramps will start the GUI. Nothing except the actual family tree data is saved.

Note that this is typically used to see if Gramps behaves better when it is running as if with a totally 'clean' install. It is NOT permanent (if you want that see [[#Defaults|Defaults]] below), if you start Gramps normally after using this command all of your previous settings etc. are still there.

This actually works by setting the folder that Gramps uses to store its user data (except for family trees) to a temporary directory, which is deleted when Gramps closes.
=== Defaults ===
<code>gramps -D E</code> or <code>gramps --default=E</code>

This CLI command causes Gramps to clear out or return to defaults the desired settings.
The family tree databases are NOT cleared out or removed.
The sub-commands (replace the 'E' from the example command line above with one or more of
the subcommand characters) are:

*<code>A</code> Addons are cleared. Any installed addons are removed, along with their settings.
*<code>F</code> Filters are cleared. Any custom filters are removed.
*<code>P</code> Preferences are returned to their default values.
*<code>X</code> Books are cleared, Reports and Tools settings are returned to their default values.
*<code>Z</code> Old '.zip' files from family tree version upgrades are deleted.
*<code>E</code> Everything except the actual family tree data is returned to default settings. This does all of the above as well as a few more items; deletes thumbnails, maps, and the user CSS (used in web reports).

For example:
gramps -D AP
will cause Gramps to remove all the Addons and to reset Preferences to their default values.
== Operation ==

If the first argument on the command line does not start with a dash (i.e. no flag), Gramps will attempt to open the file with the name given by the first argument and start an interactive session, ignoring the rest of the command line arguments.

If the <code>-O</code> flag is given, then Gramps will try opening the supplied file name and then work with that data, as instructed by the further command line parameters.

{{man note|1=Note |2=Only one file can be opened in a single invocation of Gramps. If you need to get data from multiple sources, use the importing options by using <code>-i</code> flag.}}

With or without the <code>-O</code> flag, there could be multiple imports, exports, and actions specified further on the command line by using <code>-i</code> , <code>-e</code> , and <code>-a</code> flags.

The order of <code>-i</code> , <code>-e</code> , or <code>-a</code> options with respect to each does not matter. The actual execution order always is: all imports (if any) -> all exports (if any) -> all actions (if any).

{{man note| Note |But opening must always be first!}}

If no <code>-O</code> or <code>-i</code> option is given, Gramps will launch its main window and start the usual interactive session with the empty database, since there is no data to process, anyway. (Unless you have already expressed a "preference" that it start with the last database it used.)

If no <code>-e</code> or <code>-a</code> options are given, Gramps will launch its main window and start the usual interactive session with the database resulted from opening and all imports (if any). This database resides in a directory under the ''<code>~/.gramps/grampsdb/</code>'' directory.

Any errors encountered during import, export, or action, will be either dumped to stdout (if these are exceptions handled by Gramps) or to stderr (if these are not handled). Use usual shell redirections of stdout and stderr to save messages and errors in files.

== Examples ==

*To import four databases (whose formats can be determined from their names) and then check the resulting database for errors, one may type:

:<code>gramps -i file1.ged -i file2.gpkg -i ~/db3.gramps -i file4.wft -a check</code>

*To explicitly specify the formats in the above example, append filenames with appropriate -f options:

:<code>gramps -i file1.ged -f gedcom -i file2.gpkg -f gramps-pkg -i ~/db3.gramps -f gramps-xml -i file4.wft -f wft -a check</code>

*To record the database resulting from all imports, supply -e flag (use -f if the filename does not allow Gramps to guess the format):

:<code>gramps -i file1.ged -i file2.gpkg -e ~/new-package -f gramps-pkg</code>

*To save any error messages of the above example into files outfile and errfile, run:

:<code>gramps -i file1.ged -i file2.dpkg -e ~/new-package -f gramps-pkg >outfile 2>errfile </code>

*To import three databases and start interactive Gramps session with the result:

:<code>gramps -i file1.ged -i file2.gpkg -i ~/db3.gramps </code>

*To open a database and, based on that data, generate timeline report in PDF format putting the output into the my_timeline.pdf file:

:<code>gramps -O 'Family Tree 1' -a report -p name=timeline,off=pdf,of=my_timeline.pdf </code>

{{man tip|1=Listing report options |2=Use the <code>''name=timeline,show=all''</code> to find out about all available options for the timeline report. To find out details of a particular option, use <code>''show=option_name''</code> , e.g. <code>''name=timeline,show=off''</code> string. To learn about available report names, use <code>''name=show''</code> string.}}

*To convert the bsddb database on the fly to a .gramps xml file:

:<code>gramps -O 'Family Tree 1' -e output.gramps -f gramps-xml</code>

* To generate a web site into an other locale (in German):

:<code>LANGUAGE=de_DE; LANG=de_DE.UTF-8 gramps -O 'Family Tree 1' -a report -p name=navwebpage,target=/../de </code>

*Finally, to start normal interactive session type:

:<code>gramps</code>

== Environment variables==

{{man warn|Warning|Gramps can take advantage of the following [[Gramps_and_Windows#Environmental_Variables|environment variables]] ('''Only change them if you know what are you doing.''')}}

===GRAMPSHOME===
* '''GRAMPSHOME''' - if set, [[Gramps_and_Windows#Setting_the_configuration_path|override default path]] to profile allowing user to use an external network drive to store data and all settings. For technically advanced users who run multiple versions of Gramps, setting a different $GRAMPSHOME is a way to avoid interference between the different versions in the Gramps [[Gramps_Glossary#user_directory|User Directory]]. It can also be used to configure Gramps to [[Run_Gramps_from_a_portable_drive|run from a portable drive]] or to prepare for a [[Installation|manual installation]]. The path can also be used to configure the path to a [[Gramps_for_Windows_with_MSYS2#Keep_your_GRAMPSHOME_separate|separate test Tree]] or [[Getting_started_with_Gramps_development|development Tree]].

For example <pre>GRAMPSHOME=$HOME/familytrees/paternal</pre>

===LANG, LANGUAGE, LC_MESSAGE, LC_TIME ===
* '''LANG''', '''LANGUAGE''', '''LC_MESSAGES''', and '''LC_TIME''' - are used by Gramps to determine which language file(s) should be loaded. See locale(1) for a general discussion of '''LANG''', '''LC_MESSAGES''', and '''LC_TIME'''. Note that in addition to setting date formats (which are overridden in Gramps with Preferences settings) '''LC_TIME''' also sets the language used for words in dates like month and day names and ''in the context of dates'' words like ''about'', ''between'', and ''before''. '''LANGUAGE''' is a comma-separated list of language codes (''not locales'', though certain languages like pt_BR or cn_TW are regional variants) that sets a preference-ordered list of desired translations. It will override '''LANG''' but not '''LC_MESSAGES''' or '''LC_TIME'''.

{{man note|MacOSX|Because of the way launching with Finder works, the environment variables for the Gramps.app bundle are hard-coded in <code>Gramps.app/Contents/MacOS/Gramps</code>. If for some reason you need to change them, edit that file with TextEdit; be sure to save it back as plain text. See as well [[Run_GRAMPS_in_another_locale#Change_Mac_OS_X_application_defaults|setting locale]] for an alternative to using the '''LANG''' and '''LANGUAGE''' environment variables.}}

===GRAMPSI18N===
* [[Translating_Gramps#.24GRAMPSI18N_.28for_your_locale.29| $GRAMPSI18N (for your locale) ]] - The LANG assumes the Gramps translations are installed globally. If this is not the case, you need to [[Translating_Gramps#.24GRAMPSI18N_.28for_your_locale.29|give Gramps the directory]] where the translations will be found. This can be used to temporarily [[Howto:Change_the_language_of_reports|change the language for Reports]] being generated.

A translation is called <code>gramps.mo</code>, you can find it in Linux with the locate command. For example, if you have Swedish in directory <code>/home/me/gramps/mo/sv/gramps.mo</code>, you can direct Gramps there using:
GRAMPSI18N=/home/me/gramps/mo LC_ALL=C.UTF-8 LANG="sv" python3 gramps

===GRAMPSDIR===
* The environment variable GRAMPSDIR is the path to your [[Translating_Gramps#gramps.sh|Gramps directory]].

===GRAMPS_RESOURCES===
* The environment variable GRAMPS_RESOURCES is the path to Gramps built-in resources files. You should only change this if you are using Gramps from source code or a custom environment. An indicator that you need to set this variable is if you receive one of the following errors:
** ''Encoding error while parsing resource path''
** ''Failed to open resource file''
** ''Resource Path {invalid/path/to/resources} is invalid''
** ''Unable to determine resource path''

Example [[Linux:Build_from_source#Running_from_a_tarball_release|usage]]:
GRAMPS_RESOURCES=/home/username/gramps/branches/maintenance/gramps51/build/lib.linux-x86_64-2.7/ PYTHONPATH=$GRAMPS_RESOURCES:$PYTHONPATH ./gramps

{{-}}
{{man index|Gramps 5.1 Wiki Manual - Keybindings|Gramps 5.1 Wiki Manual - User Directory|5.1}}
{{languages|Gramps_5.1_Wiki_Manual_-_Command_Line}}
{{grampsmanualcopyright}}

[[Category:Documentation]]

Addon:Import Merge Tool

2022-01-16T21:34:24Z

Codefarmer: FAQ: When would it make sense to use 'Merge Original' vs 'Merge Imported'?

{{Third-party plugin}}
{{man tip|Released for Gramps 5.0.x or greater versions}}
[[File:ImportMerge.png|thumb|right|350px|Import and Merge tool]]
The Import and Merge tool will {{man label|Import and merge a Gramps XML}} family tree derived from your own [[How_to_make_a_backup|Gramps XML family tree]] backup file.
== Purpose of this tool ==
This tool was specifically written to make importing and merging a Gramps [[Genealogy_Glossary#family_tree|Tree]] derived from your own Tree easier.

Make no mistake, merging is '''''hard'''''! And this tool is not magic, it does not make the process simple but it ''is'' easier than the alternatives.

{{man note|Important Note|This tool this requires that the Family Tree being merged must be a Gramps Family Tree ''derived from a version'' of the currently loaded Family Tree.}}

A situation occurs occasionally after giving someone a copy of your tree in our native [[Gramps XML]] format. Then each person makes changes to the copy in their possession using Gramps locally. (You can verify the Trees differ and log those revisions with the [[Addon:Database_Differences_Report|Database Differences]] add-on report.)

Programmers call this a 'fork.' (As in: when travelers come to a 'fork in the road' and each chooses different paths.) But the bottom line is that you now have two tree variants derived from a common Tree and you want share your updated Tree. You can't just give the person a fresh copy of your Tree because then their changes would be overwritten.

At some point, you may want to merge the forks into a common tree... without losing the useful changes from either tree. That synchronization is what this tool is designed to facilitate. It depends on the two Trees sharing common internal handles (not just the user-editable IDs) to simplify ignoring unchanged records. Then the tool focuses you on just the changes.

But say the other user doesn't use Gramps, so you exported with [[Gramps_and_GEDCOM|GEDCOM]] (or another format) and got it back? Sorry... this tool won't be any easier than a manual merge after a standard import. You'd still need to hand compare every record.

The derived trees need not be limited to those edited by someone else. I often take a copy of my tree on my laptop when traveling and sometimes I make updates while on the road. But then I may forget to copy it back to my home desktop computer until after I've made more updates. This tool helps to merge these back together.
{{man warn|1=Warning: Data Corruption Risk |2=Mass changes mean more potential for mangling the data. Back up your current tree BEFORE using this tool to merge. If something goes wrong, you will have a way to go back and start over. See [[How to make a backup|make a Gramps XML backup]].}}

==Usage==
The tool can be installed like any other Addon; see {{man label|[[Third-party_Addons#Installing_Addons_in_Gramps|Installing Addons in Gramps]]}}

Once installed, it is run by using the {{man menu|Tools -> Family Tree Processing -> Import and Merge tool...}}.
=== Running the Import Merge tool ===
The tool will start with an 'Undo history warning' that suggest that you back up your work.

You are then presented with the import file dialog, which shows '.gramps' files from your import location.

When you have selected a file to import, the main tool window comes up and some progress meters pop up indicating the import and comparison process. When this is complete you end up with a three part window. The bottom part provides control and 'Action' buttons and a hint that changes depending on what you are doing.

=== Top Pane ===
The top pane is a scrollable and selectable view of individual items that were found to be different in your import. Items that were the same (since they were derived from the common Gramps tree) are not shown.

[[File:ImportMerge.png|thumb|right|569px|Import and Merge tool]]
The top pane shows a 'Status' which is one of '''Different''', '''Added''', or '''Missing'''. '''Different''' items were found in both the current and imported trees, but had been changed in some way. ''Added'' items are found only in your imported tree. And '''Missing''' items were found in your current tree, but not in the imported tree.

The top pane also shows the ''Object'' type ('''Person''', '''Family''', '''Media''' etc.), its Gramps ''ID'', an ''Object Name or Description'', and the selected ''Action'' (more later).

You can search for items by Name by just typing characters to match. The top pane must be active for this to work. For example if you are looking for 'Smith, Magnes' in the 'sample.gramps' tree, you could type 'smi' which would jump the selection to the first of the lines containing these characters, and then use cursor up/down keys to find the 'Smith' you are looking for. Or type 'magn' which is more likely to land on the right place.

You can search for items by 'ID' field by typing '#' and then the characters to match. For example type '#I0103' to search for the individual with ID I0103.

You can sort the top pane by ''Status'' (''Object'' will be a sub-sort), ''Object'', ''ID'', ''Object Name/Description'' (will be grouped by ''Object'') and ''Action''. Click on the column header to change the sort.

=== Lower Pane ===
When an item in the top pane is selected, the lower pane shows the specific differences. If no ''Action'' is made yet, the pane will show the 'Original >>' and 'Imported >>' state for each sub-object and item that has a difference. If an ''Action'' has been selected, the pane also includes a 'Result >>' for each sub-object and item that has a difference.

Sometimes it may be difficult to determine enough about the difference to figure out what is going on. If so, you can check the {{man label|Show more details}} checkbox to see more about the difference.

The lower pane tries to present the information as concisely but informatively as possible. Apologies if the information seems a bit hard to interpret at times. One area that might be confusing is when there are differences in 'lists'. Many of Gramps objects have lists of other objects, families have lists of children, persons have lists of events or notes etc. When a list has changes, the left side will have a list position number preceded by '#'. For example:
{|
|Person, Event References #1, Event
| Original >> 
|your tree Event: [E0012] Death: Smith Gus
|-
|
| Imported >> 
|your tree Event: [E0011] Birth: Smith Gus
|-
|Person, Event References #2, Event
| Original >> 
|your tree Event: [E0011] Birth: Smith Gus
|-
|
| Imported >> 
|your tree Event: [E0012] Death: Smith Gus
|}
In this example list of event references, the imported tree somehow got the Birth and Death events swapped, compared to the original tree.

==== Control buttons ====

{{man button|Help}} brings up this wiki.

{{man button|Edit import}} allows editing of the selected item. Any changes are temporarily saved in your imported data, and will be kept only if that data is merged into your current tree. If your editing creates new items, they will appear in the top pane list when you finish editing. Changes here cause the 'Action' to be cleared, so be sure to choose an Action when finished.

{{man button|Unmark}} clears any current Action. If an item remains unmarked when you are done, it will be treated as if 'Ignored', that is, there will be no changes to your tree for that item.

{{man button|Ignore}} sets the action for the item so that there will be no changes to your tree for that item. This is the same as leaving the item unmarked, but makes it clear that you have looked at that item.

{{man button|Done}} tells the tool that you are finished marking the various actions. The tool will bring up a confirmation dialog, allowing you to save your work, cancel and return to marking, or abandon it.

The remaining buttons are considered 'Actions' and depend on the Status of the item.

{{man button|Add}} appears for items with an 'Added' status. When added, the imported data will be added to your current tree.

{{man button|Delete}} appears for items with a 'Missing' status. When selected, the data in your tree for this item will be deleted.

{{man button|Replace}} appears for items with a 'Different' status. When replaced, the imported data for the item will completely replace the same data in your current tree.

{{man button|Merge Original}} appears for items with a 'Different' status. When selected, the imported data for the item will be merged with the original tree and the IDs of the original item are retained. The portions of the data that cannot be merged will remain as it is in your current tree data.

{{man button|Merge Import}} appears for items with a 'Different' status. When selected, the imported data for the item will be merged with the original tree and the IDs of the imported item are used. The portions of the data that cannot be merged will be replaced by the import data.

When you select an 'Action' with one of the buttons, a hint will appear that states the action in more detail.

You can change the 'Action' at any time on any item, it may be instructive to see the results of choosing the various choices in the lower pane.

In general I recommend that you start marking your items with the 'Different' items first. Within these, doing '''Families''' and '''Persons''' first will usually minimize the amount of work to merge your tree. This tool starts up with the sort set to put these items first, so starting at the top is easy.

=== Automatic Mark ===

This tool includes the ability to automatically mark those items that are 'referred to' by the item you are currently marking. For Example, if you {{man button|Add}} a person, the events, notes, media, citations and families that the person refers to will also be added. The same process is applied for each of the various 'Action' buttons.

The marks that are automatically generated are shown in the top pane action column with a '*' preceding the action.

Occasionally you may mark items that create a conflict in the automatic marking. For example you {{man button|Add}} a person that refers to a media, and then later {{man button|Ignore}} a person that also refers to the same media. In this case, the media item will be marked with a '?' and the action that tends to conserve more data will be used. This means that Adds have priority over Ignore, Ignore over Delete etc.

You should review any items marked this way to make sure that you agree with the program.

Note that families and persons in particular usually have a lot of references to other families or persons. In fact if your imported file contains a whole new branch of your family tree, selecting any one of the people or families in that branch will automatically mark all the new people and families at once. This is usually desirable, but not always.

==== Automatic mark with Families ====
This tool is not ideal for selecting only parts of a tree for merging, but it can be done. If you wish to include a person, but not his family (spouse and children) then you can uncheck the {{man label|Automark Families}} checkbox. This applies to all persons found via the Automark as well. The effect is that you can get ancestors (if {{man label|Automark Parent Families}} is checked) included but not all the descendants of those ancestors.

If you wish to get a set of spouses and descendants included when adding a person but not all the ancestors of the spouses, then you can uncheck the {{man label|Automark Parent Families}} checkbox and leave the {{man label|Automark Families}} unchecked.
If you don't want any family or parent families automatically included, leave both {{man label|Automark Parent Families}} and {{man label|Automark Families}} unchecked.

=== Finishing up ===
When you have marked up as many items as you want and reviewed the automatic marks to make sure they are what you desire, you can press the {{man button|Done}} button.

The tool will bring up a confirmation dialog, allowing you to save your work, cancel and return to marking, or abandon it. If you abandon, your markings are lost and no changes are made to your current tree.

If you decide to save your work, the tool will perform a series of checks as it saves your work. These checks make sure that any conflicts that may have been created will not result in errors in your database. For example, if you selected a person to add, but decided to ignore a note attached to that person, the tool will 'clean up' the reference to the note on the person before saving it.

== FAQ ==
;Why would I want to use the {{man button|Edit import}} button?
: If you had an item with a difference, where both the current tree and the imported tree made changes. Because of some limitations of Gramps and this tool, you cannot choose between current and imported for every detail within an object. For these details, you can only choose to keep your current data with {{man button|Ignore}} or {{man button|Merge Original}}, or use the imported data with {{man button|Replace}} or {{man button|Merge Import}}. In either case some changes will be lost. For example, if you have edited a Person and added a Nickname, and the imported tree had edited the same person to add a LDS Ordinance, you can only keep the information for one side. In this case you might want to edit the imported person to change it to add the Nickname so that data will not be lost.

;Why does the import file have to be derived from the same original source?
: If it is not, then the matching process will not find any items that are the same or even different. Every item in the import file will end up showing as 'Added', and every item in the current tree will show as 'Missing'. You can use this tool to add in part or all of the imported data, but it is not ideal for this purpose. You would be better importing the data into a new tree, using all the Gramps views and filters to find what you do or don't want, make any deletions or edits and export to a new XML before importing that into your tree the usual way.

;When would it make sense to use 'Merge Original' vs 'Merge Imported'?
: The difference between 'Merge Original' or 'Merge Imported' is which Gramps IDs are kept as the final object. If you would like to keep your starting family tree the way you have set it up, use Merge Original. If you think that the imported tree is better, has better IDs etc, then use the Merge Imported.

;Why can't you use a GEDCOM file as the import source?
: One of the things that make this tool work is that every 'object' in the Gramps database has a unique ID called a handle (this is different than the ID shown in the GUI for each object). The tool can compare objects with matching handles relatively easily, much more easily than guessing if John Smith in your tree is the one from 1722, 1854, or 2012.
: At this time Gramps GEDCOM import and export has no way to save these handles to make this sort of matching possible. A few of the other family tree tools can import and export the so called '_UID' GEDCOM tag (which is not standardized) which might be usable for this, but most tools will simply discard them or modify them to be unusable. Even if these were available and not lost in translation, Gramps data model does not always match with GEDCOM data model. So a GEDCOM export/import, even without any changes made by the user, would have a lot of differences.

== Notes ==
If you are not sure exactly what an imported tree contains, you should use Gramps to examine it before using this tool. Import the tree into a new family tree, and look it over with the various charts (I like the relationship chart myself) to see if there are branches that you don't want. It is frequently easier to use Gramps filters or editing tools to remove items than to use the tool to exclude them, although the tool will suffice for simpler cases. Even then you should take notes on the IDs of people or families that you don't want, to make it easier to find them with this tool.

This is a new tool and fairly complex. Please report any issues or desired enhancements to paulr2787 at gmail.com

I have included a French translation of the tool, mostly as a test of the internationalization code. Since I don't speak French (USA Texas version of English only), please excuse my French.

==See also==
* [[Addon:Database_Differences_Report|Database Differences Report]] - allows a mostly complete comparison between the currently opened database (Family Tree) and a Gramps XML file.

[[Category:Plugins]]

Addon:Import Merge Tool

2022-01-16T21:28:56Z

Codefarmer: Clarify difference between Merge Original and Merge Import

{{Third-party plugin}}
{{man tip|Released for Gramps 5.0.x or greater versions}}
[[File:ImportMerge.png|thumb|right|350px|Import and Merge tool]]
The Import and Merge tool will {{man label|Import and merge a Gramps XML}} family tree derived from your own [[How_to_make_a_backup|Gramps XML family tree]] backup file.
== Purpose of this tool ==
This tool was specifically written to make importing and merging a Gramps [[Genealogy_Glossary#family_tree|Tree]] derived from your own Tree easier.

Make no mistake, merging is '''''hard'''''! And this tool is not magic, it does not make the process simple but it ''is'' easier than the alternatives.

{{man note|Important Note|This tool this requires that the Family Tree being merged must be a Gramps Family Tree ''derived from a version'' of the currently loaded Family Tree.}}

A situation occurs occasionally after giving someone a copy of your tree in our native [[Gramps XML]] format. Then each person makes changes to the copy in their possession using Gramps locally. (You can verify the Trees differ and log those revisions with the [[Addon:Database_Differences_Report|Database Differences]] add-on report.)

Programmers call this a 'fork.' (As in: when travelers come to a 'fork in the road' and each chooses different paths.) But the bottom line is that you now have two tree variants derived from a common Tree and you want share your updated Tree. You can't just give the person a fresh copy of your Tree because then their changes would be overwritten.

At some point, you may want to merge the forks into a common tree... without losing the useful changes from either tree. That synchronization is what this tool is designed to facilitate. It depends on the two Trees sharing common internal handles (not just the user-editable IDs) to simplify ignoring unchanged records. Then the tool focuses you on just the changes.

But say the other user doesn't use Gramps, so you exported with [[Gramps_and_GEDCOM|GEDCOM]] (or another format) and got it back? Sorry... this tool won't be any easier than a manual merge after a standard import. You'd still need to hand compare every record.

The derived trees need not be limited to those edited by someone else. I often take a copy of my tree on my laptop when traveling and sometimes I make updates while on the road. But then I may forget to copy it back to my home desktop computer until after I've made more updates. This tool helps to merge these back together.
{{man warn|1=Warning: Data Corruption Risk |2=Mass changes mean more potential for mangling the data. Back up your current tree BEFORE using this tool to merge. If something goes wrong, you will have a way to go back and start over. See [[How to make a backup|make a Gramps XML backup]].}}

==Usage==
The tool can be installed like any other Addon; see {{man label|[[Third-party_Addons#Installing_Addons_in_Gramps|Installing Addons in Gramps]]}}

Once installed, it is run by using the {{man menu|Tools -> Family Tree Processing -> Import and Merge tool...}}.
=== Running the Import Merge tool ===
The tool will start with an 'Undo history warning' that suggest that you back up your work.

You are then presented with the import file dialog, which shows '.gramps' files from your import location.

When you have selected a file to import, the main tool window comes up and some progress meters pop up indicating the import and comparison process. When this is complete you end up with a three part window. The bottom part provides control and 'Action' buttons and a hint that changes depending on what you are doing.

=== Top Pane ===
The top pane is a scrollable and selectable view of individual items that were found to be different in your import. Items that were the same (since they were derived from the common Gramps tree) are not shown.

[[File:ImportMerge.png|thumb|right|569px|Import and Merge tool]]
The top pane shows a 'Status' which is one of '''Different''', '''Added''', or '''Missing'''. '''Different''' items were found in both the current and imported trees, but had been changed in some way. ''Added'' items are found only in your imported tree. And '''Missing''' items were found in your current tree, but not in the imported tree.

The top pane also shows the ''Object'' type ('''Person''', '''Family''', '''Media''' etc.), its Gramps ''ID'', an ''Object Name or Description'', and the selected ''Action'' (more later).

You can search for items by Name by just typing characters to match. The top pane must be active for this to work. For example if you are looking for 'Smith, Magnes' in the 'sample.gramps' tree, you could type 'smi' which would jump the selection to the first of the lines containing these characters, and then use cursor up/down keys to find the 'Smith' you are looking for. Or type 'magn' which is more likely to land on the right place.

You can search for items by 'ID' field by typing '#' and then the characters to match. For example type '#I0103' to search for the individual with ID I0103.

You can sort the top pane by ''Status'' (''Object'' will be a sub-sort), ''Object'', ''ID'', ''Object Name/Description'' (will be grouped by ''Object'') and ''Action''. Click on the column header to change the sort.

=== Lower Pane ===
When an item in the top pane is selected, the lower pane shows the specific differences. If no ''Action'' is made yet, the pane will show the 'Original >>' and 'Imported >>' state for each sub-object and item that has a difference. If an ''Action'' has been selected, the pane also includes a 'Result >>' for each sub-object and item that has a difference.

Sometimes it may be difficult to determine enough about the difference to figure out what is going on. If so, you can check the {{man label|Show more details}} checkbox to see more about the difference.

The lower pane tries to present the information as concisely but informatively as possible. Apologies if the information seems a bit hard to interpret at times. One area that might be confusing is when there are differences in 'lists'. Many of Gramps objects have lists of other objects, families have lists of children, persons have lists of events or notes etc. When a list has changes, the left side will have a list position number preceded by '#'. For example:
{|
|Person, Event References #1, Event
| Original >> 
|your tree Event: [E0012] Death: Smith Gus
|-
|
| Imported >> 
|your tree Event: [E0011] Birth: Smith Gus
|-
|Person, Event References #2, Event
| Original >> 
|your tree Event: [E0011] Birth: Smith Gus
|-
|
| Imported >> 
|your tree Event: [E0012] Death: Smith Gus
|}
In this example list of event references, the imported tree somehow got the Birth and Death events swapped, compared to the original tree.

==== Control buttons ====

{{man button|Help}} brings up this wiki.

{{man button|Edit import}} allows editing of the selected item. Any changes are temporarily saved in your imported data, and will be kept only if that data is merged into your current tree. If your editing creates new items, they will appear in the top pane list when you finish editing. Changes here cause the 'Action' to be cleared, so be sure to choose an Action when finished.

{{man button|Unmark}} clears any current Action. If an item remains unmarked when you are done, it will be treated as if 'Ignored', that is, there will be no changes to your tree for that item.

{{man button|Ignore}} sets the action for the item so that there will be no changes to your tree for that item. This is the same as leaving the item unmarked, but makes it clear that you have looked at that item.

{{man button|Done}} tells the tool that you are finished marking the various actions. The tool will bring up a confirmation dialog, allowing you to save your work, cancel and return to marking, or abandon it.

The remaining buttons are considered 'Actions' and depend on the Status of the item.

{{man button|Add}} appears for items with an 'Added' status. When added, the imported data will be added to your current tree.

{{man button|Delete}} appears for items with a 'Missing' status. When selected, the data in your tree for this item will be deleted.

{{man button|Replace}} appears for items with a 'Different' status. When replaced, the imported data for the item will completely replace the same data in your current tree.

{{man button|Merge Original}} appears for items with a 'Different' status. When selected, the imported data for the item will be merged with the original tree and the IDs of the original item are retained. The portions of the data that cannot be merged will remain as it is in your current tree data.

{{man button|Merge Import}} appears for items with a 'Different' status. When selected, the imported data for the item will be merged with the original tree and the IDs of the imported item are used. The portions of the data that cannot be merged will be replaced by the import data.

When you select an 'Action' with one of the buttons, a hint will appear that states the action in more detail.

You can change the 'Action' at any time on any item, it may be instructive to see the results of choosing the various choices in the lower pane.

In general I recommend that you start marking your items with the 'Different' items first. Within these, doing '''Families''' and '''Persons''' first will usually minimize the amount of work to merge your tree. This tool starts up with the sort set to put these items first, so starting at the top is easy.

=== Automatic Mark ===

This tool includes the ability to automatically mark those items that are 'referred to' by the item you are currently marking. For Example, if you {{man button|Add}} a person, the events, notes, media, citations and families that the person refers to will also be added. The same process is applied for each of the various 'Action' buttons.

The marks that are automatically generated are shown in the top pane action column with a '*' preceding the action.

Occasionally you may mark items that create a conflict in the automatic marking. For example you {{man button|Add}} a person that refers to a media, and then later {{man button|Ignore}} a person that also refers to the same media. In this case, the media item will be marked with a '?' and the action that tends to conserve more data will be used. This means that Adds have priority over Ignore, Ignore over Delete etc.

You should review any items marked this way to make sure that you agree with the program.

Note that families and persons in particular usually have a lot of references to other families or persons. In fact if your imported file contains a whole new branch of your family tree, selecting any one of the people or families in that branch will automatically mark all the new people and families at once. This is usually desirable, but not always.

==== Automatic mark with Families ====
This tool is not ideal for selecting only parts of a tree for merging, but it can be done. If you wish to include a person, but not his family (spouse and children) then you can uncheck the {{man label|Automark Families}} checkbox. This applies to all persons found via the Automark as well. The effect is that you can get ancestors (if {{man label|Automark Parent Families}} is checked) included but not all the descendants of those ancestors.

If you wish to get a set of spouses and descendants included when adding a person but not all the ancestors of the spouses, then you can uncheck the {{man label|Automark Parent Families}} checkbox and leave the {{man label|Automark Families}} unchecked.
If you don't want any family or parent families automatically included, leave both {{man label|Automark Parent Families}} and {{man label|Automark Families}} unchecked.

=== Finishing up ===
When you have marked up as many items as you want and reviewed the automatic marks to make sure they are what you desire, you can press the {{man button|Done}} button.

The tool will bring up a confirmation dialog, allowing you to save your work, cancel and return to marking, or abandon it. If you abandon, your markings are lost and no changes are made to your current tree.

If you decide to save your work, the tool will perform a series of checks as it saves your work. These checks make sure that any conflicts that may have been created will not result in errors in your database. For example, if you selected a person to add, but decided to ignore a note attached to that person, the tool will 'clean up' the reference to the note on the person before saving it.

== FAQ ==
;Why would I want to use the {{man button|Edit import}} button?
: If you had an item with a difference, where both the current tree and the imported tree made changes. Because of some limitations of Gramps and this tool, you cannot choose between current and imported for every detail within an object. For these details, you can only choose to keep your current data with {{man button|Ignore}} or {{man button|Merge Original}}, or use the imported data with {{man button|Replace}} or {{man button|Merge Import}}. In either case some changes will be lost. For example, if you have edited a Person and added a Nickname, and the imported tree had edited the same person to add a LDS Ordinance, you can only keep the information for one side. In this case you might want to edit the imported person to change it to add the Nickname so that data will not be lost.

;Why does the import file have to be derived from the same original source?
: If it is not, then the matching process will not find any items that are the same or even different. Every item in the import file will end up showing as 'Added', and every item in the current tree will show as 'Missing'. You can use this tool to add in part or all of the imported data, but it is not ideal for this purpose. You would be better importing the data into a new tree, using all the Gramps views and filters to find what you do or don't want, make any deletions or edits and export to a new XML before importing that into your tree the usual way.

;Why can't you use a GEDCOM file as the import source?
: One of the things that make this tool work is that every 'object' in the Gramps database has a unique ID called a handle (this is different than the ID shown in the GUI for each object). The tool can compare objects with matching handles relatively easily, much more easily than guessing if John Smith in your tree is the one from 1722, 1854, or 2012.
: At this time Gramps GEDCOM import and export has no way to save these handles to make this sort of matching possible. A few of the other family tree tools can import and export the so called '_UID' GEDCOM tag (which is not standardized) which might be usable for this, but most tools will simply discard them or modify them to be unusable. Even if these were available and not lost in translation, Gramps data model does not always match with GEDCOM data model. So a GEDCOM export/import, even without any changes made by the user, would have a lot of differences.

== Notes ==
If you are not sure exactly what an imported tree contains, you should use Gramps to examine it before using this tool. Import the tree into a new family tree, and look it over with the various charts (I like the relationship chart myself) to see if there are branches that you don't want. It is frequently easier to use Gramps filters or editing tools to remove items than to use the tool to exclude them, although the tool will suffice for simpler cases. Even then you should take notes on the IDs of people or families that you don't want, to make it easier to find them with this tool.

This is a new tool and fairly complex. Please report any issues or desired enhancements to paulr2787 at gmail.com

I have included a French translation of the tool, mostly as a test of the internationalization code. Since I don't speak French (USA Texas version of English only), please excuse my French.

==See also==
* [[Addon:Database_Differences_Report|Database Differences Report]] - allows a mostly complete comparison between the currently opened database (Family Tree) and a Gramps XML file.

[[Category:Plugins]]

Talk:Gramps 5.1 Wiki Manual - Keybindings

2022-01-03T15:37:49Z

Codefarmer: Highlighting differences in behavior between People Grouped and Place Tree

@Call_me_Dave

Thanks for reviewing and making improvements to my recent changes to the keybinding page. My first instinct was to create a combined table for Grouped views like People Grouped and Place Tree because they have similar behaviors but I noticed at least one difference between the two:

Pressing Enter in People Grouped view expands and collapses entries of the selected entry in Group mode, but in the Place Tree view, it actually edits the entry, so I decided to split them up. What would be a good way to highlight that in the current wiki?

Gramps 5.1 Wiki Manual - Keybindings

2022-01-02T12:29:43Z

Codefarmer: Add Pace View bindings section

{{man index|Gramps 5.1 Wiki Manual - FAQ|Gramps 5.1 Wiki Manual - Command Line|5.1}}
{{languages|Gramps_5.1_Wiki_Manual_-_Keybindings}}
{{#vardefine:chapter|B}}
{{#vardefine:figure|0}}
This appendix lists keybindings (also known as ''Keyboard shortcuts'' or ''hotkeys'') that can be used in the Gramps dialogs as an alternative to using the mouse.

Some keybindings require the user to press a single key or a sequence of keys one after the other. Other keybindings require pressing and holding several keys simultaneously.
== List Views ==
=== Common keybindings ===

{{man tip|Keyboards are not all the same!|
Keybindings may depend on the keyboard layout (localization) and on your computer’s Operating System.{{-}}
[[File:windows_180x160.png|128px]] [[File:macos_200x200.png|128px]] [[File:Linux_220x261.png|128px]] [[File:Bsd daemon.png|128px]]}}
The following keybindings are available in all category [[Gramps_Glossary#view|views]].
{|{{prettytable}}
!Action/Function
!Microsoft Windows
!macOS
!KDE/GNOME
|-
| id="1" | [[Gramps_5.1_Wiki_Manual_-_Manage_Family_Trees#Starting_a_new_Family_Tree|Manage family trees]]
| |{{Man key press|Ctrl|O}}
| |{{Man key press|Cmd|O}}
| |{{Man key press|Ctrl|O}}
|-
| id="2" | [[Gramps_5.1_Wiki_Manual_-_Manage_Family_Trees#Importing_data|Import family tree]]
| |{{Man key press|Ctrl|I}}
| |{{Man key press|Cmd|I}}
| |{{Man key press|Ctrl|I}}
|-
| id="3" | [[Gramps_5.1_Wiki_Manual_-_Manage_Family_Trees#Exporting_data|Export family tree]]
| |{{Man key press|Ctrl|E}}
| |{{Man key press|Cmd|E}}
| |{{Man key press|Ctrl|E}}
|-
| id="4" | Changes to the next [[Gramps_5.1_Wiki_Manual_-_Main_Window#Switching_Categories|Category]].
| |{{Man key press|Ctrl|N}}
| |{{Man key press|Cmd|N}}
| |{{Man key press|Ctrl|N}}
|-
| id="5" |Changes to the previous [[Gramps_5.1_Wiki_Manual_-_Main_Window#Switching_Categories|Category]].
| |{{Man key press|Ctrl|P}}
| |{{Man key press|Cmd|P}}
| |{{Man key press|Ctrl|P}}
|-
| id="45" |Change [[Gramps_5.1_Wiki_Manual_-_Main_Window#Switching_Categories|Category]] to Category number 0/1/2/../9
| |{{Man key press|Ctrl|1}} {{Man key press|Ctrl|2}} {{Man key press|Ctrl|3}} ...
| |{{Man key press|Cmd|1}} {{Man key press|Cmd|2}} {{Man key press|Cmd|3}}..
| |{{Man key press|Ctrl|1}} {{Man key press|Ctrl|2}} {{Man key press|Ctrl|3}}..
|-
| id="6" |Within the Category changes the [[Gramps_5.1_Wiki_Manual_-_Main_Window#Switching_Views|view]] to view mode number 0/1/2/../9
| |{{Man key press|Ctrl|Alt|1}} {{Man key press|Ctrl|Alt|2}} {{Man key press|Ctrl|Alt|3}} ...
| |{{Man key press|Cmd|Opt|1}} {{Man key press|Cmd|Opt|2}} {{Man key press|Cmd|Opt|3}}..
| |{{Man key press|Ctrl|Alt|1}} {{Man key press|Ctrl|Alt|2}} {{Man key press|Ctrl|Alt|3}}..
|-
| id="8" |[[Gramps_5.1_Wiki_Manual_-_Navigation#Using_the_Clipboard|Open the Clipboard]]
| |{{Man key press|Ctrl|B}}
| |{{Man key press|Cmd|B}}
| |{{Man key press|Ctrl|B}}
|-
| id="9" |Add the selected item as a [[Gramps_5.1_Wiki_Manual_-_Navigation#Bookmarks|bookmark]]
| |{{Man key press|Ctrl|D}}
| |{{Man key press|Cmd|D}}
| |{{Man key press|Ctrl|D}}
|-
| id="10" |[[Gramps_5.1_Wiki_Manual_-_Navigation#Bookmarks|Organize the bookmarks]]
| |{{Man key press|Shift|Ctrl|D}}
| |{{Man key press|Shift|Cmd|D}}
| |{{Man key press|Shift|Ctrl|D}}
|-
| id="11" |Open the {{man label|[[Gramps_5.1_Wiki_Manual_-_Navigation#Edit|Undo History]]}} dialog
| |{{Man key press|Ctrl|H}}
| |{{Man key press|Shift|Cmd|H}}
| |{{Man key press|Ctrl|H}}
|-
| id="12" |Jump to a [[Gramps_5.1_Wiki_Manual_-_Settings#ID_Formats|Gramps ID]]
| |{{Man key press|Ctrl|J}}
| |{{Man key press|Cmd|J}}
| |{{Man key press|Ctrl|J}}
|-
| id="13" |Move to previous item in history
| |{{Man key press|Alt|Left}} (Left arrow)
| |{{Man key press|Ctrl|Opt|Left}} (Left arrow)
| |{{Man key press|Alt|Left}} (Left arrow)
|-
| id="14" |Move to next item in history
| |{{Man key press|Alt|Right}} (Right arrow)
| |{{Man key press|Ctrl|Opt|Right}} (Right arrow)
| |{{Man key press|Alt|Right}} (Right arrow)
|-
| id="15" |Go to the '''[[Gramps_5.1_Wiki_Manual_-_Settings#Setting_Home_person|Home Person]]'''
| |{{Man key press|Alt|Home}}
| |
| |{{Man key press|Alt|Home}}
|-
| id="16" |Same action as the [[File:Gramps-config.png|20px]] Configure active view button
| |{{Man key press|Shift|Ctrl|C}}
| |{{Man key press|Shift|Cmd|C}}
| |{{Man key press|Shift|Ctrl|C}}
|-
| id="7" |Toggle the left gramplet sidebar ([[Gramps_5.1_Wiki_Manual_-_Main_Window#Navigator|Navigator]] panel)
| |{{Man key press|Ctrl|M}}
| |{{Man key press|Cmd|M}}
| |{{Man key press|Ctrl|M}}
|-
| id="17" |Toggle the right gramplet sidebar ([[Gramps_5.1_Wiki_Manual_-_Main_Window#Bottombar_and_Sidebar|Sidebar]])
| |{{Man key press|Shift|Ctrl|R}}
| |{{Man key press|Shift|Cmd|R}}
| |{{Man key press|Shift|Ctrl|R}}
|-
| id="18" |Toggle the bottom gramplet sidebar ([[Gramps_5.1_Wiki_Manual_-_Main_Window#Bottombar_and_Sidebar|Bottombar]])
| |{{Man key press|Shift|Ctrl|B}}
| |{{Man key press|Shift|Cmd|B}}
| |{{Man key press|Shift|Ctrl|B}}
|-
| id="19" |Undo
| |{{Man key press|Ctrl|Z}}
| |{{Man key press|Cmd|Z}}
| |{{Man key press|Ctrl|Z}}
|-
| id="20" |Do again
| |{{Man key press|Shift|Ctrl|Z}}
| |{{Man key press|Shift|Cmd|Z}}
| |{{Man key press|Shift|Ctrl|Z}}
|-
| id="21" |Quit Gramps
| |{{Man key press|Ctrl|Q}}
| |{{Man key press|Cmd|Q}}
| |{{Man key press|Ctrl|Q}}
|-
| id="xx" | [[Gramps_5.1_Wiki_Manual_-_Navigation#Add|Add/Create]] a new object (Opens the related Editor) Person Family Event Place Source Citation Repository Media Note
| | {{Man key press|Shift|Alt|P}} {{Man key press|Shift|Alt|F}} {{Man key press|Shift|Alt|E}} {{Man key press|Shift|Alt|L}} {{Man key press|Shift|Alt|S}} {{Man key press|Shift|Alt|C}} {{Man key press|Shift|Alt|R}} {{Man key press|Shift|Alt|M}} {{Man key press|Shift|Alt|N}}
| | {{Man key press|Shift|Ctrl|Opt|P}} {{Man key press|Shift|Ctrl|Opt|F}} {{Man key press|Shift|Ctrl|Opt|E}} {{Man key press|Shift|Ctrl|Opt|L}} {{Man key press|Shift|Ctrl|Opt|S}} {{Man key press|Shift|Ctrl|Opt|C}} {{Man key press|Shift|Ctrl|Opt|R}} {{Man key press|Shift|Ctrl|Opt|M}} {{Man key press|Shift|Ctrl|Opt|N}}
| | {{Man key press|Shift|Alt|P}} {{Man key press|Shift|Alt|F}} {{Man key press|Shift|Alt|E}} {{Man key press|Shift|Alt|L}} {{Man key press|Shift|Alt|S}} {{Man key press|Shift|Alt|C}} {{Man key press|Shift|Alt|R}} {{Man key press|Shift|Alt|M}} {{Man key press|Shift|Alt|N}}
|}

=== All List Views bindings ===

The following bindings are available in all list views: People, Families, Events, Places, Sources, Citations, Repositories, Media and Notes View.
{|{{prettytable}}
!Action/Function
!Microsoft Windows
!Mac OS
!KDE/GNOME
!Note
|-
| id="22" |Edits the selected list item
| |{{Man key press|Ctrl|Enter}}
| |
| |{{Man key press|Ctrl|Enter}}
| |
|-
| id="23" |Adds a new item to the database
| |{{Man key press|Ctrl|Insert}}
| |
| |{{Man key press|Ctrl|Insert}}
| |
|-
| id="24" |Deletes the selected list item
| |{{Man key press|Ctrl|Delete}}
| |
| |{{Man key press|Ctrl|Delete}}
| |
|-
| id="46" |Activate the {{man button|Find}} field
|!-- Microsoft Windows --> |{{Man key press|Ctrl|F}}
|!-- Mac OS --> |{{Man key press|Cmd|F}}
|!-- KDE/GNOME --> |{{Man key press|Ctrl|F}}
| | List view interactive search ahead / Quick search
|}

=== People View bindings ===

{|{{prettytable}}
!Action/Function
!Microsoft Windows
!Mac OS
!KDE/GNOME
|-
| id="25" |Expands and collapses entries of the selected surname in Group mode
| |{{Man key press|Enter}} or {{Man key press|Shift|Right}} (expand) {{Man key press|Shift|Left}} (collapse)
| |{{Man key press|Enter}} or {{Man key press|Shift|Right}} (expand) {{Man key press|Shift|Left}} (collapse)
| |{{Man key press|Enter}}
|-
| id="251" |Expands and contracts person selection in Group mode
| |{{Man key press|Shift|Up}} (Up arrow) {{Man key press|Shift|Down}} (Down arrow)
| |{{Man key press|Shift|Up}} (Up arrow) {{Man key press|Shift|Down}} (Down arrow)
| |
|}

=== Place View bindings ===

{|{{prettytable}}
!Action/Function
!Microsoft Windows
!Mac OS
!KDE/GNOME
|-
| id="25" |Expands and collapses entries of places in Group mode
| |{{Man key press|Shift|Right}} (expand) {{Man key press|Shift|Left}} (collapse)
| |{{Man key press|Shift|Right}} (expand) {{Man key press|Shift|Left}} (collapse)
| |
|-
| id="251" |Expands and contracts place selection in Group mode
| |{{Man key press|Shift|Up}} (Up arrow) {{Man key press|Shift|Down}} (Down arrow)
| |{{Man key press|Shift|Up}} (Up arrow) {{Man key press|Shift|Down}} (Down arrow)
| |
|}

==Editors==

=== Editor Tab bindings ===
These bindings work on the tab pages of the editors (so not on the labels of the tabs!, press tab on label to move to tabpage content).

{|{{prettytable}}
!Action/Function
!Microsoft Windows
!Mac OS
!KDE/GNOME
|-
| id="26" |Same action as the {{icon|Stock_edit}} button when that button is present
| |{{Man key press|Enter}}
| |{{Man key press|Return}} or {{Man key press|Enter}}
| |{{Man key press|Enter}}
|-
| id="27" |Same action as the {{icon|Stock_add}} button when that button is present
| |{{Man key press|Insert}}
| |
| |{{Man key press|Insert}}
|-
| id="28" |Same action as the {{icon|Stock_remove}} button when that button is present
| |{{Man key press|Delete}}
| |
| |{{Man key press|Delete}}
|-
| id="29" |Same action as the {{man button|Share}} button when that button is present
| |{{Man key press|Ctrl|O}}
| |{{Man key press|Cmd|O}}
| |{{Man key press|Ctrl|O}}
|-
| id="30" |Change tabpage to the tabpage to the left
| |{{Man key press|Alt|Left}} (Left arrow)
| |{{Man key press|Ctrl|Opt|Left}} (Left arrow)
| |{{Man key press|Alt|Left}} (Left arrow)
|-
| id="31" |Change tabpage to the tabpage to the right
| |{{Man key press|Alt|Right}} (Right arrow)
| |{{Man key press|Ctlr|Opt|Right}} (Right arrow)
| |{{Man key press|Alt|Right}} (Right arrow)
|}

{|{{prettytable}}
!Action/Function
!Mouse Key
|-
| id="32" |Call up [https://en.wikipedia.org/wiki/Context_menu context menu] popup
!Right-click
|-
| id="33" |Same action as the {{icon|Stock_edit}} {{man button|Edit}} button when that button is present
!Double-click
|-
| id="34" |Common action that is not the same as {{icon|Stock_edit}} {{man button|Edit}} button. Eg: on Family Editor Child tab, edit child
!Middle-click
|}

=== Editor bindings ===
These bindings work on Editors by activating focus or by changing state of toggle buttons ([[Accessibility]]).

{|{{prettytable}}
!Action/Function
!Microsoft Windows
!Mac OS
!KDE/GNOME
|-
| id="35" |Change the privacy status.
| |{{Man key press|Ctrl|P}}
| |{{Man key press|Cmd|P}}
| |{{Man key press|Ctrl|P}}
|-
| id="36" |Call the Date editor (if present).
| |{{Man key press|Ctrl|D}}
| |{{Man key press|Cmd|D}}
| |{{Man key press|Ctrl|D}}
|-
| id="37" |Activate the {{icon|Stock_add}} {{man button|Add}} button (if present).
| |{{Man key press|Ctrl|A}}
| |{{Man key press|Cmd|A}}
| |{{Man key press|Ctrl|A}}
|-
| id="38" |Activate the {{icon|Stock_edit}} {{man button|Edit}} button (if present).
| |{{Man key press|Ctrl|E}}
| |{{Man key press|Cmd|E}}
| |{{Man key press|Ctrl|E}}
|-
| id="39" |Activate the {{man button|Select}} button (if present).
| |{{Man key press|Ctrl|S}}
| |{{Man key press|Cmd|S}}
| |{{Man key press|Ctrl|S}}
|-
| id="40" |Activate the {{man button|Father}} button (if present).
| |{{Man key press|Ctrl|F}}
| |{{Man key press|Cmd|F}}
| |{{Man key press|Ctrl|F}}
|-
| id="41" |Activate the {{man button|Mother}} button (if present).
| |{{Man key press|Ctrl|M}}
| |{{Man key press|Cmd|M}}
| |{{Man key press|Ctrl|M}}
|}

==Handy Shortcuts==

{|{{prettytable}}
!Action/Function
!Microsoft Windows
!Mac OS
!KDE/GNOME
!Note
|-
| id="42" |Full screen
|{{man key press|F11}}
|
|{{man key press|F11}}
|Maximizes Gramps to use the Full screen
|-
| id="43" |Show this user manual
|{{man key press|F1}}
|{{man key press|F1}}
|{{man key press|F1}}
|
|-
| id="44" |Select the {{man button|OK}} button
|{{man key press|Alt}}+{{man key press|O}}
|
|
|Handy for use with low resolution screens
|-
| id="45" |Dismiss (Select the {{man button|Cancel}} button)
|{{man key press|Esc}}
|{{Man key press|⎋ Esc}}
|{{man key press|Esc}}
|Handy for use with low resolution screens
|-
| id="46" |Toggle Open/Save dialog between breadcrumbs and filepaths
| |{{Man key press|Ctrl|L}}
| |{{Man key press|Ctrl|L}} {{Man key press|Esc}}
| |{{Man key press|Ctrl|L}}
|Handy for pasting filepaths
|}

== Context menu==
A [https://wikipedia.org/wiki/Context_menu context pop-up menu] shows limited number of choice related to the currently selected item in a Graphical User Interface. The menu appears with right-click on an item in operating systems with a 2 or 3 button mouse. In the one button mouse macOS, a {{man button|Ctrl}}-click will bring up the [https://developer.apple.com/design/human-interface-guidelines/macos/menus/contextual-menus/ Contextual Menus].

Keybindings:
* In Windows, the '''[https://wikipedia.org/w/index.php?title=Menu_key Menu Key]''' (aka '''application key''') will show the context menu for the active field. Alternately, the {{man button|⇧ Shift}}+{{man button|F10}} [https://wikipedia.org/wiki/Keyboard_shortcut keyboard shortcut], or sometimes {{man button|Ctrl}}+{{man button|⇧ Shift}}+{{man button|F10}}
* In macOS, users will need to enable the Universal Access settings in the System Preferences.

{{man tip|Quick navigation to an object|The clipboard has a navigation shortcut. Copy any object to the Clipboard (by drag'n'drop or by selecting and pressing the {{man key press|Ctrl|C}} [[Gramps_5.1_Wiki_Manual_-_Keybindings|keybinding]]), then select the object on the Clipboard and right-click to reveal the [[Gramps_5.1_Wiki_Manual_-_Navigation#Clipboard_context_menu|Clipboard's contextual pop-up menu]]. The bottom menu item will offer to make the selected object active. The View will '''''not''''' navigate to the object's category.}}

See [[Gramps_{{man version}}_Wiki_Manual_-_Settings#Context_menu|Context Menu]]

== See also ==
* [http://en.wikipedia.org/wiki/Table_of_keyboard_shortcuts Table of keyboard shortcuts] - for major operating systems.

{{-}}
{{man index|Gramps 5.1 Wiki Manual - FAQ|Gramps 5.1 Wiki Manual - Command Line|5.1}}
{{languages|Gramps_5.1_Wiki_Manual_-_Keybindings}}
{{grampsmanualcopyright}}

[[Category:Documentation]]

Gramps 5.1 Wiki Manual - Keybindings

2022-01-02T12:23:07Z

Codefarmer: Add selection expansion key bindings

{{man index|Gramps 5.1 Wiki Manual - FAQ|Gramps 5.1 Wiki Manual - Command Line|5.1}}
{{languages|Gramps_5.1_Wiki_Manual_-_Keybindings}}
{{#vardefine:chapter|B}}
{{#vardefine:figure|0}}
This appendix lists keybindings (also known as ''Keyboard shortcuts'' or ''hotkeys'') that can be used in the Gramps dialogs as an alternative to using the mouse.

Some keybindings require the user to press a single key or a sequence of keys one after the other. Other keybindings require pressing and holding several keys simultaneously.
== List Views ==
=== Common keybindings ===

{{man tip|Keyboards are not all the same!|
Keybindings may depend on the keyboard layout (localization) and on your computer’s Operating System.{{-}}
[[File:windows_180x160.png|128px]] [[File:macos_200x200.png|128px]] [[File:Linux_220x261.png|128px]] [[File:Bsd daemon.png|128px]]}}
The following keybindings are available in all category [[Gramps_Glossary#view|views]].
{|{{prettytable}}
!Action/Function
!Microsoft Windows
!macOS
!KDE/GNOME
|-
| id="1" | [[Gramps_5.1_Wiki_Manual_-_Manage_Family_Trees#Starting_a_new_Family_Tree|Manage family trees]]
| |{{Man key press|Ctrl|O}}
| |{{Man key press|Cmd|O}}
| |{{Man key press|Ctrl|O}}
|-
| id="2" | [[Gramps_5.1_Wiki_Manual_-_Manage_Family_Trees#Importing_data|Import family tree]]
| |{{Man key press|Ctrl|I}}
| |{{Man key press|Cmd|I}}
| |{{Man key press|Ctrl|I}}
|-
| id="3" | [[Gramps_5.1_Wiki_Manual_-_Manage_Family_Trees#Exporting_data|Export family tree]]
| |{{Man key press|Ctrl|E}}
| |{{Man key press|Cmd|E}}
| |{{Man key press|Ctrl|E}}
|-
| id="4" | Changes to the next [[Gramps_5.1_Wiki_Manual_-_Main_Window#Switching_Categories|Category]].
| |{{Man key press|Ctrl|N}}
| |{{Man key press|Cmd|N}}
| |{{Man key press|Ctrl|N}}
|-
| id="5" |Changes to the previous [[Gramps_5.1_Wiki_Manual_-_Main_Window#Switching_Categories|Category]].
| |{{Man key press|Ctrl|P}}
| |{{Man key press|Cmd|P}}
| |{{Man key press|Ctrl|P}}
|-
| id="45" |Change [[Gramps_5.1_Wiki_Manual_-_Main_Window#Switching_Categories|Category]] to Category number 0/1/2/../9
| |{{Man key press|Ctrl|1}} {{Man key press|Ctrl|2}} {{Man key press|Ctrl|3}} ...
| |{{Man key press|Cmd|1}} {{Man key press|Cmd|2}} {{Man key press|Cmd|3}}..
| |{{Man key press|Ctrl|1}} {{Man key press|Ctrl|2}} {{Man key press|Ctrl|3}}..
|-
| id="6" |Within the Category changes the [[Gramps_5.1_Wiki_Manual_-_Main_Window#Switching_Views|view]] to view mode number 0/1/2/../9
| |{{Man key press|Ctrl|Alt|1}} {{Man key press|Ctrl|Alt|2}} {{Man key press|Ctrl|Alt|3}} ...
| |{{Man key press|Cmd|Opt|1}} {{Man key press|Cmd|Opt|2}} {{Man key press|Cmd|Opt|3}}..
| |{{Man key press|Ctrl|Alt|1}} {{Man key press|Ctrl|Alt|2}} {{Man key press|Ctrl|Alt|3}}..
|-
| id="8" |[[Gramps_5.1_Wiki_Manual_-_Navigation#Using_the_Clipboard|Open the Clipboard]]
| |{{Man key press|Ctrl|B}}
| |{{Man key press|Cmd|B}}
| |{{Man key press|Ctrl|B}}
|-
| id="9" |Add the selected item as a [[Gramps_5.1_Wiki_Manual_-_Navigation#Bookmarks|bookmark]]
| |{{Man key press|Ctrl|D}}
| |{{Man key press|Cmd|D}}
| |{{Man key press|Ctrl|D}}
|-
| id="10" |[[Gramps_5.1_Wiki_Manual_-_Navigation#Bookmarks|Organize the bookmarks]]
| |{{Man key press|Shift|Ctrl|D}}
| |{{Man key press|Shift|Cmd|D}}
| |{{Man key press|Shift|Ctrl|D}}
|-
| id="11" |Open the {{man label|[[Gramps_5.1_Wiki_Manual_-_Navigation#Edit|Undo History]]}} dialog
| |{{Man key press|Ctrl|H}}
| |{{Man key press|Shift|Cmd|H}}
| |{{Man key press|Ctrl|H}}
|-
| id="12" |Jump to a [[Gramps_5.1_Wiki_Manual_-_Settings#ID_Formats|Gramps ID]]
| |{{Man key press|Ctrl|J}}
| |{{Man key press|Cmd|J}}
| |{{Man key press|Ctrl|J}}
|-
| id="13" |Move to previous item in history
| |{{Man key press|Alt|Left}} (Left arrow)
| |{{Man key press|Ctrl|Opt|Left}} (Left arrow)
| |{{Man key press|Alt|Left}} (Left arrow)
|-
| id="14" |Move to next item in history
| |{{Man key press|Alt|Right}} (Right arrow)
| |{{Man key press|Ctrl|Opt|Right}} (Right arrow)
| |{{Man key press|Alt|Right}} (Right arrow)
|-
| id="15" |Go to the '''[[Gramps_5.1_Wiki_Manual_-_Settings#Setting_Home_person|Home Person]]'''
| |{{Man key press|Alt|Home}}
| |
| |{{Man key press|Alt|Home}}
|-
| id="16" |Same action as the [[File:Gramps-config.png|20px]] Configure active view button
| |{{Man key press|Shift|Ctrl|C}}
| |{{Man key press|Shift|Cmd|C}}
| |{{Man key press|Shift|Ctrl|C}}
|-
| id="7" |Toggle the left gramplet sidebar ([[Gramps_5.1_Wiki_Manual_-_Main_Window#Navigator|Navigator]] panel)
| |{{Man key press|Ctrl|M}}
| |{{Man key press|Cmd|M}}
| |{{Man key press|Ctrl|M}}
|-
| id="17" |Toggle the right gramplet sidebar ([[Gramps_5.1_Wiki_Manual_-_Main_Window#Bottombar_and_Sidebar|Sidebar]])
| |{{Man key press|Shift|Ctrl|R}}
| |{{Man key press|Shift|Cmd|R}}
| |{{Man key press|Shift|Ctrl|R}}
|-
| id="18" |Toggle the bottom gramplet sidebar ([[Gramps_5.1_Wiki_Manual_-_Main_Window#Bottombar_and_Sidebar|Bottombar]])
| |{{Man key press|Shift|Ctrl|B}}
| |{{Man key press|Shift|Cmd|B}}
| |{{Man key press|Shift|Ctrl|B}}
|-
| id="19" |Undo
| |{{Man key press|Ctrl|Z}}
| |{{Man key press|Cmd|Z}}
| |{{Man key press|Ctrl|Z}}
|-
| id="20" |Do again
| |{{Man key press|Shift|Ctrl|Z}}
| |{{Man key press|Shift|Cmd|Z}}
| |{{Man key press|Shift|Ctrl|Z}}
|-
| id="21" |Quit Gramps
| |{{Man key press|Ctrl|Q}}
| |{{Man key press|Cmd|Q}}
| |{{Man key press|Ctrl|Q}}
|-
| id="xx" | [[Gramps_5.1_Wiki_Manual_-_Navigation#Add|Add/Create]] a new object (Opens the related Editor) Person Family Event Place Source Citation Repository Media Note
| | {{Man key press|Shift|Alt|P}} {{Man key press|Shift|Alt|F}} {{Man key press|Shift|Alt|E}} {{Man key press|Shift|Alt|L}} {{Man key press|Shift|Alt|S}} {{Man key press|Shift|Alt|C}} {{Man key press|Shift|Alt|R}} {{Man key press|Shift|Alt|M}} {{Man key press|Shift|Alt|N}}
| | {{Man key press|Shift|Ctrl|Opt|P}} {{Man key press|Shift|Ctrl|Opt|F}} {{Man key press|Shift|Ctrl|Opt|E}} {{Man key press|Shift|Ctrl|Opt|L}} {{Man key press|Shift|Ctrl|Opt|S}} {{Man key press|Shift|Ctrl|Opt|C}} {{Man key press|Shift|Ctrl|Opt|R}} {{Man key press|Shift|Ctrl|Opt|M}} {{Man key press|Shift|Ctrl|Opt|N}}
| | {{Man key press|Shift|Alt|P}} {{Man key press|Shift|Alt|F}} {{Man key press|Shift|Alt|E}} {{Man key press|Shift|Alt|L}} {{Man key press|Shift|Alt|S}} {{Man key press|Shift|Alt|C}} {{Man key press|Shift|Alt|R}} {{Man key press|Shift|Alt|M}} {{Man key press|Shift|Alt|N}}
|}

=== All List Views bindings ===

The following bindings are available in all list views: People, Families, Events, Places, Sources, Citations, Repositories, Media and Notes View.
{|{{prettytable}}
!Action/Function
!Microsoft Windows
!Mac OS
!KDE/GNOME
!Note
|-
| id="22" |Edits the selected list item
| |{{Man key press|Ctrl|Enter}}
| |
| |{{Man key press|Ctrl|Enter}}
| |
|-
| id="23" |Adds a new item to the database
| |{{Man key press|Ctrl|Insert}}
| |
| |{{Man key press|Ctrl|Insert}}
| |
|-
| id="24" |Deletes the selected list item
| |{{Man key press|Ctrl|Delete}}
| |
| |{{Man key press|Ctrl|Delete}}
| |
|-
| id="46" |Activate the {{man button|Find}} field
|!-- Microsoft Windows --> |{{Man key press|Ctrl|F}}
|!-- Mac OS --> |{{Man key press|Cmd|F}}
|!-- KDE/GNOME --> |{{Man key press|Ctrl|F}}
| | List view interactive search ahead / Quick search
|}

=== People View bindings ===

{|{{prettytable}}
!Action/Function
!Microsoft Windows
!Mac OS
!KDE/GNOME
|-
| id="25" |Expands and collapses entries of the selected surname in Group mode
| |{{Man key press|Enter}} or {{Man key press|Shift|Right}} (expand) {{Man key press|Shift|Left}} (collapse)
| |{{Man key press|Enter}} or {{Man key press|Shift|Right}} (expand) {{Man key press|Shift|Left}} (collapse)
| |{{Man key press|Enter}}
|-
| id="251" |Expands and contracts person selection in Group mode
| |{{Man key press|Shift|Up}} (Up arrow) {{Man key press|Shift|Down}} (Down arrow)
| |{{Man key press|Shift|Up}} (Up arrow) {{Man key press|Shift|Down}} (Down arrow)
| |
|}

==Editors==

=== Editor Tab bindings ===
These bindings work on the tab pages of the editors (so not on the labels of the tabs!, press tab on label to move to tabpage content).

{|{{prettytable}}
!Action/Function
!Microsoft Windows
!Mac OS
!KDE/GNOME
|-
| id="26" |Same action as the {{icon|Stock_edit}} button when that button is present
| |{{Man key press|Enter}}
| |{{Man key press|Return}} or {{Man key press|Enter}}
| |{{Man key press|Enter}}
|-
| id="27" |Same action as the {{icon|Stock_add}} button when that button is present
| |{{Man key press|Insert}}
| |
| |{{Man key press|Insert}}
|-
| id="28" |Same action as the {{icon|Stock_remove}} button when that button is present
| |{{Man key press|Delete}}
| |
| |{{Man key press|Delete}}
|-
| id="29" |Same action as the {{man button|Share}} button when that button is present
| |{{Man key press|Ctrl|O}}
| |{{Man key press|Cmd|O}}
| |{{Man key press|Ctrl|O}}
|-
| id="30" |Change tabpage to the tabpage to the left
| |{{Man key press|Alt|Left}} (Left arrow)
| |{{Man key press|Ctrl|Opt|Left}} (Left arrow)
| |{{Man key press|Alt|Left}} (Left arrow)
|-
| id="31" |Change tabpage to the tabpage to the right
| |{{Man key press|Alt|Right}} (Right arrow)
| |{{Man key press|Ctlr|Opt|Right}} (Right arrow)
| |{{Man key press|Alt|Right}} (Right arrow)
|}

{|{{prettytable}}
!Action/Function
!Mouse Key
|-
| id="32" |Call up [https://en.wikipedia.org/wiki/Context_menu context menu] popup
!Right-click
|-
| id="33" |Same action as the {{icon|Stock_edit}} {{man button|Edit}} button when that button is present
!Double-click
|-
| id="34" |Common action that is not the same as {{icon|Stock_edit}} {{man button|Edit}} button. Eg: on Family Editor Child tab, edit child
!Middle-click
|}

=== Editor bindings ===
These bindings work on Editors by activating focus or by changing state of toggle buttons ([[Accessibility]]).

{|{{prettytable}}
!Action/Function
!Microsoft Windows
!Mac OS
!KDE/GNOME
|-
| id="35" |Change the privacy status.
| |{{Man key press|Ctrl|P}}
| |{{Man key press|Cmd|P}}
| |{{Man key press|Ctrl|P}}
|-
| id="36" |Call the Date editor (if present).
| |{{Man key press|Ctrl|D}}
| |{{Man key press|Cmd|D}}
| |{{Man key press|Ctrl|D}}
|-
| id="37" |Activate the {{icon|Stock_add}} {{man button|Add}} button (if present).
| |{{Man key press|Ctrl|A}}
| |{{Man key press|Cmd|A}}
| |{{Man key press|Ctrl|A}}
|-
| id="38" |Activate the {{icon|Stock_edit}} {{man button|Edit}} button (if present).
| |{{Man key press|Ctrl|E}}
| |{{Man key press|Cmd|E}}
| |{{Man key press|Ctrl|E}}
|-
| id="39" |Activate the {{man button|Select}} button (if present).
| |{{Man key press|Ctrl|S}}
| |{{Man key press|Cmd|S}}
| |{{Man key press|Ctrl|S}}
|-
| id="40" |Activate the {{man button|Father}} button (if present).
| |{{Man key press|Ctrl|F}}
| |{{Man key press|Cmd|F}}
| |{{Man key press|Ctrl|F}}
|-
| id="41" |Activate the {{man button|Mother}} button (if present).
| |{{Man key press|Ctrl|M}}
| |{{Man key press|Cmd|M}}
| |{{Man key press|Ctrl|M}}
|}

==Handy Shortcuts==

{|{{prettytable}}
!Action/Function
!Microsoft Windows
!Mac OS
!KDE/GNOME
!Note
|-
| id="42" |Full screen
|{{man key press|F11}}
|
|{{man key press|F11}}
|Maximizes Gramps to use the Full screen
|-
| id="43" |Show this user manual
|{{man key press|F1}}
|{{man key press|F1}}
|{{man key press|F1}}
|
|-
| id="44" |Select the {{man button|OK}} button
|{{man key press|Alt}}+{{man key press|O}}
|
|
|Handy for use with low resolution screens
|-
| id="45" |Dismiss (Select the {{man button|Cancel}} button)
|{{man key press|Esc}}
|{{Man key press|⎋ Esc}}
|{{man key press|Esc}}
|Handy for use with low resolution screens
|-
| id="46" |Toggle Open/Save dialog between breadcrumbs and filepaths
| |{{Man key press|Ctrl|L}}
| |{{Man key press|Ctrl|L}} {{Man key press|Esc}}
| |{{Man key press|Ctrl|L}}
|Handy for pasting filepaths
|}

== Context menu==
A [https://wikipedia.org/wiki/Context_menu context pop-up menu] shows limited number of choice related to the currently selected item in a Graphical User Interface. The menu appears with right-click on an item in operating systems with a 2 or 3 button mouse. In the one button mouse macOS, a {{man button|Ctrl}}-click will bring up the [https://developer.apple.com/design/human-interface-guidelines/macos/menus/contextual-menus/ Contextual Menus].

Keybindings:
* In Windows, the '''[https://wikipedia.org/w/index.php?title=Menu_key Menu Key]''' (aka '''application key''') will show the context menu for the active field. Alternately, the {{man button|⇧ Shift}}+{{man button|F10}} [https://wikipedia.org/wiki/Keyboard_shortcut keyboard shortcut], or sometimes {{man button|Ctrl}}+{{man button|⇧ Shift}}+{{man button|F10}}
* In macOS, users will need to enable the Universal Access settings in the System Preferences.

{{man tip|Quick navigation to an object|The clipboard has a navigation shortcut. Copy any object to the Clipboard (by drag'n'drop or by selecting and pressing the {{man key press|Ctrl|C}} [[Gramps_5.1_Wiki_Manual_-_Keybindings|keybinding]]), then select the object on the Clipboard and right-click to reveal the [[Gramps_5.1_Wiki_Manual_-_Navigation#Clipboard_context_menu|Clipboard's contextual pop-up menu]]. The bottom menu item will offer to make the selected object active. The View will '''''not''''' navigate to the object's category.}}

See [[Gramps_{{man version}}_Wiki_Manual_-_Settings#Context_menu|Context Menu]]

== See also ==
* [http://en.wikipedia.org/wiki/Table_of_keyboard_shortcuts Table of keyboard shortcuts] - for major operating systems.

{{-}}
{{man index|Gramps 5.1 Wiki Manual - FAQ|Gramps 5.1 Wiki Manual - Command Line|5.1}}
{{languages|Gramps_5.1_Wiki_Manual_-_Keybindings}}
{{grampsmanualcopyright}}

[[Category:Documentation]]

Gramps 5.1 Wiki Manual - Reports - part 4

2020-11-08T16:50:48Z

Codefarmer: Add description of the family descendant tree.

{{man index|Gramps 5.1 Wiki Manual - Reports - part 3|Gramps_5.1_Wiki_Manual_-_Reports_-_part_5|5.1}}
{{languages|Gramps_5.1_Wiki_Manual_-_Reports - part 4}}
{{#vardefine:chapter|11.4}}
{{#vardefine:figure|0}}
Back to [[Gramps_5.1_Wiki_Manual_-_Reports|Index of Reports]].
<hr>
{{-}}
[[File:MenuOverview-Reports-GraphicalReports-50.png|right|thumb|450px|Fig. {{#var:chapter}}.{{#vardefineecho:figure|{{#expr:{{#var:figure}}+1}}}} {{man menu|Reports >Graphical Reports>...}} Menu overview]]
This section describes the different {{man label|Graphical Reports}} available in Gramps.
==Graphical Reports==

Graphical reports represent information in forms of charts and graphs. Most of the options are common among graphical reports, therefore they will be described only once, at the end of this section. The few options which are specific to a given report will be described directly in that report's entry. See also [[Gramps_5.1_Wiki_Manual_-_Reports_-_part_2#Substitution_Values|substitution values]].

The following graphical reports are available in Gramps:

===Common options===

Common options for text reports are the filename of the output, the format of the output, selected style, page size and orientation. For HTML reports, there is no page information. Instead, HTML options include the choice of the HTML template, either available in Gramps or a custom template defined by you. Optionally, the reports can be immediately opened with the default application.

{{man tip|Tip|The options used in reports are persistent. Each report remembers the options previously used.}}

The options which are specific to a given report will be described directly in that report's entry and on [[Gramps_5.1_Wiki_Manual_-_Command_Line#Action_options|Command line references]].

For each report there is a screen with on the top part tabs (like Paper Options...) and on the bottom part the '''Document Options'''. The number of tabs varies with the report.

====Paper Options====

[[File:TextReports-PaperOptions-tab-defaults-50.png|right|thumb|450px|Fig. {{#var:chapter}}.{{#vardefineecho:figure|{{#expr:{{#var:figure}}+1}}}} Paper Options - tab for Graphical Reports]]

With the {{man label|Paper Options}} tab you can change:
* {{man label|Paper format}}
** {{man label|Size}} '''Letter'''(default)
** {{man label|Width}} (<code>8.50</code> in. default)
** {{man label|Height}} (<code>11.00</code> in. default)
** {{man label|Orientation}} '''Portrait'''(default)
* {{man label|Margins}}
** {{man label|Left}}(<code>1.00</code> in. default)
** {{man label|Right}}(<code>1.00</code> in. default)
** {{man label|Top}}(<code>1.00</code> in. default)
** {{man label|Bottom}}(<code>1.00</code> in. default)
* {{checkbox|0}} {{man label|Metric}} : whether to use metric values or not (in. or cm.). (checkbox unchecked by default)

See also {{man label|[[Gramps_5.1_Wiki_Manual_-_Error_and_Warning_Reference#Report_could_not_be_created|Report could not be created]]}} dialog which may occur if your custom page size is too large.
{{-}}

====Document Options====
Options below will change slightly depending on the output format selected.
[[File:GraphicalReports-DocumentOptions-SVG-document-output-settings-50.png|right|thumb|450px|Fig. {{#var:chapter}}.{{#vardefineecho:figure|{{#expr:{{#var:figure}}+1}}}} Document Options - SVG document - output selected - example]]

*{{man label|Output Format}} choose the output format:
** ''SVG document'' : (Scalable Vector Graphics) for display with a web browser or editing with a suitable graphics editor.
** ''PostScript''
** ''OpenDocument Text'' (if you want to edit the report with Libreoffice/Openoffice)
** ''PDF document''
** ''Print...''
* {{checkbox|0}} {{man label|Open with default viewer}}: you can indicate to open the made document your default viewer. will open the created report using whatever program is defined on your system for handling the format selected.(checkbox unchecked by default)
* {{man label|Filename:}} default value is ''<code>/home/<username>/<Family Tree Name><Report Name>.<output format extension></code>''. by default the filename is the same as the report type, and it will be placed in your home directory. (In Windows it defaults to one level up from "My documents".)
* {{man label|Style:}} (default is ''default''). With the {{man button|[[Gramps_5.1_Wiki_Manual_-_Settings#Style_editor_dialog|Style Editor...]]}} button you can add Document Styles.
* {{man label|SVG Background color:}} ('''transparent background''' default)
{{-}}

====Select a person for the report selector====
The {{man label|Select a person for the report}} selector allows you to select an already existing person for the report and once selected they will be placed in {{man label|[[Gramps_5.1_Wiki_Manual_-_Reports_-_part_4#Tree Options|Tree Options]]}} as the Centre Person.
[[File:SelectAPersonForTheReport-SelectorDialog-example-50.png|right|thumb|450px|Fig. {{#var:chapter}}.{{#vardefineecho:figure|{{#expr:{{#var:figure}}+1}}}} "Select a person for the report" - selector dialog - example]]

It defaults to the current active person.

You may check the {{checkbox|0}}{{man label|Show all}} box to show the entire list of persons in the tree (checkbox unchecked by default).
{{-}}

====Scale and Resize options====
The tree is first made on a canvas that can fit a tree of any size. From that canvas the following options can change how it is finally displayed on a page.
{{-}}
====={{man label|Scale tree to fit}}:=====
This option will scale up/down the size of the report on the canvas to fit the size of the page (set in Paper Options) that you wish to print on. Currently you can:

* '''Do not scale tree''' (Default)
* ''Scale tree to fit page width only''
* ''Scale tree to fit the size of the page'' (both width and height)

{{man note|Note|For the last option, the report will scale to the lesser scale amount. If the report can be scaled up to fit the width, but needs to be scaled down further to fit the height, it will be scaled down leaving lots of room (empty white space) width-wise. Or if the report needs to be scaled down just a little for height and scaled down more for width, the report will be scaled down the most (width) leaving a gap (empty white space) at the bottom.}}

Without the Check box:{{man label|Resize Page to Fit Tree size.}} option checked, the following occurs for the ''Scale tree to fit'' selections:
* ''Do not scale the tree'' may give you a report that spans multiple pages horizontally and/or vertically
* ''Scale tree to fit page width only'' may still give you a report that spans multiple pages vertically. No pages to the sides of others. Only one on top of another.
* ''Scale tree to fit the size of the page'' will give you a one page only report. The report will print on a page the size set in Paper Options.

====={{man label|Resize Page to Fit Tree size}}=====
This option tells how big/small to resize the page we will print on. '''With this option unchecked''', the page size that is set in Paper Option. With this option checked the following happens based upon the three choices in {{man label|Scale tree to fit:}}.

{{man warn|Overrides options in the 'Paper Option' tab|This option will create irregular page sizes.}}

This overrides/ignores what is set on Paper Options and print on a page the same dimensions that the tree uses on the canvas. So taking the three options above, in scale tree to fit, this is what will happen if you select the 'Resize Page to Fit Tree size' option:

* With ''Do not scale the tree'', this option will completely ignore what is set in Paper Options and print on a page that is large enough to display the entire tree
* With ''Scale tree to fit page width only'', this option will ignore Paper Height that is set in Paper Options only. The tree has already been scaled up/down to fit the page width, so it is set. Only the page Height is set upon the height of the tree we are printing.
* With ''Scale tree to fit the size of the page'', the tree has already been scaled to the size of the page. But as noted above, either the width or height will (more than likely) have a gap (empty white space) in it. The {{man label|Resize Page to Fit Tree size}} will narrow down this gap on the page to remove that gap.

=====inter-box Y scale factor=====

:Make the inter-box Y bigger or smaller

=====box shadow scale factor=====

:Make the box shadow bigger or smaller

=====Know what you want to print on=====
Scaling a tree is an advanced function. The {{man label|Document Options}} → {{man label|Style}} sets the size of text that you can print. Scaling down is not very desirable as the text becomes more difficult to read. Scaling up is better but may have the some issues. So here are some pointers to make nice printed documents.

First thing first. What paper sizes can you print on? Ask around and see what page sizes you can print on easily. Just knowing what paper sizes you can print on helps a lot. At Kinkos (in the U.S.A) there is a 3 foot wide printer with paper that is on a roll (any length). So we could use 'Scale report to fit page width only' and 'One page report' for this.

It is also noteworthy to first make your report using {{man label|Scale tree to fit}}s ''Do not scale the report'' option and {{man label|Resize Page to Fit Tree size}} to know what the reports full dimensions (width and height) are. This will help you know how to better put this report on the pages you can print on. Here are some other quick things to take into account.
* A report that is very high and not too wide may print better with only the ''Scale report to fit page width only'' option.
* With the reports normal width, which will print better? Landscape or Portrait?
* Since every boxes width is set by the widest box, can you use the Descendant reports → Replace option to abbreviate or remove very long parts that are not needed?
* The size of the title. If there is room, you may want to make the title larger. And if it is too large, it will set the width of the report.

{{-}}

<hr>

===Ancestor Tree===
[[File:GraphicalReports-AncestorTree-example-landscape-50.png|thumb|right|450px|Fig. {{#var:chapter}}.{{#vardefineecho:figure|{{#expr:{{#var:figure}}+1}}}} Ancestor Tree - Graphical Reports - example output overview]]

This report generates the chart of people who are ancestors of the Active Person.

You can choose the Ancestor Tree report with {{man menu|Reports ->Graphical Reports -> Ancestor Tree...}}
{{-}}
See also [[Gramps_5.1_Wiki_Manual_-_Reports - part 4#Common options|common options]]
{{-}}
==== Tree Options ====

[[File:AncestorTree-GraphicalReports-TreeOptions-tab-50.png|right|thumb|450px|Fig. {{#var:chapter}}.{{#vardefineecho:figure|{{#expr:{{#var:figure}}+1}}}} Ancestor Tree - Graphical Reports - Tree Options - tab default options]]

The {{man button|Center Person}} is chosen here. The Active person will be the default.

* {{man label|[ ] Include siblings of the center person}}

With the input field {{man label|Generations}} you can change the number of generations considered.

{{man label|Display unknown generations}} will allow you to select how many generations of empty boxes to display when the tree is not completely full.

Here is also the check box {{man label|Compress tree}}.

{{-}}

==== Report Options ====

[[File:AncestorTree-GraphicalReports-ReportOptions-tab-50.png|right|thumb|450px|Fig. {{#var:chapter}}.{{#vardefineecho:figure|{{#expr:{{#var:figure}}+1}}}} Ancestor Tree - Graphical Reports - Report Options - tab default options (Gramps 5.1.0; Microsoft Windows 10) ]]

This tab gives you the option to include other items on the report.

{{man label|Report title}} allows you to choose a title for the report.
* ''Do not print a title''
* ''Include Report Title''

And this tab also includes check boxes for {{man label|Include a border}}, {{man label|Include page numbers}}, and {{man label|Include blank pages}}.

This tab also allows you to {{man label|Include a note}} to one of the corners of the report.

“$T” within the note will display the day that the report was made. Regular date formatting (see [[Gramps_5.1_Wiki_Manual_-_Reports_-_part_2|Substitution Values]]) applies.

Currently a note will be attached to a corner. If a person box writes over it, the note box will not move. Select another corner to see the note tab if this happens.

{{man label|Scale tree to fit}} will make the tree larger or smaller to fit the page as desired. The options are:
* Do not Scale the tree
* Scale tree to fit page width only
* Scale tree to fit the size of the page

where {{man label|Resize page to fit tree}} will make the page larger or smaller to fit the tree

If both are selected, the options happen in that order; scale the tree first, then the page.

These two options are better described in [[Gramps_5.1_Wiki_Manual_-_Reports - part 4#Common options|common options]] with tips for making nicer reports.
{{-}}

====Report Options (2)====
[[File:AncestorTree-GraphicalReports-ReportOptions2-tab-50.png|right|thumb|450px|Fig. {{#var:chapter}}.{{#vardefineecho:figure|{{#expr:{{#var:figure}}+1}}}} Ancestor Tree - Graphical Reports - Report Options (2) - tab default options]]
* {{man label|Name Format}}: Select the format to display names. Choose from '''Surname, Given Suffix''' (default) / Given Surname Suffix/ Given/ Main Surnames, Given Patronymic Suffix Prefix
* {{man label|Living people}}: Select to include or not living persons in the report. Choose from '''Include, and all data''' (default) / Full names, but data removed / Given names replaced, and data removed / Complete names replaced, and data removed/ Not included
* {{man label|Years from death to consider living}}: Select the number of years since death to consider persons for the report. Allows for the inclusion or exclusion of recently-dead persons in the report. Default value is 0 years.
** {{checkbox|1}} {{man label|Include data marked private}} (checkbox checked by default)
* {{man label|Translation}}: The translation to be used for the report. Language selector
* {{man label|Date Format}}: Select the format to display dates. Choose from '''YYYY-MM-DD (ISO)(2018-04-08)'''(default) / Numerical (8/4/2018) / Month Day, Year (April 8, 2018) / Mon Day, Year (Apr 8, 2018)/ Day Month Year (8 April 2018)/ Day Mon Year (8 Apr 2018)

{{-}}

==== Display ====

[[File:AncestorTree-GraphicalReports-Display-tab-50.png|right|thumb|450px|Fig. {{#var:chapter}}.{{#vardefineecho:figure|{{#expr:{{#var:figure}}+1}}}} Ancestor Tree - Graphical Reports - Display - tab default options]]

This tab allows you to determine the {{man label|Father Display Format}} to be used for the report. All fathers, grandfathers, etc. will use this format.

The {{man label|Mother Display Format}} to be used for all mothers, grandmothers, etc. will use this format.

The {} around the death information line states that the text 'd. ' will display ONLY when there is death information. See [[Gramps_5.1_Wiki_Manual_-_Reports_-_part_2|Substitution Values]] for more information, including how to include places and attributes, and format names and dates and places.

{{man label|Center person uses which format:}} allows you to specify if the center person uses the father display format or the mother display format found on the Display tab.

{{man label|Include Marriage box}} specifies to display an extra box between a father and mother that contains marriage information. {{man label|The Marriage Display Format}} (see [[Gramps_5.1_Wiki_Manual_-_Reports_-_part_2|Substitution Values]]) specifies what will print in this box.

{{-}}

==== Advanced ====

[[File:AncestorTree-GraphicalReports-Advanced-tab-50.png|right|thumb|450px|Fig. {{#var:chapter}}.{{#vardefineecho:figure|{{#expr:{{#var:figure}}+1}}}} Ancestor Tree - Graphical Reports - Advanced - tab default options]]
* {{man label|Replace Display Format: 'Replace this'/'With this'}}: This allows you to put in pairs of strings separated by '/' that specify text you want to replace with other text. For example, <pre>United States of America/USA</pre> replaces the United States of America with USA.
** {{checkbox|0}} {{man label|Include a note}} You may check the Include a note box to add a note (checkbox unchecked by default). The {{man label|Note}} specifies text the note will contain.
* {{man label|Note location}}: Specify where on the page to place the note (default is bottom left).
* {{man label|inter-box scale factor}}: Make the inter-box bigger or smaller (default is 1.00 in.).
* {{man label|box shadow scale factor}}: Make the box shadow bigger or smaller (default is 1.00 in.).

These two options are better described in [[Gramps_5.1_Wiki_Manual_-_Reports_-_part_5.1|Size options]] with tips for making nicer reports.

{{-}}

===Calendar===

[[File:GraphicalReports-Calendar-example-landscape-50.png|right|thumb|450px|Fig. {{#var:chapter}}.{{#vardefineecho:figure|{{#expr:{{#var:figure}}+1}}}} Calendar - Graphical Reports - example output overview]]

This report produces a calendar with birthdays and anniversaries on a page by month.

You can choose the Calendar report with {{man menu|Reports ->Graphical Reports -> Calendar...}}

You can print the same information but in text format by using the [[Gramps_5.1_Wiki_Manual_-_Reports_-_part_6#Birthday_and_Anniversary_Report|Birthday and Anniversary Report]].

See [[Calendar_tools_holidays|Calendar tools holidays]] for an explanation of how to add or change the holidays appearing on the output of this calendar.
{{-}}
See also [[Gramps_5.1_Wiki_Manual_-_Reports - part 4#Common options|common options]]
{{-}}
====Report Options====

[[File:Calendar-GraphicalReports-ReportOptions-tab-50.png|right|thumb|450px|Fig. {{#var:chapter}}.{{#vardefineecho:figure|{{#expr:{{#var:figure}}+1}}}} Calendar - Graphical Reports - Report Options - tab default options]]

* {{man label|Filter:}} choose between
** '''Entire Database''' (Default)
** Descendants of active person
** Descendant families of active person
** Ancestors of active person
** People with common ancestor with active person
* {{man label|Center Person:}} The center person for the report usually the active person unless you use the :
** {{man button:Select a different person}} button to use {{man label|[[Gramps_5.1_Wiki_Manual_-_Reports_-_part_4#Select_a_person_for_the_report_selector|Select a person for the report]]}} selector dialog.
* {{man label|Text Area 1:}} (<code>My Calendar</code> default) First line of text at bottom of calendar.
* {{man label|Text Area 2:}} (<code>Produced by Gramps</code> default) Second line of text at bottom of calendar.
* {{man label|Text Area 3:}} (<code>http://gramps-project.org/</code> default) Third line of text at bottom of calendar.
{{-}}

====Report Options (2)====
[[File:Calendar-GraphicalReports-ReportOptions2-tab-50.png|right|thumb|450px|Fig. {{#var:chapter}}.{{#vardefineecho:figure|{{#expr:{{#var:figure}}+1}}}} Calendar - Graphical Reports - Report Options (2) - tab default options]]
* {{man label|Name Format:}} Select the format to display the names. Choose from '''Surname, Given Suffix'''(default) / Given Surname Suffix / Given / Main Surnames, Given Patronymic Suffix / SURNAME, Given (Common)
** {{checkbox|1}} {{man label|Include data marked private}} (checkbox checked by default)
** {{checkbox|1}} {{man label|Include only living people}} (checkbox checked by default)
* {{man label|Translation:}} The translation to be used for the report. Language selector
{{-}}

====Content====

[[File:Calendar-GraphicalReports-Content-tab-50.png|right|thumb|450px|Fig. {{#var:chapter}}.{{#vardefineecho:figure|{{#expr:{{#var:figure}}+1}}}} Calendar - Graphical Reports - Content - tab default options]]

* {{man label|Year of report:}} fill in the year. Defaults to current Year.
* {{man label|Country for holidays:}} Select the country to see associated holidays.
* {{man label|First day of week:}} (Default: '''Monday''') Select the first day of the week for the report.
* {{man label|Birthday surname:}} Select married women's displayed surname.
** '''Wives use their own surname''' (Default)
** Wives use husband's surname (from first family listed)
** Wives use husband's surname (from last family listed)
* {{checkbox|1}} {{man label|Include birthdays}} : include or not birthdays in the calendar (checkbox checked by default)
* {{checkbox|1}} {{man label|Include anniversaries}} : include or not anniversaries in the calendar (checkbox checked by default)
{{-}}

===Descendant Tree===

[[File:GraphicalReports-DescendantTree-example-portrait-50.png|right|thumb|450px|Fig. {{#var:chapter}}.{{#vardefineecho:figure|{{#expr:{{#var:figure}}+1}}}} Descendant Tree - Graphical Reports - example output overview]]

This report generates a chart of people who are descendants of the starting person. Alternatively it may generate a chart of descendants of the parents of the starting person.

You can choose the Descendant Tree report with {{man menu|Reports ->Graphical Reports -> Descendant Tree...}}
{{-}}
See also [[Gramps_5.1_Wiki_Manual_-_Reports - part 4#Common options|common options]]
{{-}}
==== Tree Options ====

[[File:DescendantTree-GraphicalReports-TreeOptions-tab-50.png|right|thumb|450px|Fig. {{#var:chapter}}.{{#vardefineecho:figure|{{#expr:{{#var:figure}}+1}}}} Descendant Tree - Graphical Reports - Tree Options - tab default options]]
{{man label|Report for:}} selects the starting person for the report. It defaults to the current active person.

{{man label|Generations}} (<code>10</code> default ). The number of generations to show on the chart (including the starting person). If {{man label|Start with the parent(s) of the selected first}} is selected, the chart will include one more generation. (Example 1 was run with {{man label|Generations}}=3, Example 2 with {{man label|Generations}}=2.)

{{man label|Level of spouses}} specifies how deep to display spouses.

{{man label|Start with the parent(s) of the selected first}} will draw a descendancy chart from the parents of the starting person,
if they are in the database. The [[Gramps_5.1_Wiki_Manual_-_Reports_-_part_4#Examples|Example]] is based on the same family as the first example and shows the result of starting with "Child 2 Davies" and ticking this box.

{{-}}
Example 1 was obtained by selecting Allan Davies as the starting person and then running the report without this box ticked, with all other options the same except {{man label|Generations}}. The differences between the two examples are:
* The format of the first generation is changed. Because the parents of the starting person must be adjacent, spouses in the first generation may be shown out of order.
* For the purpose of the {{man label|Level of spouses}} setting, both parents are considered direct descendants, rather than spouses. (Although the mother uses the {{man label|Spousal display format }}on the Display tab.)
This means that other spouses (if any) of both of them will be shown to the number of
levels specified by {{man label|Level of spouses}}. In example 2, Mike Morris is shown even though {{man label|Level of spouses}} is set to 1.
* The title of the report (if selected on the Include tab) is changed to include both parents of the starting person. Only two people are shown in the title. In example 2, Mike Morris is not listed in the title even though his descendants are shown.

For the example:

* Abe is a direct descendant
** Abe has/had married Barbra and had two children
** Abe also married Bridget and had one child
*** Bridget has/had married Carl.
**** Carl and Denise had a child.

Given the above example, this is what will be displayed for the first three {{man label|Level of spouses}} options.
* 0 means that only direct descendants will be shown. Nothing on the Secondary tab will be shown (Spousal information or Marriage information). For the example above, only Abe will be shown with three children directly under him
* 1 means that only spouses of the direct descendants will be shown. For the example above, Abe will be shown with two pieces of marriage information. Under the first will be two children and one child under the second.
* 2 means that spouses of spouses are shown. Same as 1 but Bridget will also show her other marriage. If they had any children, they would be shown too.
* 3 means that everyone in the example above will be displayed.
Any option above 1 is very hard to read on the report without the {{man label|Indent Spouses}} option on the Display tab.

And last but not least is the {{man label|Compress Tree}} option which tries to move everyone up as far as they can go (compress) and still have a readable report. If {{man label|Start with the parent(s) of the selected first}} is ticked, {{man label|Compress Tree}} does not have any affect on the first generation.
{{-}}

====Report Options====
[[File:DescendantTree-GraphicalReports-ReportOptions-tab-50.png|right|thumb|450px|Fig. {{#var:chapter}}.{{#vardefineecho:figure|{{#expr:{{#var:figure}}+1}}}} Descendant Tree - Graphical Reports - Report Options - tab default options]]

{{man label|Report title}} allows you to choose a title for the report. Options are:
* ''Do not include a title''
* ''Descendant Chart for [selected person(s)]''

If "Start with Parents of Selected" is ticked on the "Tree Options" tab, both parents of the selected person are shown. Only two people will be listed in the title. If "level of spouses" is two or more, descendants of "spouses of spouses" are included on the chart, but are not listed in the title.

{{man label|Scale tree to fit }} Scale tree to fit will make the tree larger or smaller to fit the page as desired. The options are:
* ''Do not scale the tree (Default)''
*'' Scale tree to fit page width only''
* ''Scale tree to fit the size of the page''
*{{checkbox|0}} {{man label|Resize page to fit tree}}: Resize page to fit tree (unchecked by default) will make the page larger or smaller to fit the tree. If selected with the "Scale tree to fit", the options happen in that order; scale the tree first, then the page. There is a combined effect with each option:
** With "Do not scale the tree", both the page width and height is resized to fit the tree.
** With "Scale tree to fit page width only", the page height is resized to fit the tree height.
** With "Scale tree to fit the size of the page", the page is resized to remove any gap in both height and width.

{{man note|Overrides options in the Paper Option tab.| Resize page to fit tree overrides options in the Paper Option. }}
These two options are better described in [[Gramps_5.1_Wiki_Manual_-_Reports - part 4#Common options|common options]] with tips for making nicer reports.
This tab also includes check boxes to {{man label|Include a border}}, {{man label|Include page numbers}}, and {{man label|Include blank pages}}.

{{-}}

====Report Options (2)====
[[File:DescendantTree-GraphicalReports-ReportOptions2-tab-50.png|right|thumb|450px|Fig. {{#var:chapter}}.{{#vardefineecho:figure|{{#expr:{{#var:figure}}+1}}}} Descendant Tree - Graphical Reports - Report Options (2) - tab default options]]
* {{man label|Name Format}}: Select the format to display names. Choose from '''Surname, Given Suffix''' (default) / Given Surname Suffix/ Given/ Main Surnames, Given Patronymic Suffix Prefix
** {{checkbox|1}} {{man label|Include data marked private}} (checkbox checked by default)
* {{man label|Living people}}: Select to include or not living persons in the report. Choose from '''Include, and all data''' (default) / Full names, but data removed / Given names replaced, and data removed / Complete names replaced, and data removed/ Not included
* {{man label|Years from death to consider living}}: Select the number of years since death to consider persons for the report. Allows for the inclusion or exclusion of recently-dead persons in the report. Default value is 0 years.
* {{man label|Translation}}: The translation to be used for the report. Language selector
* {{man label|Date Format}}: Select the format to display dates. Choose from '''YYYY-MM-DD (ISO)(2018-04-08)'''(default) / Numerical (8/4/2018) / Month Day, Year (April 8, 2018) / Mon Day, Year (Apr 8, 2018)/ Day Month Year (8 April 2018)/ Day Mon Year (8 Apr 2018)

{{-}}

==== Display ====

[[File:DescendantTree-GraphicalReports-Display-tab-50.png|right|thumb|450px|Fig. {{#var:chapter}}.{{#vardefineecho:figure|{{#expr:{{#var:figure}}+1}}}} Descendant Tree - Graphical Reports - Display - tab default options]]

{{man label|Descendant Display Format}} sets the display for all descendants in the tree. The default is:
<pre>$n
b. $b
{d. $d}</pre>

which displays the name, birth date and death date on consecutive lines in the formats set on the Display tab in Gramps preferences. The {} on the third line states that the text 'd. ' will display ONLY when $d has a value, i.e. there is something in the death date field of the database for this person. See [[Gramps_5.1_Wiki_Manual_-_Reports_-_part_2|Substitution Values]] for more information, including how to include places and attributes, and select different formats for names and dates and places.

The check box {{man label|Bold direct descendants}} causes the names and other information about direct descendants to be in the bold font selected in the style editor.

{{man label|Spousal Display format}} specifies what is displayed for each spouse. The default is the same as for descendants. If you do not wish to have a separate box for marriage information, it can be displayed in the spouse box, for example by adding a line with
<pre>
m. $m
</pre>

Which displays the date of the marriage.

{{man label|Indent spouses}} will indent the spouse and marriage boxes from the descendant boxes. In the Family Descendant Chart, it does not affect the starting family or the parents of the starting family, but it does affect any other spouses of those three couples.

{{man label|Include marriage box}} will display a separate box on the tree for each marriage. The display format is set in {{man label|Marriage Display format}}. The default is
<pre>
m. $m
</pre>

which displays the date of the marriage. If this box is not ticked, marriage information will not be displayed unless you specify it in the spousal display format as described above.

{{-}}

==== Advanced ====
[[File:DescendantTree-GraphicalReports-Advanced-tab-50.png|right|thumb|400px|Fig. {{#var:chapter}}.{{#vardefineecho:figure|{{#expr:{{#var:figure}}+1}}}} Descendant Tree - Graphical Reports - Advanced - tab default options]]

Pairs of strings separated by a slash '/' specify what you want to replace and what you want to replace it with.

Example:
<pre>The United States of America/USA
United Kingdom of Great Britain and Northern Ireland/UK
Llanfairpwllgwyngyllgogerychwyrndrobwllllantysiliogogogoch/Llanfairpwll</pre>
Each column width is defined by the widest box in the report. So if one box happens to be a lot wider than the rest, a lot of space will be wasted. The replace string option allows you to remove, or abbreviate, parts of the string that is not needed, or that can be cut down, so the amount of space wasted is minimal.

In this tab you can also {{man label|Include a note}} in one of the corners of the report.

For example, adding the “$T” variable in the note box will display the day the report was created.
Regular date formatting (see [[Gramps_5.1_Wiki_Manual_-_Reports_-_part_2#Substitution_Values|Substitution Values]]) applies.

{{man warn|Currently a note will be attached to a corner.|If a person box writes over it, the note box will not move. Select another corner to see the note tab if this happens.}}

{{-}}

==== Examples ====
{{stub}}
[[Image:Descendant_tree_example1.png|left|thumb|450px|Fig. {{#var:chapter}}.{{#vardefineecho:figure|{{#expr:{{#var:figure}}+1}}}} Descendant Tree Report, Example 1. Allan Davies had three spouses.]]

[[Image:Descendant_tree_example2.png|right|thumb|450px|Fig. {{#var:chapter}}.{{#vardefineecho:figure|{{#expr:{{#var:figure}}+1}}}} Descendant Tree Report, Example 2.]]

{{-}}
{{man label|Report for:}} selects the starting person for the report. It defaults to the current active person.

{{man label|Start with the parent(s) of the selected first}} will draw a descendancy chart from the parents of the starting person,
if they are in the database. The example below is based on the same family as the first example and shows the result of starting with "Child 2 Davies" and ticking this box.

{{-}}
Example 1 was obtained by selecting Allan Davies as the starting person and then running the report without this box ticked, with all other options the same except {{man label|Generations}}. The differences between the two examples are:
* The format of the first generation is changed. Because the parents of the starting person must be adjacent, spouses in the first generation may be shown out of order.
* For the purpose of the {{man label|Level of spouses}} setting, both parents are considered direct descendants, rather than spouses. (Although the mother uses the {{man label|Spousal display format }}on the Display tab.)
This means that other spouses (if any) of both of them will be shown to the number of
levels specified by {{man label|Level of spouses}}. In example 2, Mike Morris is shown even though {{man label|Level of spouses}} is set to 1.
* The title of the report (if selected on the Include tab) is changed to include both parents of the starting person. Only two people are shown in the title. In example 2, Mike Morris is not listed in the title even though his descendants are shown.

{{man label|Generations}} The number of generations to show on the report (including the starting person). If {{man label|Start with the parent(s) of the selected first}} is selected, the chart will include one more generation. (Example 1 was run with {{man label|Generations}}=3, Example 2 with {{man label|Generations}}=2.)

{{man label|Level of spouses}} specifies how deep to display spouses.

For the example:

* Abe is a direct descendant
** Abe has/had married Barbra and had two children
** Abe also married Bridget and had one child
*** Bridget has/had married Carl.
**** Carl and Denise had a child.

Given the above example, this is what will be displayed for the first three {{man label|Level of spouses}} options.
* 0 means that only direct descendants will be shown. Nothing on the Secondary tab will be shown (Spousal information or Marriage information). For the example above, only Abe will be shown with three children directly under him
* 1 means that only spouses of the direct descendants will be shown. For the example above, Abe will be shown with two pieces of marriage information. Under the first will be two children and one child under the second.
* 2 means that spouses of spouses are shown. Same as 1 but Bridget will also show her other marriage. If they had any children, they would be shown too.
* 3 means that everyone in the example above will be displayed.
Any option above 1 is very hard to read on the report without the {{man label|Indent Spouses}} option on the Display tab.

And last but not least is the {{man label|Compress Tree}} option which tries to move everyone up as far as they can go (compress) and still have a readable report. If {{man label|Start with the parent(s) of the selected first}} is ticked, {{man label|Compress Tree}} does not have any affect on the first generation.
{{-}}

===Family Descendant Tree===

{{man note|Shared options with the [[#Descendant Tree|Descendant Tree report]]|This report has the same options as the 'Descendant Tree' report, except that there are more options for the report title on the Include tab. Also, some of the options have a different effect. Options are only described here if they differ between the two reports.}}

[[File:GraphicalReports-FamilyDescendantTree-example-portrait-50.png|right|thumb|450px|Fig. {{#var:chapter}}.{{#vardefineecho:figure|{{#expr:{{#var:figure}}+1}}}} Family Descendant Tree - Graphical Reports - example output overview]]

This report generates a chart of people who are descendants of the Active Family.

You can choose the Family Descendant Tree report with {{man menu|Reports ->Graphical Reports -> Family Descendant Tree...}}
{{-}}
See also [[Gramps_5.1_Wiki_Manual_-_Reports - part 4#Common options|common options]]
{{-}}
==== Tree Options ====
[[File:FamilyDescendantTree-GraphicalReports-TreeOptions-tab-50.png|right|thumb|450px|Fig. {{#var:chapter}}.{{#vardefineecho:figure|{{#expr:{{#var:figure}}+1}}}} Family Descendant Tree - Graphical Reports - Tree Options - tab default options]]

{{man button|Report for:}} will select the starting family (Father and Mother) for this report. It defaults to the currently active family.

{{man label|Generations}} (<code>10</code> default ). The number of generations to show on the chart (including the starting person). If {{man label|Start with the parent(s) of the selected first}} is selected, the chart will include one more generation. (Example 1 was run with {{man label|Generations}}=3, Example 2 with {{man label|Generations}}=2.)

{{man label|Level of spouses}} specifies how deep to display spouses.

{{man label|Start with the parent(s) of the selected first}} If this box is ticked, the report shows both parents of the starting father and mother (if they are in the database),
and all descendants of both sets of parents for the selected number of generations. The total number of generations
in the chart is therefore 1 more than the number selected in the generations box. (The example chart above was made
with generations=2.)

The starting father and mother have to be in the center of the chart.
They will therefore not be shown in birth order with their siblings - instead they will be shown as the last and first
child of their parents respectively. This is shown in the [[Gramps_5.1_Wiki_Manual_-_Reports_-_part_4#Examples|Examples]] chart, where the children in both families
have been named Child 1,2,3 in their birth order. Furthermore, if the starting father or mother have other spouses they will be shown twice. This also applies to the parents of the starting father or mother.

If this box is not ticked, the report is the same as the descendant tree report, except that the
number of generations is increased by one, the format of the first generation is different,
and you get extra options for the chart title.

{{-}}

====Report Options====
[[File:FamilyDescendantTree-GraphicalReports-ReportOptions-tab-50.png|right|thumb|450px|Fig. {{#var:chapter}}.{{#vardefineecho:figure|{{#expr:{{#var:figure}}+1}}}} Family Descendant Tree - Graphical Reports - Report Options - tab default options]]
{{man label|Report title}} allows you to choose a title for the report. Options are:
* ''Do not include a title''
* ''Descendant Chart for [selected person(s)]''

If "Start with Parents of Selected" is ticked on the "Tree Options" tab, both parents of the selected person are shown. Only two people will be listed in the title. If "level of spouses" is two or more, descendants of "spouses of spouses" are included on the chart, but are not listed in the title.

{{man label|Scale tree to fit }} Scale tree to fit will make the tree larger or smaller to fit the page as desired. The options are:
* ''Do not scale the tree (Default)''
*'' Scale tree to fit page width only''
* ''Scale tree to fit the size of the page''
*{{checkbox|0}} {{man label|Resize page to fit tree}}: Resize page to fit tree (unchecked by default) will make the page larger or smaller to fit the tree. If selected with the "Scale tree to fit", the options happen in that order; scale the tree first, then the page. There is a combined effect with each option:
** With "Do not scale the tree", both the page width and height is resized to fit the tree.
** With "Scale tree to fit page width only", the page height is resized to fit the tree height.
** With "Scale tree to fit the size of the page", the page is resized to remove any gap in both height and width.

{{man note|Overrides options in the Paper Option tab.| Resize page to fit tree overrides options in the Paper Option. }}
These two options are better described in [[Gramps_5.1_Wiki_Manual_-_Reports - part 4#Common options|common options]] with tips for making nicer reports.
This tab also includes check boxes to {{man label|Include a border}}, {{man label|Include page numbers}}, and {{man label|Include blank pages}}.

{{-}}

====Report Options (2)====
[[File:FamilyDescendantTree-GraphicalReports-ReportOptions2-tab-50.png|right|thumb|450px|Fig. {{#var:chapter}}.{{#vardefineecho:figure|{{#expr:{{#var:figure}}+1}}}} Family Descendant Tree - Graphical Reports - Report Options (2) - tab default options]]
* {{man label|Name Format}}: Select the format to display names. Choose from '''Surname, Given Suffix''' (default) / Given Surname Suffix/ Given/ Main Surnames, Given Patronymic Suffix Prefix
** {{checkbox|1}} {{man label|Include data marked private}} (checkbox checked by default)
* {{man label|Living people}}: Select to include or not living persons in the report. Choose from '''Include, and all data''' (default) / Full names, but data removed / Given names replaced, and data removed / Complete names replaced, and data removed/ Not included
* {{man label|Years from death to consider living}}: Select the number of years since death to consider persons for the report. Allows for the inclusion or exclusion of recently-dead persons in the report. Default value is 0 years.
* {{man label|Translation}}: The translation to be used for the report. Language selector
* {{man label|Date Format}}: Select the format to display dates. Choose from '''YYYY-MM-DD (ISO)(2018-04-08)'''(default) / Numerical (8/4/2018) / Month Day, Year (April 8, 2018) / Mon Day, Year (Apr 8, 2018)/ Day Month Year (8 April 2018)/ Day Mon Year (8 Apr 2018)

{{-}}

==== Display ====

[[File:FamilyDescendantTree-GraphicalReports-Display-tab-50.png|right|thumb|450px|Fig. {{#var:chapter}}.{{#vardefineecho:figure|{{#expr:{{#var:figure}}+1}}}} Family Descendant Tree - Graphical Reports - Display - tab default options]]

{{man label|Descendant Display Format}} sets the display for all descendants in the tree. The default is:
<pre>$n
b. $b
{d. $d}</pre>

which displays the name, birth date and death date on consecutive lines in the formats set on the Display tab in Gramps preferences. The {} on the third line states that the text 'd. ' will display ONLY when $d has a value, i.e. there is something in the death date field of the database for this person. See [[Gramps_5.1_Wiki_Manual_-_Reports_-_part_2|Substitution Values]] for more information, including how to include places and attributes, and select different formats for names and dates and places.

{{man label|Spousal Display format}} specifies what is displayed for each spouse. The default is the same as for descendants. If you do not wish to have a separate box for marriage information, it can be displayed in the spouse box, for example by adding a line with
<pre>
m. $m
</pre>

Which displays the date of the marriage.

{{man label|Indent spouses}} will indent the spouse and marriage boxes from the descendant boxes. In the Family Descendant Chart, it does not affect the starting family or the parents of the starting family, but it does affect any other spouses of those three couples.

{{man label|Include marriage box}} will display a separate box on the tree for each marriage. The display format is set in {{man label|Marriage Display format}}. The default is
<pre>
m. $m
</pre>

which displays the date of the marriage. If this box is not ticked, marriage information will not be displayed unless you specify it in the spousal display format as described above.

{{-}}

==== Advanced ====

[[File:FamilyDescendantTree-GraphicalReports-Advanced-tab-50.png|right|thumb|450px|Fig. {{#var:chapter}}.{{#vardefineecho:figure|{{#expr:{{#var:figure}}+1}}}} Family Descendant Tree - Graphical Reports - Advanced - tab default options]]

* {{man label|Replace Display Format: 'Replace this'/'With this'}}: This allows you to put in pairs of strings separated by '/' that specify text you want to replace with other text. For example, <pre>United States of America/USA</pre> replaces the United States of America with USA.
** {{checkbox|0}} {{man label|Include a note}} You may check the Include a note box to add a note (checkbox unchecked by default). The {{man label|Note}} specifies text the note will contain.
* {{man label|Note location}}: Specify where on the page to place the note (default is bottom left).
* {{man label|inter-box scale factor}}: Make the inter-box bigger or smaller (default is 1.00 in.).
* {{man label|box shadow scale factor}}: Make the box shadow bigger or smaller (default is 1.00 in.).

These two options are better described in [[Gramps_5.1_Wiki_Manual_-_Reports_-_part 4#Common options|common options]] with tips for making nicer reports.

{{-}}

===Fan Chart===

[[File:GraphicalReports-FanChart-example-landscape-50.png|right|thumb|450px|Fig. {{#var:chapter}}.{{#vardefineecho:figure|{{#expr:{{#var:figure}}+1}}}} Fan Chart - Graphical Reports - example output overview]]

This report produces a chart resembling a fan, with Active person in the center, parents the semicircle next to it, grandparents in the next semicircle, and so on, for a total of five generations.

You can choose the Fan Chart report with {{man menu|Reports ->Graphical Reports -> Fan Chart...}}
{{-}}
See also [[Gramps_5.1_Wiki_Manual_-_Reports - part 4#Common options|common options]]
{{-}}
====Report Options====

[[File:FanChart-GraphicalReports-ReportOptions-tab-50.png|right|thumb|450px|Fig. {{#var:chapter}}.{{#vardefineecho:figure|{{#expr:{{#var:figure}}+1}}}} Fan Chart - Graphical Reports - Report Options - tab default options]]

* {{man label|Center Person:}} The center person for the report.
{{man warn|'''CAVEAT'''|A "Person ____ is not in the Database" error will appear if the Center Person is Private or Living while the filtering Report Options (2) settings do not allow Private or Living Persons.}}
* {{man label|Generations:}} (<code>5</code> default ) The number of generations to include in the report.
* {{man label|Type of graph:}} The form of the graph.
** full circle
** '''half circle'''(Default)
** quarter circle
* {{man label|Background color:}} Background color is either white or '''generation dependent'''(Default).
* {{man label|Orientation of radial texts:}} Print radial text '''upright'''(Default) or roundabout.
* {{checkbox|1}} {{man label|Draw empty boxes}}: Draw the background although there is no information (checkbox checked by default)
* {{checkbox|1}} {{man label|Use one font style for all generations}} : You can customize font and color for each generation in the style editor (checkbox checked by default)
{{-}}

====Report Options (2)====
[[File:FanChart-GraphicalReports-ReportOptions2-tab-50.png|right|thumb|450px|Fig. {{#var:chapter}}.{{#vardefineecho:figure|{{#expr:{{#var:figure}}+1}}}} Fan Chart - Graphical Reports - Report Options (2) - tab default options]]
* {{checkbox|1}} {{man label|Include data marked private}} (checkbox checked by default)
* {{man label|Living people}}: Select to include or not living persons in the report. Choose from '''Include, and all data''' (default) / Full names, but data removed / Given names replaced, and data removed / Complete names replaced, and data removed/ Not included
* {{man label|Years from death to consider living}}: Select the number of years since death to consider persons for the report. Allows for the inclusion or exclusion of recently-dead persons in the report. Default value is 0 years.
* {{man label|Translation}}: The translation to be used for the report. Language selector

{{-}}

===Statistics Charts===
This report displays statistical data about your Family Tree.
<gallery caption= "Statistics Charts - Graphical Reports - example output overview (Gramps 5.1.0; Microsoft Windows 10; data from example.gramps)">
</gallery>
<div><ul>
<li style="display: inline-block;"> [[File:GraphicalReports-StatisticsCharts-Chart1-example-portrait-50.png|right|thumb|250px|Fig. {{#var:chapter}}.{{#vardefineecho:figure|{{#expr:{{#var:figure}}+1}}}} Chart 1 (Birth Month) ]] </li>
<li style="display: inline-block;"> [[File:GraphicalReports-StatisticsCharts-Chart3-Gender-example-portrait-50.png|right|thumb|250px|Fig. {{#var:chapter}}.{{#vardefineecho:figure|{{#expr:{{#var:figure}}+1}}}} Chart 3 (Gender) ]] </li>
<li style="display: inline-block;"> [[File:GraphicalReports-StatisticsCharts-Chart3-example-portrait-50.png|right|thumb|250px|Fig. {{#var:chapter}}.{{#vardefineecho:figure|{{#expr:{{#var:figure}}+1}}}} Chart 3 (Number of children) - ]] </li>
</ul></div>

You can choose the Statistics Charts report with {{man menu|Reports ->Graphical Reports -> Statistics Charts...}}

Specific options include filter, sorting methods, and additional birth- and gender-based limit for inclusion into statistics. You can also set the minimum number of items to qualify for the bar chart, so that the charts with fewer items will generate a pie chart instead. The {{man label|[[Gramps_5.1_Wiki_Manual_-_Reports_-_part_4#Charts_1|Charts 1]]}}, {{man label|[[Gramps_5.1_Wiki_Manual_-_Reports_-_part_4#Charts_2|Charts 2]]}} and {{man label|[[Gramps_5.1_Wiki_Manual_-_Reports_-_part_4#Charts_3|Charts 3]]}}tabs allows you to select which additional information to include on each individual chart in your report.
{{-}}
See also [[Gramps_5.1_Wiki_Manual_-_Reports - part 4#Common options|common options]]
{{-}}
====Report Options====

[[File:StatisticsCharts-GraphicalReports-ReportOptions-tab-50.png|right|thumb|450px|right|Fig. {{#var:chapter}}.{{#vardefineecho:figure|{{#expr:{{#var:figure}}+1}}}} Statistics Charts - Graphical Reports - Report Options - tab default options]]

* {{man label|Filter:}} choose between
** '''Entire Database''' (Default)
** Descendants of active person
** Descendant families of active person
** Ancestors of active person
** People with common ancestor with active person
* {{man label|Filter Person:}} The center person for the report.
* {{man label|Sort chart items by:}} Select how the statistical data is sorted:
** '''Item count''' (default)
** Item name
* {{checkbox|0}} {{man label|Sort in reverse order}} (checkbox unchecked by default)
* {{man label|People born after:}} (<code>1700</code> default) Birth year from which to include people: fill in a year to start from
* {{man label|People born before:}} (<code>Current year</code> default) Birth year until which to include people: fill in a year
* {{checkbox|0}} {{man label|Include people without known birth years}} (checkbox unchecked by default)
* {{man label|Genders included:}} Select which genders are included into statistics.
** '''Both'''(Default)
** Men
** Women
* {{man label|Max. items for a pie:}} (<code>8</code> default) With fewer items pie chart and legend will be used instead of a bar chart.
{{-}}

====Report Options (2)====
[[File:StatisticsCharts-GraphicalReports-ReportOptions2-tab-50.png|right|thumb|450px|Fig. {{#var:chapter}}.{{#vardefineecho:figure|{{#expr:{{#var:figure}}+1}}}} Statistics Charts - Graphical Reports - Report Options (2) - tab default options]]
* {{man label|Name Format:}} Select the format to display the names. Choose from '''Surname, Given Suffix'''(default) / Given Surname Suffix / Given / Main Surnames, Given Patronymic Suffix / SURNAME, Given (Common)
** {{checkbox|1}} {{man label|Include data marked private}} (checkbox checked by default)
* {{man label|Living people}}: Select to include or not living persons in the report. Choose from '''Include, and all data''' (default) / Full names, but data removed / Given names replaced, and data removed / Complete names replaced, and data removed/ Not included
* {{man label|Years from death to consider living}}: Select the number of years since death to consider persons for the report. Allows for the inclusion or exclusion of recently-dead persons in the report. Default value is 0 years.
* {{man label|Translation}}: The translation to be used for the report. Language selector

{{-}}

====Charts 1====

[[File:StatisticsCharts-GraphicalReports-Charts1-tab-50.png|right|thumb|450px|right|Fig. {{#var:chapter}}.{{#vardefineecho:figure|{{#expr:{{#var:figure}}+1}}}} Statistics Charts - Graphical Reports - Charts 1 - tab default options]]

Displays '''Birth Month''' statistics by default and you can include any of the following the indicated data on a chart:
* {{checkbox|0}} {{man label|Age}} (checkbox unchecked by default)
* {{checkbox|0}} {{man label|Age at death}} (checkbox unchecked by default)
* {{checkbox|0}} {{man label|Age at marriage}} (checkbox unchecked by default)
* {{checkbox|0}} {{man label|Age when first child born}} (checkbox unchecked by default)
* {{checkbox|0}} {{man label|Age when last child born}} (checkbox unchecked by default)
* {{checkbox|1}} {{man label|Birth month}} (checkbox checked by default)
{{-}}

====Charts 2====

[[File:StatisticsCharts-GraphicalReports-Charts2-tab-50.png|right|thumb|450px|right|Fig. {{#var:chapter}}.{{#vardefineecho:figure|{{#expr:{{#var:figure}}+1}}}} Statistics Charts - Graphical Reports - Charts 2 - tab default options]]

Displays '''Number of children''' statistics by default and you can include any of the following the indicated data on a chart:
* {{checkbox|0}} {{man label|Birth place}} (checkbox unchecked by default)
* {{checkbox|0}} {{man label|Birth year}} (checkbox unchecked by default)
* {{checkbox|0}} {{man label|Death month}} (checkbox unchecked by default)
* {{checkbox|0}} {{man label|Death place}} (checkbox unchecked by default)
* {{checkbox|0}} {{man label|Death year}} (checkbox unchecked by default)
* {{checkbox|0}} {{man label|Event type}} (checkbox unchecked by default)
{{-}}

====Charts 3====
[[File:StatisticsCharts-GraphicalReports-Charts3-tab-50.png|right|thumb|450px|Fig. {{#var:chapter}}.{{#vardefineecho:figure|{{#expr:{{#var:figure}}+1}}}} Statistics Charts - Graphical Reports - Charts 3 - tab default options]]

Displays '''Gender''' statistics by default and you can include any of the following the indicated data on a chart:
* {{checkbox|0}} {{man label|Forename}} (checkbox unchecked by default)
* {{checkbox|1}} {{man label|Gender}} (checkbox checked by default)
* {{checkbox|0}} {{man label|Marriage place}} (checkbox unchecked by default)
* {{checkbox|1}} {{man label|Number of children}} (checkbox checked by default)
* {{checkbox|0}} {{man label|Number of relationships}} (checkbox unchecked by default)
* {{checkbox|0}} {{man label|Surname}} (checkbox unchecked by default)
* {{checkbox|0}} {{man label|Title}} (checkbox unchecked by default)
{{-}}

===Timeline Chart===

[[File:GraphicalReports-TimelineChart-example-landscape-50.png|right|thumb|450px|Fig. {{#var:chapter}}.{{#vardefineecho:figure|{{#expr:{{#var:figure}}+1}}}} Timeline Chart - Graphical Reports - example output overview]]

This report outputs the list of people with their lifetimes represented by intervals on a common chronological scale.

You can choose the Timeline Chart report with {{man menu|Reports ->Graphical Reports -> Timeline Chart...}}
{{-}}
See also [[Gramps_5.1_Wiki_Manual_-_Reports - part 4#Common options|common options]]
{{-}}
==== Report Options ====

[[File:TimelineChart-GraphicalReports-ReportOptions-tab-50.png|right|thumb|450px|Fig. {{#var:chapter}}.{{#vardefineecho:figure|{{#expr:{{#var:figure}}+1}}}} Timeline Chart - Graphical Reports - Report Options - tab default options]]

* {{man label|Filter:}} choose between
** '''Entire Database''' (Default)
** Descendants of active person
** Descendant families of active person
** Ancestors of active person
** People with common ancestor with active person
* {{man label|Filter Person:}} The center person for the report.
* {{man label|Sort by:}} Sorting method to use.
** '''Birth Date''' (Default)
** Name
{{-}}

====Report Options (2)====
[[File:TimelineChart-GraphicalReports-ReportOptions2-tab-50.png|right|thumb|450px|Fig. {{#var:chapter}}.{{#vardefineecho:figure|{{#expr:{{#var:figure}}+1}}}} Timeline Chart - Graphical Reports - Report Options (2) - tab default options]]
* {{man label|Name Format:}} Select the format to display the names. Choose from '''Surname, Given Suffix'''(default) / Given Surname Suffix / Given / Main Surnames, Given Patronymic Suffix / SURNAME, Given (Common)
** {{checkbox|1}} {{man label|Include data marked private}} (checkbox checked by default)
* {{man label|Living people}}: Select to include or not living persons in the report. Choose from '''Include, and all data''' (default) / Full names, but data removed / Given names replaced, and data removed / Complete names replaced, and data removed/ Not included
* {{man label|Years from death to consider living}}: Select the number of years since death to consider persons for the report. Allows for the inclusion or exclusion of recently-dead persons in the report. Default value is 0 years.
* {{man label|Translation:}} The translation to be used for the report. Language selector

{{-}}

<hr>
Back to [[Gramps_5.1_Wiki_Manual_-_Reports|Index of Reports]].
{{-}}
{{man index|Gramps 5.1 Wiki Manual - Reports - part 3|Gramps_5.1_Wiki_Manual_-_Reports_-_part_5|5.1}}
{{languages|Gramps 5.1 Wiki Manual - Reports - part 4}}
{{grampsmanualcopyright}}

[[Category:Documentation]]
[[Category:Plugins]]