KDE PIM/KHolidays

Introduction

The KHolidays library in kdepimlibs provides details on public holidays for a given country and date range. A separate library and file format is required as iCalendar is not capable of expressing recurrence rules for all possible holidays.

Maintainers

• John Layt (IRC jlayt)
• Allen Winter

Resources

• API: Browse api.kde.org
• Code: Browse projects.kde.org
• Code: Browse quickgit.kde.org
• Bugs: Bugzilla Search

Features

The following features are available in KHolidays that are not supported in iCalendar:

• Alternative calendar systems (Hebrew, Islamic, etc)
• Special date calculations, currently Easter and Orthodox Easter, but can include events like solstices, or any named day of the year.
• Commemoration date, i.e. Christmas occurs on a Sunday, you get the Monday off.
• Holiday Class, i.e.day-of,not day off, religious day off, school holiday, etc
• Holiday Categories, i.e. Cutural, Official, Religious, etc.

File Format

The file format originally used was the PLAN format, but this has been extended a number of times to support new features. The limits of the format have about been reached and it is too complex for easy maintenance. It is intended to add a few more features to the format then to design a new XML file format to replace it.

• Historic document: http://community.kde.org/KDE_PIM/KOrganizer/Holiday_File_Format

Future Plans

• Old design document
• http://websvn.kde.org/trunk/playground/pim/libkholidays_ng/

The following development plan is designed to become a Freedesktop.org project so that the maintenance burden can be shared with Gnome and any other interested parties.

• Design a new XML based file format
• Convert KDE files to new format
• Implement a base C (?) library to parse the XML file and calculate the holidays, will include calendar systems if not in glibc by then. No desktop specific code allowed, i.e. to be equivalent to libical.
• Implement a pure Qt library to wrap the C library in kdesupport
• Implement an Akonadi resource

A proposal was presented at the Berlin Desktop Summit in August 2011. The slides from the talk go into more detail.

Rough Notes From KHolidays 2 Plan

KHolidays

• KHolidays: Holiday types, day-off types.
• Split the existing holiday files up into civil and religious files and create a better naming scheme including country, language, region and type.
• Finalise the required file metadata fields (name, region, language, etc).
• Add holiday class/category syntax (e.g. Public / Religious / Cultural / Financial Holiday etc). Holidays can have multiple classes/categories, implement as flags.
• Improve the SHIFT syntax to cater for more complex rules (e.g. the Boxing Day problem). Add optional name for day shifted to.
• Add a NOOP or EXCLUDE syntax to allow holidays to only occur in some years and not others.
• Solstice/Equinox keywords and functions (like Easter).
• If holiday has a duration > 1 day return only one Holiday instance with a duration and/or end date attribute set, rather than multiple Holiday instances. This will allow the client app to choose whether to display as a singled spanned entry or multiple entries, and may make de-duping easier.
• Return attributes of both original date of holiday and shifted to observation date, and if original date is still a holiday or not. Option to have different names shown for each date.
• Try sort out translation of the file names, the desktop file might be the way to go.
• Hebrew special event calculations
• So would that mean HolidayRegion::locations() (or the equivalent) could be passed an argument that means it will only return those locations that have holiday files of a particular type (e.g. civil)?
• Any plans to add a way of selecting holiday calendars to the KDE Control Module (Country/Region & Language)?
• I think we would have to have 2 sets, a top-level or global faith/language set, then a region/faith/language set for local variations (where faith means a religion or any sub-set within that religion). For the top-level the filename itself would just use a region code of xx which is the ISO code for supra-national groups. So something like holiday_xx_es_catholic with a metadata display name of "Catholic (Spanish)" and holiday_ar_es_catholic with "Argentine Catholic (Spanish)".
• The design actually has a nice directory based hierarchy for this, I'll have a think if we want to do that yet.
• allow them to choose to display multiple holiday files at the same time to know which is their 'official' holiday file for days-off to show in red, and if they select a second civil region to display those days-off won't be marked in red but in blue for information only. But that might be a per-file setting, someone might want both sets of days off!
• Some control over what colours are used will be needed too.

<holiday predefined=christmas region=GB type=public,religious>
  <observance move-type=both-days days-off=both-days language=en_GB>Christmas Day Bank Holiday</observance>
</holiday>

<holiday region=NZ_WN type=public>
  <name language=en_NZ>Wellington Anniversary Day</name>
  <observance calendar=gregorian month=01 day=22 started=1853 />
</holiday>

Old design:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE holidayCalendar >

<!-- US Federal Holidays -->


<!-- Federal Holidays in The United States -->
<holidayCalendar name="Federal" type="political">

  
<-- New Year's Day -->
  <holiday type="public" workDayOff="true" schoolDayOff="true">
    <name>New Year's Day</name>
    <datespec>
      <posdate position="fourth" dayOfWeek="thursday" month="11">
        <plus days="1"/>
      </posdate>
    </datespec>
    <description>Start of year, marks traditional end of holiday season</description>
  </holiday>

</holidayCalendar>

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE features >

<!-- Maryland State Holidays

     Includes all the federal holidays plus
       Election Day (even years only)
       Day After Thanksgiving
-->

<!-- Holidays for the state of Maryland in The United States -->
<holidayCalendar name="Maryland" type="political">
  <include>UnitedStates/Federal.xml</include>

  <holiday type="public" workDayOff="true" schoolDayOff="true">
    <name>Day After Thanksgiving</name>
    <datespec>
      <posdate position="fourth" dayOfWeek="thursday" month="11">
        <plus days="1"/>
      </posdate>
    </datespec>
    <description>The day after Thanksgiving</description>
  </holiday>

  <holiday type="public" workDayOff="true" schoolDayOff="true">
    <name>Election Day</name>
    <datespec>
      <posdate position="first" dayOfWeek="tuesday" month="11">
        <yearMod>2</yearMod>  <!-- every even year -->
      </posdate>
    </datespec>
    <description>Election Day</description>
  </holiday>

</holidayCalendar>