KDE PIM/KHolidays/File Format

The KHolidays file format is based on the Plan file format, but has been heavily modified to cater for alternative calendar systems and proper category support. This page documents the basics of this format and the other conventions used in standardising the content of the files. You can use this page to create a new file or to maintain an existing page.

Conventions

• Always use the standard template given below
• Always complete the file metadata
• Always put Public Holidays in the separate section at the top regardless of their other categories (i.e. even if Religious)
• Always include the English name of the holiday in a comment so the maintainers can understand it
• Always write dates using month name to remove any ambiguity
• Never remove old holidays or change the rule of an existing holiday to only have a new future calculation, as you still need the old holiday rule when calculating holidays for earlier years. Instead modify the year range the old and new calculations apply to. See Advanced Calculations below.

Holiday Region Files

A single holiday file defines all the holidays for an administrative region translated into a language and optionally separated into categories. This is known in KHolidays as a Holiday Region and each file/region is listed separately in the user interface where they can be enabled and disabled separately. This provides a convenient and easy way for organising large groups of holidays.

File Naming

The file name is of the format holiday_$region_$language[_$variant], for example "holiday_es_es" for general holidays in Spain in Spanish or "holiday_es_es_catholic" for Catholic holidays in Spain in Spanish.

• The filename is always lowercase
• The filename, being unique, is used as the ID for the Holiday Region in KHolidays
• The metadata tags in the filename are separated by an underscore "_"
• Where the metadata tags require subtags these are separated by a dash "-"
• The metadata tags in the filename are used as a fallback if the internal file metadata tags are not populated, otherwise the naming standard is purely for organisational convenience.
• The region code is the ISO 3166 Alpha2 code for the administrative region that the holidays in the file apply to and is compulsory. This is usually the country level code such as "es" (Spain) or "us" (USA), but can be a level 2 region code for a state or province such as "es-ca" (Catalonia). Where the file applies at a global level, such as "Catholic Saint's Days", then the region code is "xx"
• The language code is the KDE translation code for the language that the file is in, usually the ISO 639 Language code such as "es" (Spanish) or the locale variant of the language such as "en-gb" (British English), or even with the script variant included "sr@latin" (Serbian in Latin script).
• The variant code is optional and usually omitted for the default file for an administrative region. Where a particular category has an excessive number of holidays that may not be suitable for the default file, e.g. Name Days) then these can be split into a separate file and named with the category, e.g. "holiday_gr_el_nameday" for Greek Name Days. If the file's internal Name metadata tag is not populated, then the variant code will be used by KHoliday in generating the Name. To ensure this is properly translated you must use one of the pre-defined variant tags, or add the tag and translation to the KHolidayRegion class. Currently supported variant codes are: public, civil, religious, government, financial, cultural, commemorative, historical, school, seasonal, nameday, personal, catholic, protestant, orthodox, jewish, islamic.

File Template

When creating a new holiday file please copy this template and complete all the fields within the square brackets [ ] before adding the holidays under each category heading. See below for an explanation of the categories.

All lines starting with a ":" are comments and are ignored by the parser.

::
:: Country:  [Name]
::
:: Language: [Name]
::
:: Author:   [Name <[email protected]>]
::
:: Updated:  [YYYY-MM-DD]
::
:: Source:   [Source URL 1]
::           [Source URL 2]

:: Metadata
country     "XX"
language    "xx"
:name        "[optional - defaults to country name]"
description "[please add description in source language, e.g. National holiday file for $country]"

:: Public Holidays 

:: Civil

:: Religious

:: Government

:: Financial

:: Commemorative

:: Cultural

:: Historical

:: School

:: Daylight Saving (Winter/Summer Time)

:: Seasons

:: Name Days