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
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
0009 [JPL 2009-12-13 Added a few comments.  John Layt <john@layt.net>]
0011 I. Introduction
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.
0017    See http://www.wikipedia.org/Holidays for better, clearer explanations.
0019 II. Goals
0021    We hope that the new kholidays library will:
0023    A. allow KOrganizer to replace the holidays plugin with a KOCore
0024       implementation that links to the kholidays library.  
0026    B. allow KOrganizer to support the holidays of many religions (through
0027       plugins if desired)
0029    C. be part of kdelibs so other applications and components (eg. kdatepicker)
0030       can access holidays.
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.
0035 III. Definitions
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.
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.
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?)
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, ...
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.
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?
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.
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.
0078    Noteworthy Event: a day of interest.  eg. Daylight Savings Time Start/Stop,
0079         Election Day, ...
0081 IV. Requirements
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.
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?]
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.
0106    * The political regions will have their own holiday file containing
0107      (possibly through inheritance) the public, cultural, and financial holidays
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>, ...
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.]
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, ...
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.
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. ]
0134    * Be able to specify holidays with compound dates; i.e, be able to 
0135      combine specifications.  For example: "First Monday after May 1"
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)
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.
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.
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.
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         ...
0168    * Each Holiday can have any combination of Holiday type.
0170    * Each Holiday can have its own icon.
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?]
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.
0182    * Be able to activate more than one region/locale at a time and more
0183      than one religion at a time.
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.
0193    * The standard KDE tools will be used to translate holiday names.
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.
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).
0205 V. Functionality
0207    A. The library will provide functions that:
0209       * Returns a list of all holidays per date.  The list will have duplicate
0210         holidays removed (deduped).
0212       * Returns a list of all holidays for a range of dates, in date order.
0213         The list will have duplicate holidays removed (deduped).
0215       * Returns a list of all holidays for a Gregorian year, in date order.
0216         The list will have duplicate holidays removed (deduped).
0218       * "Add" a list of Holidays together.
0220       * "Dedupe" a list of Holidays.
0222       * Determine if a date lands on a new moon, first quarter moon,
0223         last quarter moon, or full moon.
0225       * Determine if a date lands on a solstice or equinox.
0227       * Determine if a date is a work day-off, school day-off, or bank-closure.
0229       * Provides holiday names in current language
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.
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.
0239       *
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.
0246    C. Provide a GUI to create, edit, and translate the holiday files.
0248 VI. Date Specification
0250    The holiday date can have one of the following specifications:
0252    * Fixed date: the date is fixed on the calendar.
0254    * Postional date: the date occurs according to a position,
0255                        eg. "first Monday in September".
0257    * Moon date:  the date corresponds to a phase of the moon.
0259    * Solstice date: the date corresponds to the June or December solstice.
0261    * Equinox date: the date corresponds to the March or September equinox.
0263    * Christmas: the holiday occurs on Christmas.
0265    * Easter: the holiday occurs on Easter.
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.
0271 APPENDIX A.  Classifying Holidays (Sample)
0273    This list of holidays was extracted from the US Holidays
0274    at http://www.mozilla.org/projects/calendar/holidays.html
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
0308 -----end here-----
0310 Religions: Catholic, Greek Orthodox, Jewish, Islam, Protestants,...
0312 Other special dates of interest:
0313  + start/end daylight savings time
0314  + election day
0315  + 
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.]
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.
0326 -----------------
0328 JPL  Pre-requisite steps?:
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
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?
0337 freedesktop.org: Common XML format and location for holiday files to save duplication?
0338                  Common definitions for calendar system names and formulas?