hcal man page (v1.8)

Boruch Baum

hcal man page (v1.8)

Although hdate v1.8 is still under development, here is a snapshot of the man page reflecting the features already coded and committed to the svn repository.

hcal(1)                            libhdate                            hcal(1)

       hcal - displays a Hebrew / Gregorian calendar

       hcal [options] [coordinates] [timezone] [[mm]yyyy]

       coordinates: -l [NS]yy[.yyy] -L [EW]xx[.xxx]
                    -l [NS]yy[:mm[:ss]] -L [EW]xx[:mm[:ss]]
       timezone:    -z nn[(.nn|:mm)]

       hcal  prints  a  calendar  with both Gregorian and Hebrew dates for the
       specified Gregorian month or, if no month is specified, for  the  whole
       Gregorian  year.  If  no  arguments  are  given,  it prints the current
       month's calendar. Jewish holidays are annotated, and can optionally  be
       footnoted.  hcal  tries  to be sunset-aware in order to correctly high‐
       light the current Hebrew date, and can also display Shabbat  times  and
       parshiot. See the section LOCATIONS, below.

       INPUTTING  A  HEBREW  DATE:  If the year provided is greater than 3000,
       hcal will interpret the given date as a Hebrew date, and  will  display
       the calendar of the corresponding Gregorian month(s). Hebrew months are
       expected to be passed as numbers 1-12 for Tishrei - Elul;  Adar  I  and
       Adar  II  are expected to be passed as months 13 and 14. Currently, the
       maximum value hcal accepts for a Hebrew year is 10999.

       INPUTTING A GREGORIAN DATE: hcal interprets year values  in  the  range
       1000  -  2999  as gregorian. Numeric months are interpreted as 1-12 for
       January - December.

       ACCEPTABLE DATE FORMATS: Prior versions of hcal insisted on the numeric
       date format [[yyyy [mm  [dd]]].  hcal now accepts numeric date elements
       in any easily discernable order. hcal now accepts  Hebrew  month  names
       and gregorian month names in both full and abbreviated formats, and not
       case-sensitive. Gregorian month names may be  entered  in  either  your
       locale's  language  or in English. Hebrew month names may be entered in
       either Hebrew characters or in  many  transliteration  forms  to  latin
       characters  (see  EXAMPLES  below).  hcal  will intelligently interpret
       ambiguous numeric datespec parameters. For example,  a  parameter  "32"
       could  only legitimately be a two-digit year, so hcal will, by default,
       interpretat it as a two-digit Hebrew year in the current (58th) century
       (see option --prefer-gregorian and section CONFIG FILES below).

       -0 --no-gregorian This  is  the  default.  It  prints only Hebrew month
                         information. The option exists  only  to  override  a
                         posible contrary config file setting.

       -1 --one-month    over-ride  config  file setting if you had set option
                         --three-month as a default there

       -3 --three-month  print previous/next months, side  by  side.  requires
                         127 columns

          --borders      displays a frame around calendars in three-month mode
          --spacing      quoted string to separate months in three-month mode

       -b --bidi         print Hebrew information in Hebrew , in reverse
          --visual       sequence

          --no-bidi      over-ride config file setting if you had set
          --no-visual    option --bidi as a default there

       -c --colorize     print  in  calming,  muted tones. -cc will display in
                         bolder, and mildy irritating, colors.
          --no-color     over-ride config file setting

       -d --diaspora     use diaspora reading and holidays. Only  relevant  if
                         hcal  is  using  location  information  indicating an
                         Israeli timezone

       -f --footnote     print descriptive notes of holidays
          --no-footnote  over-ride config file setting

       -g --gregorian    include gregorian corresponding days. -gg displays  a
                         gregorian month with corresponding Hebrew days. Spec‐
                         ifying option -g with a gregorian date is  equivalent
                         to requesting the Hebrew month in which the first day
                         of that specified gregorian month appears.

       -h --html         print in html format to stdout
          --no-html      over-ride config file setting

       -H --hebrew       print Hebrew  information  in  Hebrew,  in  'logical'
                         sequence.  If  this  displays in reverse for you, use
                         option -b

       -I --israel       override a diaspora default. Only relevant if hcal is
                         using  location  information indicating other than an
                         Israeli timezone

       -i                use external css file "./hcal.css" for html output

          --no-reverse   do not highlight today's date

       -m --menu         prompt user-defined menu from config file. See  there
                         for details and examples.

       -p --parasha      print week's parasha on each calendar row

       -s --shabbat      print Shabbat times and parshiot

       -l --latitude     [NS]yy[.yyy]  decimal  degrees,  or  [NS]yy[:mm[:ss]]
                         degrees, minutes, seconds. Negative values are South

       -L --longitude    [EW]xx[.xxx]  decimal  degrees,  or  [EW]xx[:mm[:ss]]
                         degrees, minutes, seconds. Negative values are West

       -z --timezone     +/-UTC.  Notation  may  be in decimal hours (hh[.hh])
                         or hours, minutes (hh[:mm])

          --prefer-hebrew     how to interpret ambiguous month and year
          --prefer-gregorian  parameters. (eg. interpret "6 10" as
                              "Adar 5710" or as "June 2010")

       Holidays are depicted by a change in the symbol separating a day's Gre‐
       gorian and Hebrew dates, as follows:

              /  Regular day
              +  Yom Tov (plus Yom Kippur)
              *  Erev Yom Kippur
              ~  Hol HaMoed
              !  Hanuka and Purim
              @  fasting day
              $  Lag BaOmer ,Tu BeAv, Tu BeShvat
              #  Independance day and Yom Yerushalaim
              %  Tzahal and Holocaust memorial days
              ^  Other Israeli National days

       Use  the -f (--footnote) option to have hcal describe what any particu‐
       lar day is marking.

       If you want  hcal  to  display  accurate  time-of-day  information,hcal
       requires location and time zone information in order to make astronomi‐
       cal calculations for a given date. If you don't provide ANY such infor‐
       mation, hcal tries to find out your computer's local time zone informa‐
       tion as an indicator, and picks the 'primary' city in that  time  zone.
       If  hcal can't find local time zone information, hcal tries to find out
       your computer's GMT offset, and either picks from the  list  below  the
       city in that time zone offset, or defaults to the equator at the center
       of that time zone offset. If hcal can't even retrieve GMT offset infor‐
       mation  from  your  computer,  it defaults to Tel-Aviv. For other loca‐
       tions, use the -l -L option pair.  For  other  timezones,  use  the  -z
       option.  Co-ordinates and standard time zones for some common locations
       are listed below.

       The current defaults are:
            tz                 Lat    Lon      tz              Lat     Lon
            -8   Los Angeles   34.05 -118.25    2    Tel-Aviv  32      34.75
            -6   Mexico City   19.43  -99.13    3.5  Tehran    35.67   51.43
            -5   New York City 40.75  -74       4    Moscow    55.75   37.62
            -4.5 Caracas       10.54  -66.93    5    Tashkent  41.27   69.22
            -3   Buenos Aires -34.61  -58.37    5.5  Calcutta  22.57   88.36
             0   London        51.5     0       8    Beijing   39.90  116.38
             1   Paris         48.86    2.34   10    Sydney   -33.87  151.21

       Useful locations and time zones
             tz                 Lat    Lon      tz              Lat     Lon
             2   Jerusalem     31.78   35.22    8   Hong Kong  22.26  114.15
             2   Haifa         32.82   34.99   -6   Chicago    41.84  -87.67
             2   Beer Sheva    31.25   34.80   -3   Sao Paolo -23.52  -46.63
             2   Ashdod        31.80   34.64   -5   Toronto    43.75  -79.38
             2   Tiberias      40.89   35.84    1   Antwerpen  51.22    4.42
             2   Eilat         29.56   34.95    3.5 Tehran     35.67   51.42

       The config files and their parent folder will be automatically created.
       Each file includes its own documentation, in-line. Should you ever wish
       to restore a config file to its original text, rename  or  delete  your
       current  one;  hcal will create a replacement automatically on its next
       invocation. Both hcal and hcal make use of identically  formatted  cus‐
       tom_days files, so you may freely copy that file from one config folder
       to the other, or use a symbolic link so both programs will  always  use
       the same custom_days information.



       If ${XDG_CONFIG_HOME} is undefined:



       Accuracy  The  accuracy  of the astronomically-derived data will suffer
                 from not accounting for environmental conditions such as ele‐
                 vation, horizon, temperature and air pressure.

       Timezones The timezone support is currenlty primitive and lacks support
                 for daylight savings time transitions.

                 The software does not yet account for the phenomenon and com‐
                 plications  of  the  "Gregorian  transition"  from the prior,
                 Julian calendar, which effectively  caused  an  instantaneous
                 'loss' of two weeks for all gentiles affected. Countries (eg.
                 Poland, Spain and Italy) began adopting the Gregorian  calen‐
                 dar  on 8 Tishrei 5343 (4 October 1582 CE), although many did
                 not transition until  the  56th  century  (1752  CE,  eg.  UK
                 colonies,  Sweden). Russia did not adopt the Gregorian calen‐
                 dar until 5678 (1918  CE)  and  Turkey  did  not  until  5687
                 (December, 1926 CE). Many other countries made the transition
                 on other dates. Keep in mind  that  Russia  invaded  part  of
                 Poland,  undoing,  for  the interim, the Gregorian transition
                 for (only) that part of Poland; Also important to remember in
                 this  regard  is  that  Eretz  Ysroel was part of the Turkish
                 Ottoman empire until the British mandate  (5677  (1917  CE)).
                 Until  all  this is accounted for adequately by this applica‐
                 tion, refer to 'ncal -p' for a basic table of country transi‐
                 tions.  However, keep in mind that European borders underwent
                 many changes during the 426 years in question, so  the  accu‐
                 racy  of  your  data  will  depend  on  accurate knowledge of
                 whether any particular date  at  any  specific  location  was
                 Julian or Gregorian.

   Not a bug
       Invoke  hcal  with  a  gregorian  month  name, and hcal will by default
       return a single month calendar for the Hebrew month in which that  gre‐
       gorian  month  begins.  For example, 'hcal feb' could return a calendar
       for Shevat of the current year. In order to see a Hebrew  calendar  for
       February, add option -gg on the command line or in your config file.

       1. Display a 2012ce year's calendar, three-months wide, in color.
             hcal -3c 2012

       2.  Display the current month's calendar, with Shabbat times, parshiot,
          footnoted holiday identification, with Hebrew information in Hebrew,
          and all in "calming", "muted" color-tones.
             hcal -csfH

   Flexible date entry
       hdate  April ; hdate aPril; hdate tiSHREi; hdate 1 Elul 44; hdate 1 sep
       1944; hdate 44 oct 21

   Flexible Hebrew month transliterations
       tIchriy, jechvan, xeshvan, khechvan, kisayv, teivayt,  sh\'vat,  addar,
       adarI, "adar A", adar_2, adar-alef, adaraleph, adARBeth, nissan, eeyar,
       ceevvan, taMUz, aV, elloul (and many more).

       mlterm(1), hdate(1) ,hebcal(1), date(1), ncal(1), cal(1), remind(1)

       Boruch Baum 2011-2013, Yaacov Zamir 2005-2010.

       project home page: http://libhdate.sourceforge.net

       hcal and hdate are part of the package libhdate, a small C/C++  library
       for  Hebrew dates, holidays, and reading sequences (parashiot). It uses
       the source code from  Amos  Shapir's  "hdate"  package,  as  fixed  and
       patched  by  Nadav  Har'El. The Torah reading sequence tables were con‐
       tributed by Zvi Har'El.

Linux                             2013-01-01                           hcal(1)