
COMPREHENSIVE MANUAL FOR CALH / CALH_TSR (version 1.2) 
======================================================
Benno van Dalen 1996/1997


1) When the opening screen appears simply press <ENTER>.

2) A calendar can be selected by pressing the first letter of its 
   name or by moving the highlighted bar to the desired calendar 
   and pressing <ENTER>. 

3) When entering a date, CALH excepts any input as soon as it is 
   unambiguous. This means that, for the day of the month, digits 4 
   till 9 are accepted at once, whereas after digits 1 till 3 either 
   <RETURN> or a second digit is expected. 

   Months can now also be entered by their number (as shown in 
   the listing on the right of the screen, note that leap months or 
   "epagomenae" always have number 13); digits 2 till 9 are accepted 
   at once, after digit 1 either <RETURN> or a second digit is 
   expected. Alternatively, the month can be selected by moving the 
   highlighted bar to the desired month and pressing <ENTER>. The 
   highlighted bar can be moved by using the up- and down-arrow 
   keys as well as by typing the first letter of a month name.

   Years are NOT accepted as soon as a fourth digit has been 
   entered in order to allow correction of typos. If the year 
   number is STARTED with a - (minus sign) it will be counted in 
   the astronomical way (i.e. the year 1 is preceded by years 0, 
   -1, etc.). If a minus sign is typed after one or more digits of 
   the year number have been entered, the year will be taken to be 
   before the epoch concerned and the epoch indication will be 
   changed consequently (before Christ, before Nabonassar etc.) 
   Note that, except for the Julian and Gregorian calendars, years 
   before the epochs will only be shown if the toggle SHIFT-F3 is on 
   (see below). 

   At any time the calendar variant can be changed by pressing TAB 
   or SHIFT-TAB. A message at the bottom of the screen indicates 
   whether the selected calendar actually has variants or not. 
   Depending on the newly selected variant some entries on the 
   screen may change (order of the months, name of the epoch), but 
   the date remains as it has been selected so far.

   Finally, once you have specified the date as desired, the <ENTER> 
   key may be pressed in order to perform the conversions to all 
   available other calendars. 

4) The corresponding dates in all calendars will be shown on a 
   single screen. After every date,  indicates a leap year. For 
   the Hebrew calendar the type of year is indicated by its length.

   You now have the following operations at your disposal (which are 
   all shown at the bottom of the screen):

   a) Change the date by jumping forwards or backwards by a day, 
      week, month, year, 10 years, or a century by pressing D, W, 
      M, Y, T and C (forwards) or the same keys while holding the 
      ALT-key (backwards). The jumps are performed in the current 
      calendar (originally the one in which you have entered a 
      date), even if you have moved the highlighted bar to a 
      different calendar. To change the current calendar to the 
      one which is presently highlighted, press F8 (one of the 
      special commands which is shown at the bottom of the screen 
      only when you type F9, see below).

   b) Change the date by jumping a number of days to be specified 
      by pressing F3. At the prompt in the upper part of the screen 
      type a positive number of days to jump forwards, a negative 
      number to jump backwards.

   c) Save a date in order to be able to return to it quickly by 
      pressing F4. The message _date saved_ will be shown at the 
      bottom of the screen. You can save 10 different dates at the 
      most, the eleventh save will erase the first one. To jump back 
      to previously saved dates, type F5, which will cycle through 
      the saved dates. 

   d) Count the number of days between certain dates using the 
      "Total jump: " indicator at the bottom of the screen. The 
      number indicated is the difference in days between a 
      "reference date" (originally the first date entered after 
      starting the program) and the currently selected date. The 
      reference date can be reset to the presently selected date 
      by pressing F6; the "Total jump: " indication will then 
      disappear, meaning that it is presently zero. 

      Example 1: To find the number of days between two particular 
      dates, first enter the first date in any way you like, press 
      F6, enter the second date in any way you like, and read off 
      the "Total jump".

      Example 2: Finding the number of days between two epochs 
      can be done particularly fast by using F7, "jump to epoch", 
      another special command (see below): move the highlighted 
      bar to the first calendar, press F8 to make it the current 
      calendar and F7 to jump to its epoch. Press F6 to reset the 
      counter. Now move the highlighted bar to the second calendar 
      and again type F8 and F7. Then read off the "Total jump".

   e) Change the date into the epoch of the current calendar by 
      pressing F7. To change the current calendar, use F8 (f) below).

   f) To change the current calendar (in particular necessary for 
      jumping to to the epoch of a calendar different from the one 
      in which you have entered a date or to use the jump functions 
      under a) for a different calendar), move the highlighted bar 
      to it and press F8. A message at the bottom of the screen 
      indicates that the current calendar has been reset. You can 
      easily recognize which calendar is the current one, because 
      the highlighted bar is reset to the current calendar after 
      every jump operation.

   g) Change the variant of any calendar by moving the highlighted 
      bar to it and pressing TAB or SHIFT-TAB. The highlighted bar 
      can be moved by using the arrow keys or typing the first 
      letter of the calendar name except when this letter is one of 
      the keys D, W, M, Y, T, or C, which are reserved for jumping 
      as explained under a).

   h) Change the way in which the dates are displayed in one of the 
      three following ways. All three are "special" functions, only 
      shown on the screen when F9 is pressed. Furthermore, all three 
      are "toggles", which means that the reverse operation can be 
      performed by pressing the same key once again.

      1) Toggle the indication of the month number (in square 
         brackets after the month names) by pressing SHIFT-F1.

      2) Toggle the use of astronomical years versus years before 
         the epochs. For instance, SHIFT-F2 will change the year 10 
         Before Christ into -9 and conversely. 

      3) Toggle the display of years before the epochs by pressing 
         SHIFT-F3. If this toggle is off, only for the Julian and 
         Gregorian calendar dates before the epochs are always 
         shown. To see the effect of this toggle, select a date 
         like 1 January 1 A.D. and press SHIFT-F3.

