Difference between revisions of "Calendar tools holidays"

From Gramps
Jump to: navigation, search
m (has also been translated to Hebrew https://gramps-project.org/wiki/index.php/Calendar_tools_holidays/he)
 
(33 intermediate revisions by 3 users not shown)
Line 1: Line 1:
Explanation of how to add or change the holidays appearing on the output of the calendars in Gramps. This includes the Text:''Birthday and Anniversary Report'', the Graphical:''Calendar'' Report, and the ''Web Calendar''.
+
{{languages|Calendar tools holidays}}
 +
[[File:Calendar-GraphicalReports-Content-tab-Country for holidays-default-list-51.png|thumb|450px|right|Content tab showing "Country for holidays:" option showing "Country for holidays" default list]]
  
==Calendar Holidays==
+
Details on how to add custom holiday set or change the built-in holiday set appearing on the output of the [[#Calendar-based_reports|Calendar-based reports]] in Gramps.
  
Gramps comes with three Calendar-based reports:
+
==Custom holiday set==
# [[Gramps_{{Version manual}}_Wiki_Manual_-_Reports_-_part_4#Calendar|Calendar Report]]: (menu {{man menu|Reports->Graphical Reports->Calendar...}} )
+
Gramps comes installed with a default <code>holidays.xml</code> file and you can either add more holiday sets to it or  create your own custom <code>holidays.xml</code>
# [[Gramps_{{Version manual}}_Wiki_Manual_-_Reports_-_part_6#Birthday_and_Anniversary_Report|Birthday and Anniversary Report]]: (menu {{man menu|Reports->Text Reports->Birthday and Anniversary Report...}} )
+
 
# And an output for the Web with [[Gramps_{{Version manual}}_Wiki_Manual_-_Reports_-_part_7#Web_Calendar|Web Calendar Report]]:(menu {{man menu|Reports->Web Pages->Web Calendar...}} )
+
===Custom holidays.xml===
 +
You can create a separate custom <code>holidays.xml</code> file in your personal [[Gramps_{{Version manual}}_Wiki_Manual_-_User_Directory|User directory]] <code>.gramps/plugins/</code> folder.
 +
 
 +
====Adding your countries holidays====
 +
Are your countries holidays missing or incomplete and you would like Gramps to have them by default?
  
===Adding your countries holidays===
 
 
If you would like to add your [http://en.wikipedia.org/wiki/Holiday countries holidays] to the calendar, then you can add them to the file <code>holidays.xml.in</code> located:
 
If you would like to add your [http://en.wikipedia.org/wiki/Holiday countries holidays] to the calendar, then you can add them to the file <code>holidays.xml.in</code> located:
* Gramps 4 and older: [https://github.com/gramps-project/gramps/blob/maintenance/gramps42/gramps/plugins/lib/holidays.xml.in gramps/plugins/lib/holidays.xml.in]
+
* Gramps 5 or newer: [https://github.com/gramps-project/gramps/blob/master/data/holidays.xml.in data/holidays.xml.in]
* Gramps 5 or newer: [https://github.com/gramps-project/gramps/blob/master/data/holidays.xml.in data/holidays.xml.in]
 
  
 +
and then raise a feature request and submit your updated file or create a pull request on Github.
 +
 +
====format of holidays.xml====
 
In the file <code>holidays.xml.in</code>, you can add recurring annual events in a variety of ways. The format is generally:
 
In the file <code>holidays.xml.in</code>, you can add recurring annual events in a variety of ways. The format is generally:
  
Line 30: Line 36:
 
</pre>
 
</pre>
 
   
 
   
where each of the capitalized words would be filled in with appropriate values, as shown in [https://github.com/gramps-project/gramps/blob/master/gramps/plugins/lib/libholiday.py /gramps/plugins/lib/libholiday.py]. All but NAME and VALUE are optional.
+
where each of the capitalized words would be filled in with appropriate values, as shown in list of keywords.
 +
 
 +
====Keywords====
 +
The following is a list of keywords to be used when creating or expanding the holidays.xml file see:
 +
* [https://github.com/gramps-project/gramps/blob/master/gramps/plugins/lib/libholiday.py /gramps/plugins/lib/libholiday.py].
 +
 
 +
All but NAME and VALUE are optional.
  
 
*'''COUNTRYNAME''' => "United States", "China", etc. You don't have to make these countries, however. You can make these just a "holiday set" which could be "Christian", "Muslim", "Eastern European", etc. These names can be selected from the {{man label|Country for holidays:}} list option when running calendar-related reports. You can use your own language for this name.
 
*'''COUNTRYNAME''' => "United States", "China", etc. You don't have to make these countries, however. You can make these just a "holiday set" which could be "Christian", "Muslim", "Eastern European", etc. These names can be selected from the {{man label|Country for holidays:}} list option when running calendar-related reports. You can use your own language for this name.
Line 66: Line 78:
 
** "workday" or "weekend" (may be negative) - the next workday/weekend that is on this day, or the next/prev
 
** "workday" or "weekend" (may be negative) - the next workday/weekend that is on this day, or the next/prev
  
== Translations ==
+
===Translations===
  
 
Holiday entries are generally written for a specific country, and thus typically don't need to be written for more than one language. However, it might be appropriate to have your entries country name and holiday text be translated into the language that Gramps is running in. To make a country name or holiday name get translated, simply precede the name of the XML item with an underscore. For example:
 
Holiday entries are generally written for a specific country, and thus typically don't need to be written for more than one language. However, it might be appropriate to have your entries country name and holiday text be translated into the language that Gramps is running in. To make a country name or holiday name get translated, simply precede the name of the XML item with an underscore. For example:
Line 82: Line 94:
 
In this example, "Jewish Holidays", "Purim", and "Passover" will be looked up in the Gramps gettext system for translations. If you would like to help add those translations, please see [[Translating Gramps]].
 
In this example, "Jewish Holidays", "Purim", and "Passover" will be looked up in the Gramps gettext system for translations. If you would like to help add those translations, please see [[Translating Gramps]].
  
==Examples==
+
===Example===
 +
 
 +
The last set ( <country name="Finland">  ) will only load if your country is Finland. It says that Card Night is the last Thursday of every month, every year. Let's play!
 +
 
 +
Filename: holidays.xml
  
 
<pre>
 
<pre>
Line 114: Line 130:
 
</pre>
 
</pre>
  
The last set will only load if your country is Finland. It says that Card Night is the last Thursday of every month, every year. Let's play!
+
==Calendar-based reports==
 +
[[File:Calendar-GraphicalReports-Content-tab-50.png|thumb|450px|right|Content tab showing "Country for holidays:" option]]
 +
 
 +
Gramps comes with the following Calendar-based reports:
 +
* [[Gramps_{{Version manual}}_Wiki_Manual_-_Reports_-_part_4#Calendar|Calendar Report]]: (menu {{man menu|Reports->Graphical Reports->Calendar...}} )
 +
* [[Gramps_{{Version manual}}_Wiki_Manual_-_Reports_-_part_6#Birthday_and_Anniversary_Report|Birthday and Anniversary Report]]: (menu {{man menu|Reports->Text Reports->Birthday and Anniversary Report...}} )
 +
* And an output for the Web with [[Gramps_{{Version manual}}_Wiki_Manual_-_Reports_-_part_7#Web_Calendar|Web Calendar Report]]:(menu {{man menu|Reports->Web Pages->Web Calendar...}} )
 +
 
 +
{{-}}
 +
You can select which holidays to show by setting the {{man label|Country for holidays:}} option in either the {{man label|Content}} tab of the reports.
 +
 
 +
[[File:Calendar-GraphicalReports-Content-tab-Country for holidays-default-list-51.png|thumb|450px|right|Content tab showing "Country for holidays:" option showing "Country for holidays" default list]]
 +
{{-}}
  
==Separate holidays.xml==
+
===Available Calendars===
Note that you can have two separate <code>holidays.xml</code> files:
 
# Where Gramps is installed,
 
# The other in your personal [[Gramps_{{Version manual}}_Wiki_Manual_-_User_Directory|User directory]] <code>.gramps/plugins/</code> folder.
 
  
==Available Calendars==
 
===Gramps 4.2===
 
 
Countries:
 
Countries:
*  Bulgaria / Canada / Chile / China / Croatia / Czech Republic / England / Finland / France / Germany / Japan / New Zealand / Sweden / Ukraine / United States of America
+
*  Bulgaria / Canada / Chile / China / Croatia / Czech Republic / England / Finland / France / Germany / Japan / New Zealand / Russia / Serbia / Serbia (Latin) / Slovakia / Sweden / Ukraine / United States of America
 
Holidays
 
Holidays
 
* Jewish Holidays
 
* Jewish Holidays

Latest revision as of 09:07, 17 September 2023

Content tab showing "Country for holidays:" option showing "Country for holidays" default list

Details on how to add custom holiday set or change the built-in holiday set appearing on the output of the Calendar-based reports in Gramps.

Custom holiday set

Gramps comes installed with a default holidays.xml file and you can either add more holiday sets to it or create your own custom holidays.xml

Custom holidays.xml

You can create a separate custom holidays.xml file in your personal User directory .gramps/plugins/ folder.

Adding your countries holidays

Are your countries holidays missing or incomplete and you would like Gramps to have them by default?

If you would like to add your countries holidays to the calendar, then you can add them to the file holidays.xml.in located:

and then raise a feature request and submit your updated file or create a pull request on Github.

format of holidays.xml

In the file holidays.xml.in, you can add recurring annual events in a variety of ways. The format is generally:

 <?xml version="1.0" encoding="UTF-8"?>
 <calendar>
   <country _name=COUNTRYNAME>
     <date name=NAME value=VALUE type=TYPE offset=OFFSET if=EXPRESSION />
     ...
   </country>
   <country _name=COUNTRYNAME>
     <date name=NAME value=VALUE type=TYPE offset=OFFSET if=EXPRESSION />
     ...
   </country>
   ...
 </calendar>

where each of the capitalized words would be filled in with appropriate values, as shown in list of keywords.

Keywords

The following is a list of keywords to be used when creating or expanding the holidays.xml file see:

All but NAME and VALUE are optional.

  • COUNTRYNAME => "United States", "China", etc. You don't have to make these countries, however. You can make these just a "holiday set" which could be "Christian", "Muslim", "Eastern European", etc. These names can be selected from the Country for holidays: list option when running calendar-related reports. You can use your own language for this name.
  • NAME => the text to appear on the calendar
  • TYPE => "secular", "religious", "personal", "informational" (This isn't currently used in the calendar, but could be. Use these keywords, untranslated.)
  • EXPRESSION => a python expression that must be true for this to appear on the calendar. You can use y, m, and d variables (for year, month, and day, all integers). See VALUE for examples.
  • VALUE =>
    • "YEAR/MONTH/DAY"
      • "2012/12/25"
      • "*/12/25"
    • "YEAR/MONCODE/DAY"
      • "2012/dec/25"
      • "*/dec/25"
    • "YEAR/NUMBER/DAYCODE/MONCODE" (nth day of week in month, year)
      • "2012/1/mon/dec" (first monday in december, 2012)
      • "*/-1/tue/dec" (last tuesday in december, every year)
    • "> EXPRESSION" (which evaluates to one of the previous two types of VALUES). Current useful expression values are:
      • "> easter(y)" (Easter for current year)
      • "> dst(y)[0]" (Daylight Saving Time, "us", start)
      • "> dst(y)[1]" (Daylight Saving Time, "us", end)
      • "> dst(y, "eu")[0]" (Daylight Saving Time, "eu", start)
      • "> dst(y, "eu")[1]" (Daylight Saving Time, "eu", end)
      • "> dow(y, m, d) == 1" (dow returns the iso weekday number, where Monday is 1 and Sunday is 7)
  • YEAR => "*" or an actual year. "*" means any year.
  • MONTH => "*" or actual month number. "*" means any month.
  • DAY => "*" or actual day number in month. "*" means any day.
  • NUMBER => number of weekday in month. For example, "every 3rd Tuesday in April" would be "*/3/tue/apr". NUMBER can also be negative, which means it is counted from the end of the month. "last Tuesday in April 2007" could be "2007/-1/tue/4"
  • DAYCODE => "mon", "tue", "wed", "thu", "fri", "sat", or "sun". Do not translate these words; use all lowercase.
  • MONCODE =>
    • MONTH
    • 'jan', 'feb', 'mar', 'apr', 'may', 'jun', 'jul', 'aug', 'sep', 'oct', 'nov', or 'dec'. (not be translated; use all lowercase)
  • OFFSET =>
    • number (may be negative) that offsets the day determined by VALUE
    • DAYCODE (may be negative), the next DAYCODE that is either the same as this day, or the next(+)/prev(-) one.
    • "workday" or "weekend" (may be negative) - the next workday/weekend that is on this day, or the next/prev

Translations

Holiday entries are generally written for a specific country, and thus typically don't need to be written for more than one language. However, it might be appropriate to have your entries country name and holiday text be translated into the language that Gramps is running in. To make a country name or holiday name get translated, simply precede the name of the XML item with an underscore. For example:

  ...
  <country _name="Jewish Holidays">
    <date _name="Purim" value="> passover(y)" offset="-30"/>
    <date _name="Passover" value="> passover(y)" offset="0"/>
    ...
  </country>
  ...

In this example, "Jewish Holidays", "Purim", and "Passover" will be looked up in the Gramps gettext system for translations. If you would like to help add those translations, please see Translating Gramps.

Example

The last set ( <country name="Finland"> ) will only load if your country is Finland. It says that Card Night is the last Thursday of every month, every year. Let's play!

Filename: holidays.xml

 <?xml version="1.0" encoding="UTF-8"?>
 <calendar>
   <country name="United States">
     <date name="Daylight Saving Time begins" value="> dst(y)[0]" type="informational" />
     <date name="Daylight Saving Time ends" value="> dst(y)[1]" type="informational" />
     <date name="New Year's Day" value="*/1/1" type="national" />
     <date name="Labor Day" value="*/1/mon/sep" type="national" />
     <date name="Thanksgiving" value="*/4/thu/nov" type="national" />
     <date name="Inauguration Day" value="*/1/20" if="(y - 1980) % 4 == 0"  type="national" />
     <date name="Washington's Birthday" value="*/3/mon/feb" type="secular" />
     <date name="St. Patrick's Day" value="*/3/17" type="secular" />
     <date name="Assistants' Day" value="*/-1/sat/apr" offset="-3" type="secular" />
     <date name="Arbor Day" value="*/-1/fri/apr" type="secular" />
     <date name="Mothers' Day" value="*/2/sun/may" type="secular" />
     <date name="Fathers' Day" value="*/3/sun/jun" type="secular" />
     <date name="ML Kings's Birthday" value="*/3/mon/jan"  type="secular" />
     <date name="Memorial Day" value="*/-1/mon/may" type="secular" />
     <date name="Easter" value="> easter(y)" type="religious" />
     <date name="Ash Wednesday" value="> easter(y)" offset="-46" type="religious" />
    </country>
   <country name="China">
     <date name="Chinese New Year" value="2006/1/29" type="national" />
   </country>
   <country name="Finland">
     <date name="Card Night" value="*/-1/thu/*" type="personal" />
   </country>
 </calendar>

Calendar-based reports

Content tab showing "Country for holidays:" option

Gramps comes with the following Calendar-based reports:


You can select which holidays to show by setting the Country for holidays: option in either the Content tab of the reports.

Content tab showing "Country for holidays:" option showing "Country for holidays" default list


Available Calendars

Countries:

  • Bulgaria / Canada / Chile / China / Croatia / Czech Republic / England / Finland / France / Germany / Japan / New Zealand / Russia / Serbia / Serbia (Latin) / Slovakia / Sweden / Ukraine / United States of America

Holidays

  • Jewish Holidays

See also