usr.bin/calendar/calendar.1

   1 .\" Copyright (c) 1989, 1990, 1993
   2 .\"     The Regents of the University of California.  All rights reserved.
   3 .\"
   4 .\" Redistribution and use in source and binary forms, with or without
   5 .\" modification, are permitted provided that the following conditions
   6 .\" are met:
   7 .\" 1. Redistributions of source code must retain the above copyright
   8 .\"    notice, this list of conditions and the following disclaimer.
   9 .\" 2. Redistributions in binary form must reproduce the above copyright
  10 .\"    notice, this list of conditions and the following disclaimer in the
  11 .\"    documentation and/or other materials provided with the distribution.
  12 .\" 4. Neither the name of the University nor the names of its contributors
  13 .\"    may be used to endorse or promote products derived from this software
  14 .\"    without specific prior written permission.
  15 .\"
  16 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
  17 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  18 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  19 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
  20 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  21 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  22 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  23 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  24 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  25 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  26 .\" SUCH DAMAGE.
  27 .\"
  28 .\"     @(#)calendar.1  8.1 (Berkeley) 6/29/93
  29 .\" $FreeBSD$
  30 .\"
  31 .Dd June 13, 2002
  32 .Dt CALENDAR 1
  33 .Os
  34 .Sh NAME
  35 .Nm calendar
  36 .Nd reminder service
  37 .Sh SYNOPSIS
  38 .Nm
  39 .Op Fl a
  40 .Op Fl A Ar num
  41 .Op Fl B Ar num
  42 .Op Fl F Ar friday
  43 .Op Fl f Ar calendarfile
  44 .Oo
  45 .Bk -words
  46 .Fl t Ar dd Ns
  47 .Sm off
  48 .Op . Ar mm Op . Ar year
  49 .Sm on
  50 .Ek
  51 .Oc
  52 .Op Fl W Ar num
  53 .Op Fl U Ar UTC-offset
  54 .Op Fl l Ar longitude
  55 .Sh DESCRIPTION
  56 The
  57 .Nm
  58 utility checks the current directory for a file named
  59 .Pa calendar
  60 and displays lines that begin with either today's date
  61 or tomorrow's.
  62 On the day before a weekend (normally Friday), events for the next
  63 three days are displayed.
  64 .Pp
  65 The following options are available:
  66 .Bl -tag -width Ds
  67 .It Fl A Ar num
  68 Print lines from today and the next
  69 .Ar num
  70 days (forward, future).
  71 .It Fl a
  72 Process the ``calendar'' files of all users and mail the results
  73 to them.
  74 This requires super-user privileges.
  75 .It Fl B Ar num
  76 Print lines from today and the previous
  77 .Ar num
  78 days (backward, past).
  79 .It Fl F Ar friday
  80 Specify which day of the week is ``Friday'' (the day before the
  81 weekend begins).
  82 Default is 5.
  83 .It Fl f Pa calendarfile
  84 Use
  85 .Pa calendarfile
  86 as the default calendar file.
  87 .It Xo Fl t
  88 .Sm off
  89 .Ar dd
  90 .Op . Ar mm Op . Ar year
  91 .Sm on
  92 .Xc
  93 For test purposes only: set date directly to argument values.
  94 .It Fl l Ar longitude , Fl U Ar UTC-offset
  95 Only one is needed:
  96 Perform lunar and solar calculations from this longitude or from
  97 this UTC offset.
  98 If neither is specified, the calculations will be based on the
  99 difference between UTC time and localtime.
 100 .It Fl W Ar num
 101 Print lines from today and the next
 102 .Ar num
 103 days (forward, future).
 104 Ignore weekends when calculating the number of days.
 105 .El
 106 .Sh FILE FORMAT
 107 .Pp
 108 To handle calendars in your national code table you can specify
 109 .Dq LANG=<locale_name>
 110 in the calendar file as early as possible.
 111 .Pp
 112 To handle the local name of sequences, you can specify them as:
 113 .Dq SEQUENCE=<first> <second> <third> <fourth> <fifth> <last>
 114 in the calendar file as early as possible.
 115 .Pp
 116 The names of the following special days are recognized:
 117 .Bl -tag -width 123456789012345 -compact
 118 .It Easter
 119 Catholic Easter.
 120 .It Paskha
 121 Orthodox Easter.
 122 .It NewMoon
 123 The lunar New Moon.
 124 .It FullMoon
 125 The lunar Full Moon.
 126 .It MarEquinox
 127 The solar equinox in March.
 128 .It JunSolstice
 129 The solar solstice in June.
 130 .It SepEquinox
 131 The solar equinox in September.
 132 .It DecSolstice
 133 The solar solstice in December.
 134 .It ChineseNewYear
 135 The first day of the Chinese year.
 136 .El
 137 These names may be reassigned to their local names via an assignment
 138 like
 139 .Dq Easter=Pasen
 140 in the calendar file.
 141 .Pp
 142 Other lines should begin with a month and day.
 143 They may be entered in almost any format, either numeric or as character
 144 strings.
 145 If the proper locale is set, national month and weekday
 146 names can be used.
 147 A single asterisk (``*'') matches every month.
 148 A day without a month matches that day of every week.
 149 A month without a day matches the first of that month.
 150 Two numbers default to the month followed by the day.
 151 Lines with leading tabs default to the last entered date, allowing
 152 multiple line specifications for a single date.
 153 .Pp
 154 The names of the recognized special days may be followed by a
 155 positive or negative integer, like:
 156 .Dq Easter+3
 157 or
 158 .Dq Paskha-4 .
 159 .Pp
 160 Weekdays may be followed by ``-4'' ...\& ``+5'' (aliases for
 161 last, first, second, third, fourth) for moving events like
 162 ``the last Monday in April''.
 163 .Pp
 164 By convention, dates followed by an asterisk are not fixed, i.e., change
 165 from year to year.
 166 .Pp
 167 Day descriptions start after the first <tab> character in the line;
 168 if the line does not contain a <tab> character, it is not displayed.
 169 If the first character in the line is a <tab> character, it is treated as
 170 a continuation of the previous line.
 171 .Pp
 172 The ``calendar'' file is preprocessed by
 173 .Xr cpp 1 ,
 174 allowing the inclusion of shared files such as lists of company holidays or
 175 meetings.
 176 If the shared file is not referenced by a full pathname,
 177 .Xr cpp 1
 178 searches in the current (or home) directory first, and then in the
 179 directory
 180 .Pa /usr/share/calendar .
 181 Empty lines and lines protected by the C commenting syntax
 182 .Pq Li /* ... */
 183 are ignored.
 184 .Pp
 185 Some possible calendar entries (<tab> characters highlighted by
 186 \fB\et\fR sequence)
 187 .Bd -unfilled -offset indent
 188 LANG=C
 189 Easter=Ostern
 190
 191 #include <calendar.usholiday>
 192 #include <calendar.birthday>
 193
 194 6/15\fB\et\fRJune 15 (if ambiguous, will default to month/day).
 195 Jun. 15\fB\et\fRJune 15.
 196 15 June\fB\et\fRJune 15.
 197 Thursday\fB\et\fREvery Thursday.
 198 June\fB\et\fREvery June 1st.
 199 15 *\fB\et\fR15th of every month.
 200 2010/4/15\fB\et\fR15 April 2010
 201
 202 May Sun+2\fB\et\fRsecond Sunday in May (Muttertag)
 203 04/SunLast\fB\et\fRlast Sunday in April,
 204 \fB\et\fRsummer time in Europe
 205 Easter\fB\et\fREaster
 206 Ostern-2\fB\et\fRGood Friday (2 days before Easter)
 207 Paskha\fB\et\fROrthodox Easter
 208
 209 .Ed
 210 .Sh FILES
 211 .Bl -tag -width calendar.christian -compact
 212 .It Pa calendar
 213 file in current directory
 214 .It Pa ~/.calendar
 215 .Pa calendar
 216 HOME directory.
 217 A chdir is done into this directory if it exists.
 218 .It Pa ~/.calendar/calendar
 219 calendar file to use if no calendar file exists in the current directory.
 220 .It Pa ~/.calendar/nomail
 221 do not send mail if this file exists.
 222 .El
 223 .Pp
 224 The following default calendar files are provided in
 225 .Pa /usr/share/calendars:
 226 .Pp
 227 .Bl -tag -width calendar.southafrica -compact
 228 .It Pa calendar.all
 229 File which includes all the default files.
 230 .It Pa calendar.australia
 231 Calendar of events in Australia.
 232 .It Pa calendar.birthday
 233 Births and deaths of famous (and not-so-famous) people.
 234 .It Pa calendar.christian
 235 Christian holidays.
 236 This calendar should be updated yearly by the local system administrator
 237 so that roving holidays are set correctly for the current year.
 238 .It Pa calendar.computer
 239 Days of special significance to computer people.
 240 .It Pa calendar.croatian
 241 Calendar of events in Croatia.
 242 .It Pa calendar.dutch
 243 Calendar of events in the Netherlands.
 244 .It Pa calendar.freebsd
 245 Birthdays of
 246 .Fx
 247 committers.
 248 .It Pa calendar.french
 249 Calendar of events in France.
 250 .It Pa calendar.german
 251 Calendar of events in Germany.
 252 .It Pa calendar.history
 253 Everything else, mostly U.S.\& historical events.
 254 .It Pa calendar.holiday
 255 Other holidays, including the not-well-known, obscure, and
 256 .Em really
 257 obscure.
 258 .It Pa calendar.judaic
 259 Jewish holidays.
 260 The entries for this calendar have been obtained from the port
 261 deskutils/hebcal.
 262 .It Pa calendar.music
 263 Musical events, births, and deaths.
 264 Strongly oriented toward rock 'n' roll.
 265 .It Pa calendar.newzealand
 266 Calendar of events in New Zealand.
 267 .It Pa calendar.russian
 268 Russian calendar.
 269 .It Pa calendar.southafrica
 270 Calendar of events in South Africa.
 271 .It Pa calendar.usholiday
 272 U.S.\& holidays.
 273 This calendar should be updated yearly by the local system administrator
 274 so that roving holidays are set correctly for the current year.
 275 .It Pa calendar.world
 276 Includes all calendar files except for national files.
 277 .El
 278 .Sh COMPATIBILITY
 279 The
 280 .Nm
 281 program previously selected lines which had the correct date anywhere
 282 in the line.
 283 This is no longer true, the date is only recognized when it occurs
 284 at the beginning of a line.
 285 .Sh SEE ALSO
 286 .Xr at 1 ,
 287 .Xr cpp 1 ,
 288 .Xr mail 1 ,
 289 .Xr cron 8
 290 .Sh HISTORY
 291 A
 292 .Nm
 293 command appeared in
 294 .At v7 .
 295 .Sh NOTES
 296 Chinese New Year is calculated at 120 degrees east of Greenwich,
 297 which roughly corresponds with the east coast of China.
 298 For people west of China, this might result that the start of Chinese
 299 New Year and the day of the related new moon might differ.
 300 .Pp
 301 The phases of the moon and the longitude of the sun are calculated
 302 against the local position which corresponds with 30 degrees times
 303 the time-difference towards Greenwich.
 304 .Pp
 305 The new and full moons are happening on the day indicated: They
 306 might happen in the time period in the early night or in the late
 307 evening.
 308 It doesn't indicate that they are starting in the night on that date.
 309 .Pp
 310 Because of minor differences between the output of the formulas
 311 used and other sources on the Internet, Druids and Werewolves should
 312 double-check the start and end time of solar and lunar events.
 313 .Sh BUGS
 314 The
 315 .Nm
 316 utility does not handle Jewish holidays.
 317 .Pp
 318 There is no possibility to properly specify the local position
 319 needed for solar and lunar calculations.