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 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 code Alpha2 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.