Difference between revisions of "Customize reports with XML tool"

From Gramps
Jump to: navigation, search
(Initial commit of How To for managing xml)
 
m (Move Category tag to bottom)
 
(3 intermediate revisions by 2 users not shown)
Line 1: Line 1:
{{Languages}}
 
{{man warn|1=&#x1F6A7; Work In Progress|2=This wikipage is an outline from a template being roughed in. Please don't edit '''''just yet'''''. Instead, contribute suggestions on the Discussion page. <br /><br />This page is not planned be linked to a public page until about 2 weeks after 26 March 2021. <br /><br />If this notice remains after that date, please feel welcome to remove this notice and consider the content 'fair game' for unlimited editing.}}
 
== See also ==
 
*Feature documentation:[[Start_with_Genealogy|Start with Genealogy]]
 
 
*[[Gramps_Glossary#active_person|Active Person]] Gramps Glossary definition
 
 
*based on the [https://sourceforge.net/p/gramps/mailman/gramps-users/ Gramps-users] archived threads:
 
:[https://sourceforge.net/p/gramps/mailman/message/36617953/ The Group As name override]
 
:[https://sourceforge.net/p/gramps/mailman/search/?q=%22unify+similar+surmanes+%3F%3F%22&mail_list=all unify similar surmanes &#91;sic&#93; thread]
 
:[https://sourceforge.net/p/gramps/mailman/search/?q=%22Group+As+name%22 threads with "Group As name"]
 
 
 
{{DEFAULTSORT:How do I...new category location|noreplace}}
 
[[Category:Tutorial]]
 
[[Category:WikiContributors]]
 
[[Category:How do I...]]
 
 
 
<div style="background:lightcyan">
 
 
 
Paste the raw '''[[:Category:Tutorials|Tutorials]]''' outline for the '''[[:Category:How_do_I...|How Do I...]]''' article above the '''See also''' section. This might start with pasting in a copy of a useful thread from one of the Gramps maillists.
 
 
 
Saving this file as a 'work in progress' will insert the code behind this reference template. (Preview only show the results, not the markup formatting control.) You can use the appended special formatting example template to pre-populate a virtual Copy&amp;Paste clipboard.  Snip pieces to paste special formatting to enhance the outline.
 
  
 
----
 
----
 +
{{Languages|Customize_reports_with_XML_tool}}
 +
{{man warn|1=&#x1F6A7; Work In Progress|2=This wikipage is an outline from a template being roughed in. Please don't edit '''''just yet'''''. Instead, contribute suggestions on the Discussion page. <br /><br />This page is not planned be linked to a public page until about 2 weeks after 26 March 2021. <br /><br />If this notice remains after that date, please feel welcome to remove this notice and consider the content 'fair game' for unlimited editing.}}
 +
Families often have complicated structures, especially for Twenty-first century blended families. Generating reports that include the various relatives will yield a more complete picture of the family.
  
Adding a ''feature documentation'' link pointing to the introduction of the interface element in the wiki will relieve you of the burden explaining how to find the feature.
+
This article offers a less manual method to configure a Report's options as an alternative to the Gramps report interface.  
 +
== Family Lines Graph ==
  
Finding a ''[[Gramps_Glossary|Gramps Glossary]] term'' to link may be easier than choosing the best introductory section in the wiki.
+
Creating a [[Gramps_{{man version}}_Wiki_Manual_-_Reports_-_part_5#Family_Lines_Graph|Family Lines Graph]] often involves carefully selecting multiple people to include, this is a slow process that recursively loads the Select Person dialog.  
  <small>&#91;&#91;Gramps_Glossary#active_person|Active Person]]
 
  &#91;&#91;Gramps_Glossary#P|Primary Object]]</small>
 
Glossary terms (like [[Gramps_Glossary#active_person|Active Person]] above) are normally lowercase and use an underscore between words. They have a brief description and may already have the introductory text and practical tutorial linked. You can fall back to the Letter index (like using '[[Gramps_Glossary#P|P]]' with [[Gramps_Glossary#P|Primary Object]] above) if you don't know the exact entry.
 
  
Since most of these ''How do I...'' tutorials are likely to have been prompted by a MailList discussion, a set of example 'See also' link are included for reference.
+
Gramps stores these selections in a file named <code>report_options.xml</code> in the <code>~/.gramps</code> [[Gramps_{{man version}}_Wiki_Manual_-_User_Directory|User directory]]. The report options are '''overwritten''' every time a graphical report is created.  
 
 
Pointing the ''maillist archived thread'' link to the original message that inspired the tutorial give proper credit for the idea &amp; reveals the background discussion.
 
 
 
Pointing another link to a good search phrase for the archive allows similar discussions to be explored.
 
 
 
----
 
 
 
Once the tutorial Preview is satisfactory, save a revision of the document. Then clean out the virtual Copy&amp;Paste clipboard cluttering up your tutorial and save a final revision.
 
 
 
 
 
To remove the virtual Copy&amp;Paste clipboard, simply delete everything from the beginning of this section to the bottom of the document. It is all disposable.
 
  
If the Copy&amp;Paste clipboard is needed again, simply paste the following line at the end of the Edit box, Save a revision, &amp; edit again.(Previewing isn't enough... a revision must be saved.)
+
It is possible to edit this file manually with a text editor, but that is a tedious and error-prone procedure.  
<pre>  {{subst:Template:How_do_I}}</pre>
 
Other wiki [[:Category:Templates|Templates]] can be used as virtual Copy&amp;Paste clipboards in the same way.
 
  
 +
==Create a Bash script==
 +
The following [https://wikipedia.org/wiki/Bash_(Unix_shell) bash] script will take care of the process for Linux users. It includes backing up the current file and saving the list of Person IDs in a file that can be reused.
  
</div>
 
[[Write_a_%22How_Do_I...%22_Article|Writing a 'How do I...' article.]]
 
 
<pre>
 
<pre>
{{subst:Gramps_{{man version}}_Wiki_Manual_-_Preface}}
 
{{subst:WikiContributorRecruiting}
 
</pre>
 
----
 
  
== (Section) ==
+
#!/bin/bash
Stub, english (''default'')
+
if [ $# -lt 1 ];then
{{Stub}}
+
    echo "Utility to replace list of People of Interest in Gramps Family Lines Graph."
 +
    echo "The file 'report_options.xml' is overwritten after making a backup."
 +
    echo "The current list of People of Interest is saved for possible reuse"
 +
    echo "Usage: "$0" current_pid [new_pid]"
 +
    echo "  current_pid is the file name in which to save current pid list"
 +
    echo "  Optional. If present, new_pid is the name of the file containing"
 +
    echo "  the new pid list"
 +
    echo "  eg " $0" bigfamily.pid three_gen.pid"
 +
    exit 1
 +
fi
  
{{Stub|fr}}
+
gramps_home=~/.gramps/
Stub, french
+
#echo "gramps_home = "$gramps_home
 +
opts=$gramps_home"report_options.xml"
 +
#echo "opts = "$opts
 +
bak=$opts".bak"
 +
#echo "bak = "$bak
  
=== Embeddable Snippets (Subsection) ===
+
echo "Backing up "$opts " to " $bak
Icons
+
cp -irp $opts $bak
: {{icon|gram}} Dashboard
 
: {{icon|peop}} People
 
: {{icon|rela}} Relationships
 
: {{icon|fami}} Family Families
 
: {{icon|ance}} Charts
 
: {{icon|even}} Events
 
: {{icon|plac}} Places
 
: {{icon|geog}} Geography
 
: {{icon|sour34}} Sources
 
: {{icon|cite}} Citations
 
: {{icon|repo}} Repositories
 
: {{icon|medi}} Media
 
: {{icon|note}} Notes
 
:[[Template:Icon/doc|more of the standard icons]]
 
  
<small>
+
echo "Saving current pid list to "$gramps_home$1
{|
+
lxprintf -e 'module[@name="familylines_graph"]/option[@name="gidlist"]'\
|+ List object tools
+
"%s\n" @value $opts > $gramps_home$1
|-
 
! style="width: 70px"|
 
! style="width: 70px"|
 
! style="width: 70px"|
 
! style="width: 70px"|
 
! style="width: 70px"|
 
! style="width: 70px"|
 
|-
 
!{{icon|stock_add}}
 
!{{icon|share}}
 
!{{icon|stock_edit}}
 
!{{icon|stock_remove}}
 
!{{icon|up}}
 
!{{icon|down}}
 
|-
 
! Add
 
! Share
 
! Edit
 
! Remove
 
! <small>Move<br /></small>Upwards
 
! Move<br />Downwards
 
|}
 
</small>
 
  
==== [[Help:Formatting|Text formatting]] (Level 2 Subsection) ====
+
echo "Replacing pids in "$opts
''italic'', '''bold''', '''''bold & italic'''''
+
echo "    with the contents of "$gramps_home$2
===== [[Help:Images|Images]] (Level 3 Subsection) =====
 
[[File:ChartsCategory-desendantfan-fullcircle-9gen-default-50.png|thumb|right|450px|Fig. {{#var:chapter}}.{{#vardefineecho:figure|{{#expr:{{#var:figure}}+1}}}} A screenshot caption]]
 
[[Image:Gramps-logo.png|Logo]]
 
  
*[[Screenshots|Screenshots]]
+
# replacing the xml in situ does not seem to work correctly
*[[Special:PrefixIndex|Templates]]
+
# instead send it to a temporary file and copy
====== Annotations of User Activities  (Level 4 Subsection) ======
+
lxreplace -q \
 +
  'module[@name="familylines_graph"]/option[@name="gidlist"]' \
 +
  -@ '"value"' "&apos;`cat $gramps_home$2`&apos;" \
 +
  ~/.gramps/report_options.xml > /tmp/temp.xml
  
*<pre>Commands you type at the command line</pre>
+
cp -fv /tmp/temp.xml $opts 2>>/dev/null
 +
echo "Updated "$opts
  
*''Filenames'' or <code>Filenames</code>
+
</pre>
 +
==Using the script==
 +
Copy the this code into a file, or get the most [https://github.com/johnrsibert/Grampsish/blob/main/fix_fl_people.sh recent version] of the script from [https://github.com/ github], and save it to a directory on your [http://www.linfo.org/path_env_var.html PATH].
  
*<tt>''Replaceable text''</tt>
+
You will also need the [https://www.ltg.ed.ac.uk/software/ltxml2/ LTXML2 Toolkit] from the Language Technology Group at Edinburgh University.
  
*{{man label|Labels}} for buttons and other portions of the graphical interface
+
==See also==
 
+
* 18 Mar 2021 [https://sourceforge.net/p/gramps/mailman/gramps-users/thread/3fdb89de-f1c0-ead9-5080-c02706f4ffe9%40silmaril.ie/#msg37243313 Family Lines Graph] message thread in the [https://sourceforge.net/p/gramps/mailman/gramps-users/ Gramps-users maillist archive]
*{{man tooltip|hint text}} for roll-over tooltip hints that identify elements of the graphical interface
+
[[Category:How do I...]]
 
 
*Menu selections look like this: {{Man menu|Menu &#x27a1; Submenu &#x25B6; Menu Item}} (always pad unicode symbols like these arrows with spaces so that robot translators see recognizable words)
 
* Pop-up menu down {{man button|&#x25BC;}} arrowhead, (triangle) button
 
 
 
*{{man button|Buttons}}  you can click
 
 
 
*{{Man key press|CTRL|D}} see [[Gramps_{{man version}}_Wiki_Manual_-_Keybindings|Keybindings]] for a list of keyboard combinations used in Gramps.
 
 
 
*<tt>Anything you type in</tt>
 
 
 
*{{checkbox|1|Checked}} - [[Template:Checkbox|Selected Checkbox]] &#x2611; template
 
*{{checkbox|0|Unchecked}} - Checkbox that is &#x274f; unselected
 
 
 
== Boxed annotations ==
 
{{man tip| 1=Title of Tip |2=Tips text.}}
 
{{man note|Example Note |Notes text.}}
 
{{man warn|1=WarningTitle/Heading |2=warning text }}</onlyinclude>
 
 
 
[[User:JohnRSibert|JohnRSibert]] ([[User talk:JohnRSibert|talk]]) 15:52, 26 March 2021 (UTC)
 
 
 
Families often have complicated structure, especially for Twenty-first century blended families. Creating a [[Gramps_{{man version}}_Wiki_Manual_-_Reports_-_part_5#Family_Lines_Graph|Family Lines Graph]] for such families often involves carefully selecting multiple people to include.
 
 
 
Gramps stores these selections in a file named <code>report_options.xml</code> in the <code>~/.gramps</code> [[Gramps_{{man version}}_Wiki_Manual_-_User_Directory|User directory]]. The report options are '''overwritten''' every time a graphical report is created.
 
 
 
It is possible to edit this file manually with a text editor, but that is a tedious and error-prone procedure. The following [https://wikipedia.org/wiki/Bash_(Unix_shell) bash] script will take care of the process for you backing up the current file and saving the list of person IDs in a file that can be reused.
 
 
 
 
 
#!/bin/bash
 
if [ $# -lt 1 ];then
 
    echo "Utility to replace list of People of Interest in Gramps Family Lines Graph."
 
    echo "The file 'report_options.xml' is overwritten after making a backup."
 
    echo "The current list of People of Interest is saved for possible reuse"
 
    echo "Usage: "$0" current_pid [new_pid]"
 
    echo "  current_pid is the file name in which to save current pid list"
 
    echo "  Optional. If present, new_pid is the name of the file containing"
 
    echo "  the new pid list"
 
    echo "  eg " $0" bigfamily.pid three_gen.pid"
 
    exit 1
 
fi
 
 
gramps_home=~/.gramps/
 
#echo "gramps_home = "$gramps_home
 
opts=$gramps_home"report_options.xml"
 
#echo "opts = "$opts
 
bak=$opts".bak"
 
#echo "bak = "$bak
 
 
echo "Backing up "$opts " to " $bak
 
cp -irp $opts $bak
 
 
echo "Saving current pid list to "$gramps_home$1
 
lxprintf -e 'module[@name="familylines_graph"]/option[@name="gidlist"]'\
 
  "%s\n" @value $opts > $gramps_home$1
 
 
echo "Replacing pids in "$opts
 
echo "    with the contents of "$gramps_home$2
 
 
# replacing the xml in situ does not seem to work correctly
 
# instead send it to a temporary file and copy
 
lxreplace -q \
 
  'module[@name="familylines_graph"]/option[@name="gidlist"]' \
 
  -@ '"value"' "&apos;`cat $gramps_home$2`&apos;" \
 
  ~/.gramps/report_options.xml > /tmp/temp.xml
 
 
cp -fv /tmp/temp.xml $opts 2>>/dev/null
 
echo "Updated "$opts
 
 
 
Copy the this code into a file, or get the most recent version of the script from
 
[https://github.com/johnrsibert/Grampsish/blob/main/fix_fl_people.sh github], and save it to a directory on your [http://www.linfo.org/path_env_var.html PATH].
 

Latest revision as of 14:49, 28 March 2021


Gnome-important.png
🚧 Work In Progress

This wikipage is an outline from a template being roughed in. Please don't edit just yet. Instead, contribute suggestions on the Discussion page.

This page is not planned be linked to a public page until about 2 weeks after 26 March 2021.

If this notice remains after that date, please feel welcome to remove this notice and consider the content 'fair game' for unlimited editing.

Families often have complicated structures, especially for Twenty-first century blended families. Generating reports that include the various relatives will yield a more complete picture of the family.

This article offers a less manual method to configure a Report's options as an alternative to the Gramps report interface.

Family Lines Graph

Creating a Family Lines Graph often involves carefully selecting multiple people to include, this is a slow process that recursively loads the Select Person dialog.

Gramps stores these selections in a file named report_options.xml in the ~/.gramps User directory. The report options are overwritten every time a graphical report is created.

It is possible to edit this file manually with a text editor, but that is a tedious and error-prone procedure.

Create a Bash script

The following bash script will take care of the process for Linux users. It includes backing up the current file and saving the list of Person IDs in a file that can be reused.


#!/bin/bash
if [ $# -lt 1 ];then
    echo "Utility to replace list of People of Interest in Gramps Family Lines Graph."
    echo "The file 'report_options.xml' is overwritten after making a backup."
    echo "The current list of People of Interest is saved for possible reuse" 
    echo "Usage: "$0" current_pid [new_pid]"
    echo "   current_pid is the file name in which to save current pid list"
    echo "   Optional. If present, new_pid is the name of the file containing"
    echo "   the new pid list"
    echo "   eg " $0" bigfamily.pid three_gen.pid"
    exit 1
fi 

gramps_home=~/.gramps/
#echo "gramps_home = "$gramps_home
opts=$gramps_home"report_options.xml"
#echo "opts = "$opts
bak=$opts".bak"
#echo "bak = "$bak

echo "Backing up "$opts " to " $bak 
cp -irp $opts $bak

echo "Saving current pid list to "$gramps_home$1
lxprintf -e 'module[@name="familylines_graph"]/option[@name="gidlist"]'\
 "%s\n" @value $opts > $gramps_home$1

echo "Replacing pids in "$opts
echo "    with the contents of "$gramps_home$2

# replacing the xml in situ does not seem to work correctly
# instead send it to a temporary file and copy
lxreplace -q \
  'module[@name="familylines_graph"]/option[@name="gidlist"]' \
  -@ '"value"' "'`cat $gramps_home$2`'" \
  ~/.gramps/report_options.xml > /tmp/temp.xml

cp -fv /tmp/temp.xml $opts 2>>/dev/null
echo "Updated "$opts

Using the script

Copy the this code into a file, or get the most recent version of the script from github, and save it to a directory on your PATH.

You will also need the LTXML2 Toolkit from the Language Technology Group at Edinburgh University.

See also