1 Preface

The reason why I have written Gcal was mainly to have an off-line tool¹ which is able to display Julian and Gregorian calendar sheets in a highly flexible and internationalized manner, fixed date lists for reminding purposes and country respectively territory specific holiday lists. At a later stage, Gcal was extended in the way to perform some basic astronomical calculations like Moon phase, moonrise, moonset and other Moon based data, sunset, sunrise, different twilight times and other Sun based data, zodiacal markers, solar and lunar eclipses, equinoxes and solstices. Other gimmicks like biorhythm calculation and the computation of a distance between two geographical point locations and their course angles (true tracks) are also done by it now, plus a lot more.

The accuracy of most of the astronomical calculations done by Gcal is low because it is really hard to perform accurate astronomical predictions more that 100 years ahead. Of course, this also has consequences for some country specific holidays which are based on such astronomical calculations. So it is really possible that some output may differ from the real astronomical date and time of the event calculated, and that by one or more minutes/hours/days. This can happen when the date of a real astronomical event occurs near around midnight. So don’t be surprised! Strictly speaking, take all such astronomically based output as a more or less good approximation of the true value, but do not rely on it!

Because Gcal is not primarily designed for the purpose of having a high precision astronomical calculation tool, the world currently has to live with these limitations. But if you have C source code functions, which

• perform the astronomical calculations more precise for the period that is respected by Gcal,
• have the similar or faster processing speed than Gcal’s actual functions,
• are either put into the public domain or are covered by the GPL²,
• have the same calling conventions and return types like Gcal’s actual functions,
• conform to the GNU coding standard and are therefore easy to maintain and extend,
• do not break Gcal internal limitations and concepts,

and you want to grant them to the public, I would be very pleased if you would contact me so I am able to implement your result to a next release of this software.

Some words to the build-in country specific holidays now…

As you certainly know, there are several other calendar systems actually existing around the world among the Gregorian calendar. The Gregorian calendar that Gcal mainly represents as a software is only one calendar of many others, but it is that one which is most respected around the world today. Even countries which use another calendar system officially mostly respect the Gregorian calendar for civil and administrative purposes.

But when Gcal offers the ability to include holidays from a definite country into its eternal holiday list, it is possible that not all holidays are displayed which are respected in that country. One reason is that my various sources simply don’t tell me about the existence of a holiday. A second reason is that the holiday is just designed or changed or removed by political or society reality during Gcal’s development phase. And another reason is that the method to calculate a holiday is not build-in Gcal yet. This case is marked by a ‘#’ character behind the country name in the list of countries, which are respected by Gcal. See Calendar option --cc-holidays=cc[_tt][+…], for the above mentioned list.
The holidays of early years that are included into the eternal holiday list —i.e. those within the period AD 30 until the midth of the 20th century— are certainly not accomplishing the requirements of historians to such a list. Gcal cannot be understood as a complete and historically correct data base, and it is not designed for that purpose! This is caused by the fact that the territorial borders and names of the national structures and the settlement in earlier times was partly quite different as it is nowadays. Moreover, I am yet lacking reliable information that tells me the precise date of the introduction of a holiday in a region. Here I appeal to the historians to support me with the concrete country and culture based data if they are bothered by this fact and they want to have it removed.

Still unsupported alive and major calendar systems, respectively methods to derive country specific holidays from them, are:

• Religious Islamic lunar calendar
• Hindu solar and lunar calendars
• Buddhist calendar
• Sikh calendar
• Jain calendar

Even if the list of supported countries seems to be almost complete if you compare it with the actual list of all nations existing around the world, you should note that there are still some countries missing! If you can grant me support to complete Gcal’s list of respected countries, or if you would work out or have C functions which manage the missing calendar systems, I also would be very pleased about if you would contact me.

I have recorded the country specific holiday dates as good as I can, but I cannot guarantee that I did not made any mistakes while I hacked them in. So it is possible that some country specific holiday lists contain errors.

