usr.bin/calendar/calendar.1.in

   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 .\" 3. 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: head/usr.bin/calendar/calendar.1 314436 2017-02-28 23:42:47Z imp $
  30 .\"
  31 .Dd September 14, 2020
  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
  43 .Op Fl F Ar friday
  44 .Op Fl f Ar calendar_file
  45 .Op Fl H Ar calendar_home
  46 .Op Fl h
  47 .Op Fl L Ar latitude,longitude[,elevation]
  48 .Op Fl s Ar category
  49 .Op Fl T Ar hh:mm[:ss]
  50 .Op Fl t Ar [[[CC]YY]MM]DD
  51 .Op Fl U Ar \(+-hh[[:]mm]
  52 .Op Fl W Ar num
  53 .Sh DESCRIPTION
  54 The
  55 .Nm
  56 utility processes calendar files and displays lines that fall into the
  57 specified date range.
  58 On the day before a weekend (normally Friday), events for the next
  59 three days are displayed.
  60 .Pp
  61 The following options are available:
  62 .Bl -tag -width Ds
  63 .It Fl A Ar num
  64 Print lines from today and the next
  65 .Ar num
  66 days (forward, future).
  67 .It Fl a
  68 Process the calendar files
  69 .Pa ( ~/.calendar/calendar )
  70 of all users and mail the results to them.
  71 This requires super-user privileges.
  72 .It Fl B Ar num
  73 Print lines from today and the previous
  74 .Ar num
  75 days (backward, past).
  76 .It Fl d
  77 Print debug messages.
  78 This flag may be repeated multiple times to increase the verbosity.
  79 .It Fl F Ar friday
  80 Specify which day of the week is
  81 .Dq Friday
  82 (the day before the weekend begins).
  83 The default is 5.
  84 .It Fl f Pa calendar_file
  85 Use
  86 .Ar calendar_file
  87 as the default calendar file.
  88 If specified as
  89 .Pa - ,
  90 then read from standard input.
  91 Note that this flag cannot be used together with the
  92 .Fl a
  93 flag.
  94 .It Fl H Pa calendar_home
  95 Use
  96 .Ar calendar_home
  97 as the calendar home directory.
  98 Note that this flag cannot be used together with the
  99 .Fl a
 100 flag.
 101 .It Fl h
 102 Show the utility usage.
 103 .It Fl L Ar latitude,longitude[,elevation]
 104 Specify the location for use in some calculations, such as the current
 105 Sun and Moon positions and their rise and set times.
 106 The
 107 .Ar latitude
 108 and
 109 .Ar longitude
 110 arguments are given in units of degrees,
 111 which can be a decimal number or in the DMS format of
 112 .Dq [+-]d:m:s .
 113 The
 114 .Ar elevation
 115 argument is optional and is given in units of meters.
 116 If not specified, the
 117 .Ar latitude
 118 and
 119 .Ar elevation
 120 arguments are default to 0, while the
 121 .Ar longitude
 122 argument is calculated from the adopted UTC offset
 123 (i.e., 15 degrees times the UTC offset in hours).
 124 .It Fl s Ar category
 125 Show information of the specified
 126 .Ar category ,
 127 which can take the following values:
 128 .Pp
 129 .Bl -tag -width chinese -compact
 130 .It Cm chinese
 131 Show the Chinese calendar and the 24 solar terms (a.k.a. Jieqi) in this year.
 132 .It Cm julian
 133 Show the Julian calendar.
 134 .It Cm moon
 135 Show Moon position, phases, rise and set times, and lunar events in this year.
 136 .It Cm sun
 137 Show Sun position, rise and set times, and solar events in this year.
 138 .El
 139 .It Fl T Ar hh:mm[:ss]
 140 Specify the time of day to use instead of the current system time.
 141 This time is only used in determining the Sun and Moon information.
 142 .It Fl t Ar [[[CC]YY]MM]DD
 143 Act like the specified value is
 144 .Dq today
 145 instead of using the current date.
 146 If
 147 .Ar YY
 148 is specified, but
 149 .Ar CC
 150 is not,
 151 a value for
 152 .Ar YY
 153 between 69 and 99 results in a
 154 .Ar CC
 155 value of 19.
 156 Otherwise, a
 157 .Ar CC
 158 value of 20 is used.
 159 .It Fl U Ar \(+-hh[[:]mm]
 160 Specify the timezone with a UTC offset.
 161 If not specified, the timezone of localtime is used.
 162 .It Fl W Ar num
 163 Print lines from today and the next
 164 .Ar num
 165 days (forward, future).
 166 Similar to the
 167 .Fl A
 168 option but ignore weekends when calculating the number of days.
 169 .El
 170 .Sh FILE FORMAT
 171 The calendar files are preprocessed by a limited subset of
 172 .Xr cpp 1
 173 internally, allowing the inclusion of shared calendar files.
 174 This limited directive subset consists of
 175 .Sy #include ,
 176 .Sy #ifndef ,
 177 .Sy #endif ,
 178 and
 179 .Sy #define .
 180 If the calendar file to be included (via the
 181 .Sy #include
 182 directive) is not referenced by a full pathname,
 183 .Nm
 184 searches in its home directory
 185 .Pa ( ~/.calendar
 186 or specified by the
 187 .Fl H
 188 flag)
 189 first, then in the
 190 .Pa @@CALENDAR_ETCDIR@@
 191 directory, and finally in the
 192 .Pa @@CALENDAR_DIR@@
 193 directory.
 194 Both the C-style comment
 195 .Pq Li /* ... */
 196 and C++-style comment
 197 .Pq Li // ...
 198 are supported.
 199 .Pp
 200 The default calendar used by the
 201 .Nm
 202 utility is the
 203 .Dq Gregorian calendar .
 204 In addition, the following calendars are supported:
 205 .Bl -tag -offset indent -width chinese -compact
 206 .It Julian
 207 The Julian calendar
 208 .It Chinese
 209 The Chinese calendar
 210 .El
 211 Specify
 212 .Dq CALENDAR=<calendar>
 213 in the calendar file to select the calendar to use.
 214 The calendar will be reset to the default Gregorian calendar
 215 at the end of the calendar file.
 216 When a non-default calendar is selected, the matched events will
 217 be printed with a secondary date formatted in the selected calendar.
 218 .Pp
 219 To handle calendars in national code table, specify
 220 .Dq LANG=<locale>
 221 in the calendar file, before the national names being used.
 222 This setting will also make the event date in this calendar file
 223 be formatted in national names in the output.
 224 The locale change will be reset at the end of the calendar file.
 225 .Pp
 226 To handle the local name of sequences, specify them as
 227 .Dq SEQUENCE=<first> <second> <third> <fourth> <fifth> <last>
 228 in the calendar file.
 229 .Pp
 230 The names of the following special days are recognized:
 231 .Bl -tag -offset indent -width 1234567890123456 -compact
 232 .It Easter
 233 Catholic Easter.
 234 .It Paskha
 235 Orthodox Easter.
 236 .It Advent
 237 First Sunday of Advent.
 238 .It NewMoon
 239 The lunar New Moon.
 240 .It FullMoon
 241 The lunar Full Moon.
 242 .It MarEquinox
 243 The solar equinox in March.
 244 .It JunSolstice
 245 The solar solstice in June.
 246 .It SepEquinox
 247 The solar equinox in September.
 248 .It DecSolstice
 249 The solar solstice in December.
 250 .It ChineseNewYear
 251 The first day of the Chinese year.
 252 .It ChineseQingming
 253 The Chinese Qingming festival (a.k.a. Tomb-Sweeping Day).
 254 .It ChineseJieqi
 255 The 24 solar terms (Jieqi) in Chinese calendar.
 256 .El
 257 These names may be reassigned to their local names via an assignment
 258 like
 259 .Dq <name>=<local_name>
 260 in the calendar file, and then the
 261 .Dq <local_name>
 262 can also be used to specify the date.
 263 .Pp
 264 Other lines should begin with a year (optional), month and day.
 265 They may be entered in multiple formats, either numeric or as
 266 character strings.
 267 If the proper locale is set (via
 268 .Dq LANG=<locale> ) ,
 269 national month and weekday names can be used as well.
 270 Additional rules are as follows:
 271 .Bl -bullet -offset indent
 272 .It
 273 Two numbers default to the month followed by the day.
 274 .It
 275 A single asterisk
 276 .Pq Sq *
 277 matches every month.
 278 .It
 279 A day without a month matches that day of every week.
 280 .It
 281 A day of zero means the last day of previous month.
 282 .It
 283 The names of special days may be followed by a
 284 positive or negative integer to represent the date offset, like:
 285 .Dq Easter+3
 286 or
 287 .Dq Paskha-4 .
 288 .It
 289 A weekday may be followed by a sequence name
 290 .Dq ( First
 291 .Li ...
 292 .Dq Fifth ,
 293 and
 294 .Dq Last )
 295 to specify moving events, like
 296 .Dq the last Monday in April .
 297 Numeric sequence
 298 .Dq ( \(+-[12345] )
 299 can also be used.
 300 .It
 301 A date may be followed by an asterisk
 302 .Pq Sq *
 303 to indicate that it is not fixed (i.e., changes from year to year).
 304 .It
 305 A date must be immediately followed by <tab> character(s), and then
 306 followed by the event description.
 307 Lines without containing a <tab> character are invalid and thus ignored.
 308 .It
 309 Lines starting with a <tab> character are treated as a continuation of
 310 the previous line, allowing multiple-line description of an event.
 311 .El
 312 .Pp
 313 The supported date styles can vary with calendars.
 314 In the Gregorian calendar, the following date styles are supported:
 315 .Bd -literal -offset indent
 316 Date                    ::=     Year . '/' . Month . '/' . DayOfMonth |
 317                                 Year . ' ' . Month . ' ' . DayOfMonth |
 318                                 Month . '/' . DayOfMonth |
 319                                 Month . ' ' . DayOfMonth |
 320                                 Month . '/' . DayOfWeek . Index |
 321                                 Month . ' ' . DayOfWeek . Index |
 322                                 MonthName . '/' . AllDays |
 323                                 MonthName . ' ' . AllDays |
 324                                 AllDays . '/' . MonthName |
 325                                 AllDays . ' ' . MonthName |
 326                                 AllMonths . '/' . DayOfMonth |
 327                                 AllMonths . ' ' . DayOfMonth |
 328                                 DayOfMonth . '/' . AllMonths |
 329                                 DayOfMonth . ' ' . AllMonths |
 330                                 DayOfMonth . '/' . Month |
 331                                 DayOfMonth . ' ' . Month |
 332                                 DayOfWeek . Index . '/' . MonthName |
 333                                 DayOfWeek . Index . ' ' . MonthName |
 334                                 DayOfWeek . Index
 335                                 SpecialDay . Offset
 336
 337 Year                    ::=     '0' ... '9' | '00' ... '09' | '10' ... '99' |
 338                                 '100' ... '999' | '1000' ... '9999'
 339
 340 Month                   ::=     MonthName | MonthNumber
 341 MonthNumber             ::=     '0' ... '9' | '00' ... '09' | '10' ... '12'
 342 MonthName               ::=     MonthNameShort | MonthNameLong
 343 MonthNameLong           ::=     'January' ... 'December'
 344 MonthNameShort          ::=     'Jan' ... 'Dec' | 'Jan.' ... 'Dec.'
 345
 346 DayOfWeek               ::=     DayOfWeekShort | DayOfWeekLong
 347 DayOfWeekShort          ::=     'Mon' ... 'Sun'
 348 DayOfWeekLong           ::=     'Monday' ... 'Sunday'
 349 DayOfMonth              ::=     '0' ... '9' | '00' ... '09' | '10' ... '29' |
 350                                 '30' ... '31'
 351
 352 AllMonths               ::=     '*'
 353 AllDays                 ::=     '*'
 354
 355 Index                   ::=     '' | IndexName |
 356                                 '+' . IndexNumber | '-' . IndexNumber
 357 IndexName               ::=     'First' | 'Second' | 'Third' | 'Fourth' |
 358                                 'Fifth' | 'Last'
 359 IndexNumber             ::=     '1' ... '5'
 360
 361 Offset                  ::=     '' | '+' . OffsetNumber | '-' . OffsetNumber
 362 OffsetNumber            ::=     '0' ... '9' | '00' ... '99' | '000' ... '299' |
 363                                 '300' ... '359' | '360' ... '365'
 364
 365 SpecialDay              ::=     'Easter' | 'Paskha' | 'Advent' |
 366                                 'ChineseNewYear' |
 367                                 'ChineseQingming' | 'ChineseJieqi' |
 368                                 'NewMoon' | 'FullMoon' |
 369                                 'MarEquinox' | 'SepEquinox' |
 370                                 'JunSolstice' | 'DecSolstice'
 371 .Ed
 372 .Sh EXAMPLES
 373 Some possible calendar entries (<tab> characters highlighted as
 374 .Sq \fB\et\fR ) :
 375 .Bd -unfilled -offset indent
 376 CLANEDAR=Gregorian
 377 LANG=C
 378 Easter=Ostern
 379
 380 /* Include shared calendar files */
 381 #include <calendar.birthday>
 382 #include <calendar.holiday>
 383
 384 6/15\fB\et\fRJune 15 (if ambiguous, will default to month/day)
 385 Jun. 15\fB\et\fRJune 15
 386 15 June\fB\et\fRJune 15
 387 15 *\fB\et\fR15th of every month
 388 0 *\fB\et\fRLast day of every month
 389 March/0\fB\et\fRLast day of February
 390 2010/4/15\fB\et\fR15 April 2010
 391 2020/11/03*\fB\et\fRU.S. Election Day ('*' indicates a movable event)
 392
 393 Thursday\fB\et\fREvery Thursday
 394 SatSecond\fB\et\fRSecond Saturday of every month
 395 Apr/Mon\fB\et\fREvery Monday in April
 396 May Sun+2\fB\et\fRSecond Sunday in May (Muttertag)
 397 04/SunLast\fB\et\fRLast Sunday in April,
 398 \fB\et\fRSummer time in Europe  // continuation of previous line
 399
 400 Easter\fB\et\fREaster
 401 Ostern-2\fB\et\fRGood Friday (2 days before Easter)
 402 Paskha\fB\et\fROrthodox Easter
 403 NewMoon\fB\et\fRNew moon of every month
 404 .Ed
 405 .Sh FILES
 406 .Bl -tag -width calendar.123456789012 -compact
 407 .It Pa calendar
 408 The calendar file to find in current directory.
 409 .It Pa ~/.calendar
 410 The default calendar home directory.
 411 A
 412 .Xr chdir 2
 413 is done into this directory if it exists.
 414 .It Pa ~/.calendar/calendar
 415 The calendar file to use if no calendar file exists in the current directory.
 416 .It Pa ~/.calendar/nomail
 417 Do not send mail if this file exists.
 418 .It Pa @@CALENDAR_ETCDIR@@/default
 419 The system-wide default calendar file, which is used if the
 420 .Pa ~/.calendar/calendar
 421 doesn't exist.
 422 This fallback calendar file is ignored in the
 423 .Fl a
 424 mode.
 425 .El
 426 .Pp
 427 The following calendar files are provided in
 428 .Pa @@CALENDAR_DIR@@ :
 429 .Pp
 430 .Bl -tag -width calendar.123456789012 -compact
 431 .It Pa calendar.all
 432 File which includes all the calendar files.
 433 .It Pa calendar.australia
 434 Calendar of events in Australia.
 435 .It Pa calendar.birthday
 436 Births and deaths of famous (and not-so-famous) people.
 437 .It Pa calendar.brazilian
 438 Calendar of events in Brazil.
 439 .It Pa calendar.canada
 440 Canadian holidays.
 441 .It Pa calendar.chinese
 442 Calendar of events in China.
 443 .It Pa calendar.christian
 444 Christian holidays.
 445 .It Pa calendar.computer
 446 Days of special significance to computer people.
 447 .It Pa calendar.croatian
 448 Calendar of events in Croatia.
 449 .It Pa calendar.discord
 450 Discordian calendar (all rites reversed).
 451 .It Pa calendar.dragonfly
 452 .Dx
 453 related events.
 454 .It Pa calendar.dutch
 455 Calendar of events in the Netherlands.
 456 .It Pa calendar.fictional
 457 Fantasy and fiction dates (mostly
 458 .Em Load Of The Rings ) .
 459 .It Pa calendar.french
 460 Calendar of events in France.
 461 .It Pa calendar.german
 462 Calendar of events in Germany.
 463 .It Pa calendar.history
 464 Miscellaneous history.
 465 .It Pa calendar.holiday
 466 Other holidays, including the not-well-known, obscure, and
 467 .Em really
 468 obscure.
 469 .It Pa calendar.hungarian
 470 Calendar of events in Hungary.
 471 .It Pa calendar.judaic
 472 Jewish holidays.
 473 This calendar should be updated yearly by the local system administrator
 474 so that roving holidays are set correctly for the current year.
 475 The entries for this calendar have been obtained from the port
 476 .Pa deskutils/hebcal .
 477 .It Pa calendar.misc
 478 Miscellaneous events.
 479 .It Pa calendar.music
 480 Musical events, births, and deaths.
 481 Strongly oriented toward rock 'n' roll and classical.
 482 .It Pa calendar.newzealand
 483 Calendar of events in New Zealand.
 484 .It Pa calendar.orthodox
 485 Orthodox holidays.
 486 .It Pa calendar.russian
 487 Russian calendar.
 488 .It Pa calendar.southafrica
 489 Calendar of events in South Africa.
 490 .It Pa calendar.space
 491 Aerospace and astronomical events.
 492 .It Pa calendar.uk
 493 Calendar of events in U.K.
 494 .It Pa calendar.ukrainian
 495 Calendar of events in Ukraine.
 496 .It Pa calendar.ushistory
 497 U.S.\& history.
 498 .It Pa calendar.usholiday
 499 U.S.\& holidays.
 500 This calendar should be updated yearly by the local system administrator
 501 so that roving holidays are set correctly for the current year.
 502 .It Pa calendar.world
 503 Includes all calendar files except for national ones.
 504 .El
 505 .Sh COMPATIBILITY
 506 The
 507 .Nm
 508 utility previously selected lines which had the correct date anywhere
 509 in the line.
 510 This is no longer true: the date is only recognized when it occurs
 511 at the beginning of a line.
 512 .Sh SEE ALSO
 513 .Xr at 1 ,
 514 .Xr cal 1 ,
 515 .Xr mail 1 ,
 516 .Xr cron 8
 517 .Rs
 518 .%A Edward M. Reingold
 519 .%A Nachum Dershowitz
 520 .%B Calendrical Calculations: The Ultimate Edition (4th Edition)
 521 .%I Cambridge University Press
 522 .%D 2018
 523 .%O ISBN: 9781107057623
 524 .Re
 525 .Sh HISTORY
 526 A
 527 .Nm
 528 command appeared in
 529 .At v7 .
 530 .Pp
 531 The
 532 .Nm
 533 utility was significantly enhanced in
 534 .Fx 9.0
 535 by
 536 .An Edwin Groothuis Aq Mt edwin@FreeBSD.org ,
 537 and was later rewritten to support multiple calendars in
 538 .Dx 5.9
 539 by
 540 .An Aaron LI Aq Mt aly@aaronly.me .
 541 .Sh NOTES
 542 The new and full moons are happening on the day indicated.
 543 They can happen in the time period from the early morning to
 544 the late evening.
 545 .Pp
 546 The adopted methods to calculate solar and lunar events are
 547 simplified astronomical algorithms, so the accuracy of events is
 548 within several minutes, provided that the precise location is specified.
 549 Druids and Werewolves should double-check the start and end time of
 550 solar and lunar events.
 551 .Sh BUGS
 552 The
 553 .Nm
 554 internal preprocessor only recognizes
 555 .Sy #include ,
 556 .Sy #ifndef ,
 557 .Sy #endif ,
 558 and
 559 .Sy #define .
 560 Quoted or escaped comment marks are not supported yet.
 561 .Pp
 562 An event can repeat at most 100 times in the specified date range.
 563 The most repeated event is an weekly event, so a maximum of 100 repeats
 564 covers a date range of about 2 years.
 565 If more repeats of events are needed, you're likely using
 566 .Nm
 567 in the wrong way ;)