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 April 6, 2013
  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 Ar num
  40 .Op Fl a
  41 .Op Fl B Ar num
  42 .Op Fl D Ar moon|sun
  43 .Op Fl d
  44 .Op Fl F Ar friday
  45 .Op Fl f Ar calendarfile
  46 .Op Fl l Ar longitude
  47 .Oo
  48 .Bk -words
  49 .Fl t Ar dd Ns
  50 .Sm off
  51 .Op . Ar mm Op . Ar year
  52 .Sm on
  53 .Ek
  54 .Oc
  55 .Op Fl U Ar UTC-offset
  56 .Op Fl W Ar num
  57 .Sh DESCRIPTION
  58 The
  59 .Nm
  60 utility checks the current directory for a file named
  61 .Pa calendar
  62 and displays lines that fall into the specified date range.
  63 On the day before a weekend (normally Friday), events for the next
  64 three days are displayed.
  65 .Pp
  66 The following options are available:
  67 .Bl -tag -width Ds
  68 .It Fl A Ar num
  69 Print lines from today and the next
  70 .Ar num
  71 days (forward, future).
  72 .It Fl a
  73 Process the ``calendar'' files of all users and mail the results
  74 to them.
  75 This requires super-user privileges.
  76 .It Fl B Ar num
  77 Print lines from today and the previous
  78 .Ar num
  79 days (backward, past).
  80 .It Fl D Ar moon|sun
  81 Print UTC offset, longitude and moon or sun information.
  82 .It Fl d
  83 Debug option: print current date information.
  84 .It Fl F Ar friday
  85 Specify which day of the week is ``Friday'' (the day before the
  86 weekend begins).
  87 Default is 5.
  88 .It Fl f Pa calendarfile
  89 Use
  90 .Pa calendarfile
  91 as the default calendar file.
  92 .It Fl l Ar longitude
  93 Perform lunar and solar calculations from this longitude.
  94 If neither longitude nor UTC offset is specified, the calculations will
  95 be based on the difference between UTC time and localtime.
  96 If both are specified, UTC offset overrides longitude.
  97 .It Xo Fl t
  98 .Sm off
  99 .Ar dd
 100 .Op . Ar mm Op . Ar year
 101 .Sm on
 102 .Xc
 103 For test purposes only: set date directly to argument values.
 104 .It Fl U Ar UTC-offset
 105 Perform lunar and solar calculations from this UTC offset.
 106 If neither UTC offset nor longitude is specified, the calculations
 107 will be based on the difference between UTC time and localtime.
 108 If both are specified, UTC offset overrides longitude.
 109 .It Fl W Ar num
 110 Print lines from today and the next
 111 .Ar num
 112 days (forward, future).
 113 Ignore weekends when calculating the number of days.
 114 .El
 115 .Sh FILE FORMAT
 116 To handle calendars in your national code table you can specify
 117 .Dq LANG=<locale_name>
 118 in the calendar file as early as possible.
 119 .Pp
 120 To handle the local name of sequences, you can specify them as:
 121 .Dq SEQUENCE=<first> <second> <third> <fourth> <fifth> <last>
 122 in the calendar file as early as possible.
 123 .Pp
 124 The names of the following special days are recognized:
 125 .Bl -tag -width 123456789012345 -compact
 126 .It Easter
 127 Catholic Easter.
 128 .It Paskha
 129 Orthodox Easter.
 130 .It NewMoon
 131 The lunar New Moon.
 132 .It FullMoon
 133 The lunar Full Moon.
 134 .It MarEquinox
 135 The solar equinox in March.
 136 .It JunSolstice
 137 The solar solstice in June.
 138 .It SepEquinox
 139 The solar equinox in September.
 140 .It DecSolstice
 141 The solar solstice in December.
 142 .It ChineseNewYear
 143 The first day of the Chinese year.
 144 .El
 145 These names may be reassigned to their local names via an assignment
 146 like
 147 .Dq Easter=Pasen
 148 in the calendar file.
 149 .Pp
 150 Other lines should begin with a month and day.
 151 They may be entered in almost any format, either numeric or as character
 152 strings.
 153 If the proper locale is set, national month and weekday
 154 names can be used.
 155 A single asterisk (``*'') matches every month.
 156 A day without a month matches that day of every week.
 157 A month without a day matches the first of that month.
 158 Two numbers default to the month followed by the day.
 159 Lines with leading tabs default to the last entered date, allowing
 160 multiple line specifications for a single date.
 161 .Pp
 162 The names of the recognized special days may be followed by a
 163 positive or negative integer, like:
 164 .Dq Easter+3
 165 or
 166 .Dq Paskha-4 .
 167 .Pp
 168 Weekdays may be followed by ``-4'' ...\& ``+5'' (aliases for
 169 last, first, second, third, fourth) for moving events like
 170 ``the last Monday in April''.
 171 .Pp
 172 By convention, dates followed by an asterisk are not fixed, i.e., change
 173 from year to year.
 174 .Pp
 175 Day descriptions start after the first <tab> character in the line;
 176 if the line does not contain a <tab> character, it is not displayed.
 177 If the first character in the line is a <tab> character, it is treated as
 178 a continuation of the previous line.
 179 .Pp
 180 The
 181 .Nm
 182 file is preprocessed by a limited subset of
 183 .Xr cpp 1
 184 internally, allowing the inclusion of shared files such as
 185 lists of company holidays or meetings.
 186 This limited subset consists of \fB#include #ifndef #endif\fR and \fB#define\fR.
 187 If the shared file is not referenced by a full pathname,
 188 .Xr calendar 1
 189 searches in the current (or home) directory first, and then in the
 190 directory
 191 .Pa /usr/share/calendar .
 192 Empty lines and lines protected by the C commenting syntax
 193 .Pq Li /* ... */
 194 are ignored.
 195 .Pp
 196 Some possible calendar entries (<tab> characters highlighted by
 197 \fB\et\fR sequence)
 198 .Bd -unfilled -offset indent
 199 LANG=C
 200 Easter=Ostern
 201
 202 #include <calendar.usholiday>
 203 #include <calendar.birthday>
 204
 205 6/15\fB\et\fRJune 15 (if ambiguous, will default to month/day).
 206 Jun. 15\fB\et\fRJune 15.
 207 15 June\fB\et\fRJune 15.
 208 Thursday\fB\et\fREvery Thursday.
 209 June\fB\et\fREvery June 1st.
 210 15 *\fB\et\fR15th of every month.
 211 2010/4/15\fB\et\fR15 April 2010
 212
 213 May Sun+2\fB\et\fRsecond Sunday in May (Muttertag)
 214 04/SunLast\fB\et\fRlast Sunday in April,
 215 \fB\et\fRsummer time in Europe
 216 Easter\fB\et\fREaster
 217 Ostern-2\fB\et\fRGood Friday (2 days before Easter)
 218 Paskha\fB\et\fROrthodox Easter
 219
 220 .Ed
 221 .Sh FILES
 222 .Bl -tag -width calendar.christian -compact
 223 .It Pa calendar
 224 file in current directory.
 225 .It Pa ~/.calendar
 226 .Pa calendar
 227 HOME directory.
 228 A chdir is done into this directory if it exists.
 229 .It Pa ~/.calendar/calendar
 230 calendar file to use if no calendar file exists in the current directory.
 231 .It Pa ~/.calendar/nomail
 232 do not send mail if this file exists.
 233 .El
 234 .Pp
 235 The following default calendar files are provided in
 236 .Pa /usr/share/calendar:
 237 .Pp
 238 .Bl -tag -width calendar.southafrica -compact
 239 .It Pa calendar.all
 240 File which includes all the default files.
 241 .It Pa calendar.australia
 242 Calendar of events in Australia.
 243 .It Pa calendar.birthday
 244 Births and deaths of famous (and not-so-famous) people.
 245 .It Pa calendar.christian
 246 Christian holidays.
 247 This calendar should be updated yearly by the local system administrator
 248 so that roving holidays are set correctly for the current year.
 249 .It Pa calendar.computer
 250 Days of special significance to computer people.
 251 .It Pa calendar.croatian
 252 Calendar of events in Croatia.
 253 .It Pa calendar.dutch
 254 Calendar of events in the Netherlands.
 255 .It Pa calendar.freebsd
 256 Birthdays of
 257 .Fx
 258 committers.
 259 .It Pa calendar.french
 260 Calendar of events in France.
 261 .It Pa calendar.german
 262 Calendar of events in Germany.
 263 .It Pa calendar.history
 264 Everything else, mostly U.S.\& historical events.
 265 .It Pa calendar.holiday
 266 Other holidays, including the not-well-known, obscure, and
 267 .Em really
 268 obscure.
 269 .It Pa calendar.judaic
 270 Jewish holidays.
 271 The entries for this calendar have been obtained from the port
 272 deskutils/hebcal.
 273 .It Pa calendar.music
 274 Musical events, births, and deaths.
 275 Strongly oriented toward rock 'n' roll.
 276 .It Pa calendar.newzealand
 277 Calendar of events in New Zealand.
 278 .It Pa calendar.russian
 279 Russian calendar.
 280 .It Pa calendar.southafrica
 281 Calendar of events in South Africa.
 282 .It Pa calendar.usholiday
 283 U.S.\& holidays.
 284 This calendar should be updated yearly by the local system administrator
 285 so that roving holidays are set correctly for the current year.
 286 .It Pa calendar.world
 287 Includes all calendar files except for national files.
 288 .El
 289 .Sh COMPATIBILITY
 290 The
 291 .Nm
 292 program previously selected lines which had the correct date anywhere
 293 in the line.
 294 This is no longer true, the date is only recognized when it occurs
 295 at the beginning of a line.
 296 .Sh SEE ALSO
 297 .Xr at 1 ,
 298 .Xr cpp 1 ,
 299 .Xr mail 1 ,
 300 .Xr cron 8
 301 .Sh HISTORY
 302 A
 303 .Nm
 304 command appeared in
 305 .At v7 .
 306 .Sh NOTES
 307 Chinese New Year is calculated at 120 degrees east of Greenwich,
 308 which roughly corresponds with the east coast of China.
 309 For people west of China, this might result that the start of Chinese
 310 New Year and the day of the related new moon might differ.
 311 .Pp
 312 The phases of the moon and the longitude of the sun are calculated
 313 against the local position which corresponds with 30 degrees times
 314 the time-difference towards Greenwich.
 315 .Pp
 316 The new and full moons are happening on the day indicated: They
 317 might happen in the time period in the early night or in the late
 318 evening.
 319 It does not indicate that they are starting in the night on that date.
 320 .Pp
 321 Because of minor differences between the output of the formulas
 322 used and other sources on the Internet, Druids and Werewolves should
 323 double-check the start and end time of solar and lunar events.
 324 .Sh BUGS
 325 The
 326 .Nm
 327 internal cpp does not correctly do #ifndef and will discard the rest
 328 of the file if a #ifndef is triggered.
 329 It also has a maximum of 50 include file and/or 100 #defines
 330 and only recognises #include, #define and
 331 #ifndef.
 332 .Pp
 333 There is no possibility to properly specify the local position
 334 needed for solar and lunar calculations.