Warning, /frameworks/kholidays/DESIGN is written in an unsupported language. File is not indexed.
0001 What: A New kholiday library 0002 Author: Allen Winter <email@example.com> 0003 Version: 0.92 2006-04-02 0004 0005 This is a draft. Please send constructive comments to the author. 0006 I'm trying hard not to offend anybody. If I make a mistake, particularly 0007 about religious holidays, please let me know about it. --Allen 0008 0009 [JPL 2009-12-13 Added a few comments. John Layt <firstname.lastname@example.org>] 0010 0011 I. Introduction 0012 0013 The current kholidays library code was borrowed from the 'plan' project 0014 many years ago and, has been discussed often on the KDE-PIM mailing list, 0015 we need to replace it with a modern library with a friendly license. 0016 0017 See http://www.wikipedia.org/Holidays for better, clearer explanations. 0018 0019 II. Goals 0020 0021 We hope that the new kholidays library will: 0022 0023 A. allow KOrganizer to replace the holidays plugin with a KOCore 0024 implementation that links to the kholidays library. 0025 0026 B. allow KOrganizer to support the holidays of many religions (through 0027 plugins if desired) 0028 0029 C. be part of kdelibs so other applications and components (eg. kdatepicker) 0030 can access holidays. 0031 0032 D. be licensed so that it can be linked directly to all KDE applications 0033 and can be ported freely to other platforms with binary-only Qt. 0034 0035 III. Definitions 0036 0037 Holiday: any day that may have special significance to a fairly large 0038 number of people. A "holy day" can be a holiday, a "day-off" for 0039 all public employees can be a holiday. Also, the remembrance of an 0040 historical event can be a holiday. 0041 0042 Public Holiday: a day-off from work or school (typically) to commemorate 0043 a historical event, or to honor people. Public holidays are always 0044 bounded to a political region at national, regional or local level. 0045 0046 Public/Civil Service Holiday: a day-off from work for government workers 0047 but not a day off for private sector workers. (name Government Holiday, 0048 or is that different?) 0049 0050 Cultural Holiday : a special day in the culture and therefore usually 0051 bounded to a political region. A day where people "celebrate" 0052 in some fashion. eg. Halloween, St. Valentines, ... 0053 0054 Religious Holiday: a special day in a religion and not bounded to any 0055 political region. Religions can have holidays that range in 0056 devotion to those were work/school are forbidden, days of 0057 prayer obligation, to historical remembrances, etc. 0058 Governments often have public holidays for some religious holidays. 0059 0060 Financial Holiday: banks and markets may close on some public holidays. 0061 it would be useful for financial applications to know when. 0062 Financial holidays are tied to public holidays and therefore are 0063 always bounded to a political region. Not sure if financial holidays 0064 move from weekends; eg. if Christmas lands on a weekend is it moved 0065 to a nearby business day? 0066 0067 School Holiday:a day-off from school, either as a one-off Public Holiday or 0068 extended periods between school terms. This can vary widely depending 0069 on school level, type, location. The differing holidays can be held in 0070 separate files, e.g. State Primary, State Secondary, State University, 0071 local religious school, etc. 0072 0073 Name Day Holiday: (See Bug #92919) In some countries each day is assigned 0074 a first name and persons with that name celebrate that day as their 0075 "Name Day". We will require Name Days to be bounded to a political 0076 region. 0077 0078 Noteworthy Event: a day of interest. eg. Daylight Savings Time Start/Stop, 0079 Election Day, ... 0080 0081 IV. Requirements 0082 0083 * All non-religious date calculations will be performed according to the 0084 Gregorian calendar. To use another calendar, one will need to convert 0085 their date to Gregorian first. 0086 0087 [JPL: No. In Iran for instance if the rule for a public holiday is defined 0088 as the 1st occurrence of the 3rd weekday of the 9th month of the Jalali 0089 calendar (first Chahar Shanbe of Azar) it would not be valid to 0090 convert that into the first Wednesday of September in the Gregorian 0091 calendar, there could be no formulation that would always work other 0092 than expressing the rule in the Calendar System that it applies to. 0093 This means all holiday recurrence rules not defined in the Gregorian 0094 default must define the Calendar System used to calculate them. This 0095 may also mean the recurrence rules must always use month and weekday 0096 numbers rather than names, except that some calendar systems such as 0097 the Hebrew add leap months in the middle of the year which change the 0098 month numbering but are not counted when calculating recurrances. Use 0099 either the existing calendarType e.g. "jalali" or a new short code 0100 "JA" or a new standard agreed on FDO?] 0101 0102 * Religious holidays will be computed on the appropriate calendar. 0103 i.e. Jewish holidays on the Hebrew calendar. The calling application 0104 can then convert the date to Gregorian, if desired. 0105 0106 * The political regions will have their own holiday file containing 0107 (possibly through inheritance) the public, cultural, and financial holidays 0108 0109 * Holidays of political regions will be specified in in files in a 0110 hierarchy similar to how timezones are stored in /usr/share/zoneinfo. 0111 eg. holidays/Canada/<Province>, holidays/US/<State>, 0112 holidays/Europe/Germany/<Province>, holidays/Australia/<State>, ... 0113 0114 [JPL: Political regions could be incorporated into KLocale and the Region 0115 KCM to allow users to set a global default. The ISO standard is 0116 for-pay at this level, but Wikipedia has a fairly complete set so it 0117 may still be legal to use. We could also then tie regions and 0118 timezones together for better timezone defaults.] 0119 0120 * Religious holidays will be specified in files separate from the 0121 political region files, by religion name: 0122 eg. holidays/Religious/Jewish, holidays/Religious/Catholic, ... 0123 0124 * Be able to specify where to move public, day-off holidays if they 0125 land on a weekend. This occurs for holidays with a fixed date. 0126 0127 [JPL 0128 * Be able to specify where to move holidays if they reccur on a day that 0129 doesn't exist, e.g. whether holiday on 29th February should only ever 0130 occur on 29th Feb or should be moved to the 28th Feb or 1st March. This 0131 particularly applies to religious holidays in calendar systems where the 0132 number of months and days in months can vary more than in Gregorian. ] 0133 0134 * Be able to specify holidays with compound dates; i.e, be able to 0135 combine specifications. For example: "First Monday after May 1" 0136 0137 * Support lunar phases for the new moon, first quarter moon, 0138 last quarter moon, and full moon. 0139 (One should be able to see moon phases on the calendar as this is 0140 important to some religions -- but this is an application issue) 0141 0142 * Support june solstice, december solstice, march equinox, and 0143 september equinox -- the so-called "astronomical seasons". 0144 So, in the US for example, one could set a holiday of 0145 summer is on the june solstice. 0146 0147 * Public holidays that are moved when they land on a weekend will have 0148 their names changed to "Name (Day off)". For example, in the US if 0149 Christmas is on a Sunday, then it will be moved to Monday and have the 0150 name changed to "Christmas (Day off)". Note that if the user has chosen 0151 a Christian set of holidays they will also see "Christmas" on the Sunday. 0152 0153 * Local governments (states, provinces) will be able to inherit their 0154 holidays from the national government. In general, any holiday set 0155 can inherit holidays from any other holiday set. We expect to use 0156 an "include file" mechanism to support inheritance. 0157 0158 * Support Holiday categories: 0159 work day-off (public), 0160 school day-off (public), 0161 bank-closed holiday (financial), 0162 noteworthy event (cultural), 0163 religious holiday (religious), 0164 holy day (religious), 0165 name day (cultural), 0166 ... 0167 0168 * Each Holiday can have any combination of Holiday type. 0169 0170 * Each Holiday can have its own icon. 0171 0172 [JPL: Each Holiday Type could also have a default icon and colour, e.g. 0173 national work day-off marked in red, regional day off in blue, 0174 financial in green, etc. Perhaps able to be user or locale modified?] 0175 0176 * For the most part, keep religious holidays out of public holidays 0177 and in their own specific holiday files. The exception is when 0178 the governments have religious, public holidays. A religious holiday 0179 that is also a public, work/school day-off should be specified in 0180 government (political) holiday files. 0181 0182 * Be able to activate more than one region/locale at a time and more 0183 than one religion at a time. 0184 0185 * Holiday names should be in English so they can be translated with the 0186 usual tools. If a holiday name has no English equivalent then it can 0187 be written in the "native" language. If English is not practical, 0188 then the holiday names can be written in the "native" language and 0189 possibly translated into English later. In other words, we want to 0190 make it easy for people to contribute holiday files so don't exclude 0191 non-English speakers from writing one. 0192 0193 * The standard KDE tools will be used to translate holiday names. 0194 0195 * Holiday file format will in XML according to a RELAX NG schema. 0196 There will be tools written to parse and validate our file format 0197 if none are currently available. 0198 0199 * We will write simple tools to convert existing holiday file formats to 0200 our new format. These tools should provide some easy validation checks. 0201 The new files will be used to bootstrap the new library into KDE. 0202 It might also be useful to write a program to convert iCalendar files into 0203 our format (see http://www.mozilla.org/projects/calendar/holidays.html). 0204 0205 V. Functionality 0206 0207 A. The library will provide functions that: 0208 0209 * Returns a list of all holidays per date. The list will have duplicate 0210 holidays removed (deduped). 0211 0212 * Returns a list of all holidays for a range of dates, in date order. 0213 The list will have duplicate holidays removed (deduped). 0214 0215 * Returns a list of all holidays for a Gregorian year, in date order. 0216 The list will have duplicate holidays removed (deduped). 0217 0218 * "Add" a list of Holidays together. 0219 0220 * "Dedupe" a list of Holidays. 0221 0222 * Determine if a date lands on a new moon, first quarter moon, 0223 last quarter moon, or full moon. 0224 0225 * Determine if a date lands on a solstice or equinox. 0226 0227 * Determine if a date is a work day-off, school day-off, or bank-closure. 0228 0229 * Provides holiday names in current language 0230 0231 * Returns a QStringList of all political regions supported, 0232 (possibly/probably) extracted from the holiday file names. 0233 The region names will need to be translated into all languages. 0234 0235 * Returns a QStringList of all religions supported, 0236 (possibly/probably) extracted from the holiday file names. 0237 The religion names will need to be translated into all languages. 0238 0239 * 0240 0241 B. A KGetNewStuff mechanism will be implemented so that holiday files 0242 can be donated to the project and installed by using this common 0243 PIM mechanism. 0244 0245 0246 C. Provide a GUI to create, edit, and translate the holiday files. 0247 0248 VI. Date Specification 0249 0250 The holiday date can have one of the following specifications: 0251 0252 * Fixed date: the date is fixed on the calendar. 0253 0254 * Postional date: the date occurs according to a position, 0255 eg. "first Monday in September". 0256 0257 * Moon date: the date corresponds to a phase of the moon. 0258 0259 * Solstice date: the date corresponds to the June or December solstice. 0260 0261 * Equinox date: the date corresponds to the March or September equinox. 0262 0263 * Christmas: the holiday occurs on Christmas. 0264 0265 * Easter: the holiday occurs on Easter. 0266 0267 In addition, the date can have a "before weekend" or "after weekend" 0268 modifier, meaning that if the holiday date lands on a weekend, the date 0269 is moved to the first workday/schoolday before or after the weekend. 0270 0271 APPENDIX A. Classifying Holidays (Sample) 0272 0273 This list of holidays was extracted from the US Holidays 0274 at http://www.mozilla.org/projects/calendar/holidays.html 0275 0276 New Year's Day: public, work day-off, school day-off, bank-closed, move from weekend 0277 Groundhog Day: noteworthy event. no day-offs 0278 Lincoln's birthday: noteworthy event, no day-offs 0279 Washington's birthday: noteworthy event, no day-offs 0280 Valentine's Day: cultural, no day-offs 0281 Palm Sunday: religious, no day-offs 0282 Good Friday: religious, no day-offs 0283 Easter (Western): religious, no day-offs 0284 Easter (Orthodox): religious, no day-offs 0285 Tax Day: noteworthy event, no day-offs 0286 April Fool's Day: cultural, no day-offs 0287 St. Patrick's Day: cultural, no day-offs (perhaps religious, I don't know) 0288 Flag Day: noteworthy event, no day-offs 0289 Independence Day: public, work day-off, school day-off, bank-closed, move from weekend 0290 Columbus Day: public, work day-off, school day-off, bank-closed 0291 Halloween: cultural, no day-offs 0292 Veteran's Day: public, work day-off, school day-off, bank-closed, move from weekend 0293 Christmas: public, work day-off, school day-off, bank-closed, move from weekend 0294 Martin Luther King's Birthday: public, work day-off, school day-off, bank-closed 0295 President's Day: public, work day-off, school day-off, bank-closed 0296 Daylight Savings Time begins: noteworthy event 0297 ASH Wednesday: religious, no days-off 0298 Memorial Day: public, work day-off, school day-off, bank-closed 0299 Mother's Day: cultural, no days-off 0300 Father's Day: cultural, no days-off 0301 Labor Day: public, work day-off, school day-off, bank-closed 0302 Daylight Savings Time ends: noteworthy event 0303 Election Day: noteworthy event, school day-off 0304 Thanksgiving: public, work day-off, school day-off, bank-closed 0305 0306 0307 0308 -----end here----- 0309 0310 Religions: Catholic, Greek Orthodox, Jewish, Islam, Protestants,... 0311 0312 Other special dates of interest: 0313 + start/end daylight savings time 0314 + election day 0315 + 0316 0317 See Reinhold's XML DTD (holiday.dtd) 0318 [Reinhold: I didn't check the DTD at all, so it might be completely wrong 0319 or breaks with all XML specs or whatever. Basically, currently it's meant 0320 only to develop a nice structure of the files, not for real use in code yet.] 0321 0322 A good starting point [..for parsing Reinhold's XML..] would be to use some code 0323 from the kconfig_compiler in kdelibs/kdecore/kconfig_compiler, which parses 0324 the XML file. 0325 0326 ----------------- 0327 0328 JPL Pre-requisite steps?: 0329 0330 KLocale & KCM: Add political regions to countries, allow kcm to set up 0331 Add users lat/lon for use in lunar calculations, allow KCM to set up 0332 0333 KCalendarSystem: Proper astronomical (lunar/solar) calendar support 0334 Additional calendar systems as required (e.g. Julian, Chinese, etc) 0335 Add standard short code for each calendar system? 0336 0337 freedesktop.org: Common XML format and location for holiday files to save duplication? 0338 Common definitions for calendar system names and formulas?