Warning, /frameworks/kholidays/DESIGN is written in an unsupported language. File is not indexed.

0001 What:       A New kholiday library
0002 Author:     Allen Winter <winter@kde.org>
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 <john@layt.net>]
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?