hdate man page (v1.8)

Boruch Baum

hdate 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.

hdate(1)                    libhdate documentation                    hdate(1)

NAME
       hdate - displays  Hebrew  date information for a given Gregorian/Julian
               date

SYNOPSIS
       hdate [options] [coordinates] [timezone] [datespec]

       hdate [options] [coordinates] [timezone] [julian_day|time_t]

       coordinates -l [N|S]yy[.yyy]     -L [E|W]xx[.xxx]
                   -l [N|S]yy[:mm[:ss]] -L [E|W]xx[:mm[:ss]]
       timezone:   -z nn[(.nn|:mm)]
                   -z [timezone_name] (see below)
       datespec:   see section ACCEPTABLE DATE FORMATS

DESCRIPTION
       hdate provides the date according to the Hebrew  calendar,  that  day's
       corresponding  date according to the gregorian calendar, and optionally
       providess further information about that Hebrew date,  including  holi‐
       days  and  astronomical-related  times  (see  section LOCATIONS). If no
       arguments are given, hdate provides information for the  current  date.
       If  a  single numeric argument is given, hdate interprets it as a year,
       and provides the requested information for all days of  that  year.  If
       two  arguments are given, hdate interprets them  as a month and a year,
       and provides the requested information for all days of that month.

       INPUTTING A HEBREW DATE: hdate interprets year values greater than 3000
       as  Hebrew  dates.  Numeric  Hebrew  months are interpreted as 1-12 for
       Tishrei - Elul; 13 and 14 for Adar I and Adar II. Currently, the  maxi‐
       mum value hdate accepts for a Hebrew year is 6999.

       INPUTTING  A  GREGORIAN DATE: hdate interprets year values in the range
       1000 - 2999 as either gregorian, or (see section BUGS, subsection  His‐
       torical)  julian.  Numeric months are interpreted as 1-12 for January -
       December.

       INPUTTING A JULIAN DAY: If a single numeric argument is  provided,  and
       that argument is in the range 1443377 <= n <= 2904342, hdate interprets
       it as a "julian day number" and provides information  for  that  Julian
       day's corresponding Hebrew date. See section JULIAN DAY.

       INPUTTING AN EPOCH DATE: hdate interprets a number preceded by a '@' as
       a time_t value, representing the number of seconds  elapsed  since  the
       Epoch,  1970-01-01  00:00:00  +0000  (UTC).  A second way to provide an
       epoch date value is as a parameter to the -E (--epoch) option,  without
       the leading '@'.

       ACCEPTABLE  DATE  FORMATS:  Prior  versions  of  hdate  insisted on the
       numeric date format [[yyyy [mm  [dd]]].  hdate now accepts numeric date
       elements  in  any  easily  discernable  order. hdate now accepts Hebrew
       month names and gregorian month names in both full and abbreviated for‐
       mats,  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).  hdate  will  intelligently  interpret
       ambiguous  numeric  datespec  parameters. For example, a parameter "32"
       could only legitimately be a two-digit year, so hdate will, by default,
       interpret  it  as a two-digit Hebrew year in the current (58th) century
       (see option --prefer-gregorian, section CONFIG FILES,  and  the  config
       file options to change the default base years).