Well, if you think that I forgot to provide Gcal with the specific holidays of a/your country, or you think that a country specific holiday list is incomplete, or you think that some of the already implemented holidays are wrong, please feel free to send me a complete list of all the holidays which are celebrated in this country respectively to give me hints how to correct or to complete them!

Such a list should ideally include the following information:

• The English name of the holiday.
• The rule how it is built (like 10th October each year, or 47 days after Easter Sunday’s date, or three Fridays before the last Saturday in June…). If there are any exceptions from such a general rule, please state them in a detailed manner. And please tell me the date since what time the holiday is or was celebrated for the first time, respectively.

  By the way, if the holiday is tied to the Easter Sunday’s date, please tell me whether you mean the Easter Sunday of the Christian Western churches or the Easter Sunday of the Orthodox Christian Eastern churches.

• Whether it is a legal holiday which is respected in the whole country. (Use a ‘+’ character for marking this case.) In this sense, a legal holiday means a day people don’t have to work — as in most companies, and businesses are closed; like ‘New Year's Day’ on January 1st.
• Whether it is a legal holiday in some parts of your country only. Please tell me whether such a holiday is valid in major parts of the country or not, try to express that by using percent points. (If such a holiday is celebrated in more than 70% of the country, use a ‘#’ character for marking this case, otherwise use a ‘*’ character.)
• Whether it is a day only used for memorial or remembering purposes. (Use a ‘-’ character for marking this case.) Like ‘All Fool's Day’ on April 1st is not a holiday in the sense that anyone has a day off from school or work, just a play jokes day, pretty ordinary. Other holidays may be celebrated with cards or presents etc. — but they are working days such as:

  Valentine's day, Father's day, Mother's day.
  

The Islamic holidays inserted into the country specific holiday list are calculated arithmetically, not astronomically. This is what people call the civil Islamic lunar calendar. This type of calendar is just a rough estimate of the religious Islamic lunar calendar, which is determined quite astronomically. So don’t be surprised too much if some holiday dates differ from the religious Islamic calendar about +/- 1…2 days in some years.
The main difficulty to implement the religious Islamic calendar correctly into Gcal are the several different criteria that are existing for the first sighting of the crescent Moon after a New Moon phase — that event, which defines the beginning of a new (lunar) month in the religious oriented Islamic calendar. So on the one hand, there are quite astronomically-based criteria, and on the other hand, there are also quite religiously-based criteria. Furthermore, the local predominant weather conditions, the geographical co-ordinate of the observer’s location and the kind of the observance method used also affect these criteria. Moreover, to render all more difficult, I as yet do not have any reliable information that tells me which kind of criteria is used in the countries (around 60 world-wide) which respect this religious Islamic calendar. So due to all the above mentioned facts of problematic nature, this religious Islamic calendar is not included into Gcal yet.

The Chinese (and Japanese) holidays also inserted into the country specific holiday list are calculated by using that algorithm as it is used by the Purple Mountain Observatory in Nanjing to determine the astronomical lunisolar Chinese calendar. This calendar is obligatory for (the Peoples Republic of) China since 1929 and is determined annually always new. Nevertheless and strictly speaking, in the historic reality and depending on the region, the Chinese calendar, especially in the 17th and 18th century, was either calculated using this modern algorithm, or by the use of a different method, so that a different calendar structure for one and the same year was possibly calculated as result.

And last…

This manual shows the possible use of the Gcal program only briefly and deliberately renounces to present the topics that are covered by this software arranged in a novel-like style. The use of Gcal is illustrated in an exemplary manner only! A detailed description of all possible use is inexpedient here because there are simply too many of such possibilities which are caused by the existing variety of combinations of all useable modes of operation.

Furthermore, this manual does not contain detailed explanations about the calendar systems supported by Gcal, nor it can be understood as a reference-book for the basics in celestial mechanics or spherical trigonometry! A detailed discussion of the above topics is completely beyond the scope of this manual. If you are interested to learn more about these subjects, you unfortunately have to read the specific pertinent literature.

Any further errors occurring in the output of the above mentioned holiday lists and in the astronomical calculations are my own fault, and are not intended to offend members of any culture, religion or profession!