At any time, if you want to enter a new date in the current calendar, 
type F2; if you want to enter a date in a different calendar, type 
F1. To leave the program, type F10 or ESC. In the memory resident 
version CALH_TSR (TSR for Terminate-and-Stay-Resident) the effect 
of F10 and ESC is slightly different: F10 resets the program to the 
initial screen, so that you will have to start from the beginning 
when calling the program again. ESC leaves the state of the program 
unaltered, so that you will be returned to the same date (and the 
same settings of current calendar, reference date, stored dates) as 
before.

Note: you can use the special functions F7, F8, SHIFT-F1, SHIFT-F2 
and SHIFT-F3 at any time; there is no need to type the special key 
F9 first. In fact, F9, does nothing more than showing the menu of 
the special functions.



LATER ADDITIONS:

Version 1.21 (1 Februari 1997):
    SHIFT-F7 jumps to the beginning of the current year in the 
    current calendar. For instance, to find the Byzantine New Year 
    just preceding the Hijra epoch, first select the Hijra epoch 
    (either by specifying 1 Muharram 1 in the date selection screen 
    or by using F7), then make the Byzantine calendar the current 
    one by pressing F8 when it is highlighted, and finally press 
    SHIFT-F7.



BUGS:
In versions 1 and 1.1, I sometimes noted strange things when jumping
through dates using the M, Y, T and C with or without the ALT-key.
Versions 1.2 and 1.21 have not yet been tested anew. Since the changes
from version 1.1 are relatively small, I expect few problems. If you
encounter strange things, please report them to me.

There are some problems with the memory resident version CALH_TSR
which I do not understand very well and will probably not be able
to fix. They are probably related to interrupts (in particular,
the timer interrupt) and sometimes cause the program or the whole
machine to crash. Part of the problems seem to occur on slow
machines (I have had no problems like this on a fast 486 or
pentium), others when converting dates in the Uighur and Maliki
calendar (on any machine). Before trying out the memory-resident
version, please save your data in other programs.

Millennium Bug: Internally CALH and CALM operate with year numbers
between -9999 and +9999; dates which fall without that range will
be indicated by a hyphen behind the name of the calendar concerned.
CALH and CALM do not carry out any operations involving the system
date and/or time. Therefore, both programs can be considered to be
millennium proof.

Disclaimer: The author of CALH disclaims liability for any errors
that may be present in the program and for any damage that may ensue
from its use.


        Benno van Dalen
        Institut fuer Geschichte der Naturwissenschaften
        Postfach 111932 (FB 13)
        60054 Frankfurt am Main
        GERMANY
        Email: dalen@em.uni-frankfurt.de