OPTIONS
       -b --bidi         output Hebrew information in Hebrew, but in reverse
          --visual       sequence.

       -d --diaspora     force diaspora readings and holidays.
          --israel       force Eretz Yisroel readings an holidays.

          --daf-yomi

       -e --emesh        begin printing times-of-day at sunset or candle
          --erev         lighting. This is the default.
          --no-emesh
          --no-erev

       -E --epoch        print times of day in epoch format, ie. the number of
                         seconds elapsed since the Epoch, 1970-01-01  00:00:00
                         +0000  (UTC).  This option will also cause --sun-hour
                         to display in seconds instead of hh:mm:ss.

       -E --epoch time_t get information for this epoch date, instead  of  for
                         datespec.

       -h --holidays     print  holiday  name  if  day is a holiday, and print
                         custom day name if day is marked as a custom day. See
                         section HOLIDAYS AND CUSTOM DAYS.

       -H                print  only  if day is a holiday or a custom day, and
                         print the name of that holiday or custom day.

       -i --ical         use iCal formatted output.

       -j --julian       print Julian day number.

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

       -o --omer         print Sefirat Ha Omer, number of days only.
                         -oo 'today is n days in the omer'
                         -ooo the full text, with weeks and remainder days
          --ba-omer      full omer text, as -ooo, in Hebrew
          --la-omer      full omer text, as -ooo, in Hebrew

       -q --quiet        suppress output, available in four levels:
          --quiet-alerts       -q    suppresses warning messages
          --quiet-gregorian    -qq   also suppresses the gregorian date
          --quiet-descriptions -qqq  also suppresses data labels
          --quiet-hebrew       -qqqq also suppresses the Hebrew date

       -r --parasha      print weekly reading if day is Shabbat.

       -R                print  only  if day is a Shabbat on which the regular
                         weekly reading is read (ie.  not  a  special  holiday
                         reading), and print that weekly reading.

          --sun          print sunrise and sunset times.
          --sunrise
          --sunset

       -s --shabbat-times
          --shabbat      print Shabbat start and end times.

          --candles-lighting [nn]
          --candle [nn]   (17<nn<91) default is 20 minutes before sunset.
          --havdalah [nn] (19<nn<91 minutes) default is 3 stars.

       -S --short-format print using short format.

       -t --times        print day times (three verbosity levels):
          --times-of-day -t    first light, talit, sunrise, mid day, sunset,
          --day-times          first stars, three stars,
                               and the length of that day's sun-hour.
                         -tt   adds end_Shema_(GR"A), end_amidah,
                               mincha_gedola, mincha_ketana, plag_hamincha.
                         -ttt  adds end_Shema_(M"A).
                         -tttt adds erev Pesach times

                         Instead   of   using  the  presets,  customize  with:
                         --first-light --midday        --shekia
                         --alot        --noon          --tzeit-hakochavim
                         --talit       --chatzot       --first-stars
                         --netz        --mincha-gedola --three-stars
                         --shema       --mincha-ketana --magen-avraham
                         --amidah      --plag-hamincha --sun-hour
                         --sunrise     --sunset

          --erev-pesach  if the day is 14 Nissan, print the following times:
                         --end-eating-chometz-ma   --end-eating-chometz-gra
                         --end-owning-chometz-ma   --end-owning-chometz-gra

       -T --table        print tabular output. All data for each requested day
          --tabular      will be output on a single comma-delimited line. Most
                         suitable for piping, or export to spreadsheets

       -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     either a timezone name  (see  section  TIMEZONES)  or
                         numeric  offset  +/-UTC.  Notation may  be in decimal
                         hours (hh[.hh]) or hours, minutes (hh[:mm])

          --hebrew       forces Hebrew to print in Hebrew characters

          --yom          force Hebrew prefix to Hebrew day of week

          --leshabbat    insert parasha between day of week and day

          --leseder      insert parasha between day of week and day

          --not-sunset-aware
                         don't display next day if after sunset

          --data-first   display data, followed by it's description

          --labels-first display data descriptions before the data itself

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

NOTES
   TIMEZONES
       hdate accepts as timezone parameters either an absolute numeric  offset
       from UTC, or an official timezone name, as found on many *nix operating
       systems at /usr/share/zoneinfo/zone.tab. These names are  typically  in
       the form 'continent/city' (eg. Asia/Jerusalem); however, hdate is flex‐
       ible and will accept any unique substring of a timezone name, and  will
       report how it interpreted your input. For example, 'jer' will be inter‐
       preted as Israel time. Names use underscores in place  of  spaces,  but
       hdate  will  accept spaces as long as the parameter is quoted ("w y" is
       acceptable for America/New_York, but so would be 'new'). When  given  a
       timezone name, hdate will be aware of daylight savings time transitions
       and will report times-of-day accordingly. When given no timezone infor‐
       mation,  hdate  will try to find out your computer's local timezone. If
       that fails, it will attempt to find your computer's UTC offset. If  all
       else fails, Jerusalem Standard time is used.

   LOCATIONS
       If  you  want  hdate to display accurate time-of-day information, hdate
       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, hdate tries to find out your computer's local time zone  infor‐
       mation as an indicator, and picks the 'primary' city in that time zone.
       If hdate can't find local time zone information, hdate  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 hdate can't even retrieve GMT off‐
       set information from your computer, it defaults to Tel-Aviv. For  other
       locations,  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

   HOLIDAYS AND CUSTOM DAYS
       By  default,  if  you ask hdate to display holiday names (options -h or
       --holidays),  hdate  uses  libhdate's  data  set  of  the   traditional
       'shulchan  aruch' Hebrew holidays. hdate also creates a user-modifiable
       config file, custom_days, for any other personal  or  national  days  a
       user might want to mark. The config file contains detailed in-line doc‐
       umentation, and allows for simple definitions of custom days by  either
       the  Hebrew or gregorian calendar; by either calendar day of a month or
       nth day of week of a month; and provides a simple method of  specifying
       how/whether  to  advance/postpone  a  custom day should it occur on any
       undesired day of week.

   JULIAN DAY
       The julian day system is not directly related to the  Julian  calendar.
       Rather,  it was introduced by astronomers for scientific use to provide
       a single system of dates that could be used when working with different
       calendars  and  to  unify different historical chronologies. Julian day
       number (JDN) zero corresponds to January 1, 4713  BCE  Greenwich  noon,
       according to the "julian proleptic calendar".

   TABULAR OUTPUT
       When invoked with option -T ( --table or --tabular ), hdate outputs the
       requested data for any single day in comma-delimited  format,  with  no
       intervening spaces. The only exception is that holidays and custom_days
       are delimited from each other with semi-colons, because  there  may  be
       more  than  one  of those entries for any given day. When invoked for a
       month (no dd supplied) or a year (no dd or dd supplied), data for sepa‐
       rate days are new-line-delimited. The first line of tabular output is a
       header line, describing each field being output, and delimited  in  the
       same  way  as  the  data line(s). Output of the header line can be sup‐
       pressed using option -qqq ( --quiet-descriptions ).

FILES
   CONFIG FILES
       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; hdate will create a replacement automatically on its next
       invocation. Both hdate 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.

            ${XDG_CONFIG_HOME}/hdate/hdaterc_v1.8

            ${XDG_CONFIG_HOME}/hdate/custom_days_v1.8

       If ${XDG_CONFIG_HOME} is undefined:

            ~/.config/hdate/hdaterc

            ~/.config/hdate/custom_days

BUGS
       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.

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

       Historical
                 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.

EXAMPLES
       1.  Display  data  for the entire month of Adar, with a candle-lighting
          custom of 29 minutes.
             hdate --candles=29 adar

       2. Create an iCal calendar of the holidays of year 2025.
             hdate -Hi 2025

       3. Print out the weekly readings and sunset/sunrise times for Eilat, on
          April 2031 CE.
             hdate -sR 4 2031 -l29.56 -L34.95 -z Jerusalem

   Flexible date entry
       tiSHREi ; yerech_haeitanim ; 1 Elul 44; 1 sep 1944; 44 oct 21 ; April ;
       aPril ; ziv ; bool ; Mar-Cheshvan ; menachemav

   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).

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

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

       project 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.

libhdate version 1.8              2013-01-01                          hdate(1)