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 .\" 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$
  30 .\"
  31 .Dd November 5, 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 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 for users found in
  74 .Pa /etc/passwd
  75 and mail the results
  76 to them.
  77 This can result in multiple messages for specific files, since
  78 .Pa /etc/passwd
  79 does not require home directories to be unique.
  80 In particular, by default
  81 .Ar root ,
  82 .Ar toor
  83 and
  84 .Ar daemon
  85 share the same home directory.
  86 If this directory contains calendar information,
  87 .Nm
  88 will process the file three times.
  89 .Pp
  90 This option requires super-user privileges.
  91 .It Fl B Ar num
  92 Print lines from today and the previous
  93 .Ar num
  94 days (backward, past).
  95 .It Fl D Ar moon|sun
  96 Print UTC offset, longitude and moon or sun information.
  97 .It Fl d
  98 Debug option: print current date information.
  99 .It Fl F Ar friday
 100 Specify which day of the week is ``Friday'' (the day before the
 101 weekend begins).
 102 Default is 5.
 103 .It Fl f Pa calendarfile
 104 Use
 105 .Pa calendarfile
 106 as the default calendar file.
 107 .It Fl l Ar longitude
 108 Perform lunar and solar calculations from this longitude.
 109 If neither longitude nor UTC offset is specified, the calculations will
 110 be based on the difference between UTC time and localtime.
 111 If both are specified, UTC offset overrides longitude.
 112 .It Xo Fl t
 113 .Sm off
 114 .Ar dd
 115 .Op . Ar mm Op . Ar year
 116 .Sm on
 117 .Xc
 118 For test purposes only: set date directly to argument values.
 119 .It Fl U Ar UTC-offset
 120 Perform lunar and solar calculations from this UTC offset.
 121 If neither UTC offset nor longitude is specified, the calculations
 122 will be based on the difference between UTC time and localtime.
 123 If both are specified, UTC offset overrides longitude.
 124 .It Fl W Ar num
 125 Print lines from today and the next
 126 .Ar num
 127 days (forward, future).
 128 Ignore weekends when calculating the number of days.
 129 .El
 130 .Sh FILE FORMAT
 131 To handle calendars in your national code table you can specify
 132 .Dq LANG=<locale_name>
 133 in the calendar file as early as possible.
 134 .Pp
 135 To handle the local name of sequences, you can specify them as:
 136 .Dq SEQUENCE=<first> <second> <third> <fourth> <fifth> <last>
 137 in the calendar file as early as possible.
 138 .Pp
 139 The names of the following special days are recognized:
 140 .Bl -tag -width 123456789012345 -compact
 141 .It Easter
 142 Catholic Easter.
 143 .It Paskha
 144 Orthodox Easter.
 145 .It NewMoon
 146 The lunar New Moon.
 147 .It FullMoon
 148 The lunar Full Moon.
 149 .It MarEquinox
 150 The solar equinox in March.
 151 .It JunSolstice
 152 The solar solstice in June.
 153 .It SepEquinox
 154 The solar equinox in September.
 155 .It DecSolstice
 156 The solar solstice in December.
 157 .It ChineseNewYear
 158 The first day of the Chinese year.
 159 .El
 160 These names may be reassigned to their local names via an assignment
 161 like
 162 .Dq Easter=Pasen
 163 in the calendar file.
 164 .Pp
 165 Other lines should begin with a month and day.
 166 They may be entered in almost any format, either numeric or as character
 167 strings.
 168 If the proper locale is set, national month and weekday
 169 names can be used.
 170 A single asterisk (``*'') matches every month.
 171 A day without a month matches that day of every week.
 172 A month without a day matches the first of that month.
 173 Two numbers default to the month followed by the day.
 174 Lines with leading tabs default to the last entered date, allowing
 175 multiple line specifications for a single date.
 176 .Pp
 177 The names of the recognized special days may be followed by a
 178 positive or negative integer, like:
 179 .Dq Easter+3
 180 or
 181 .Dq Paskha-4 .
 182 .Pp
 183 Weekdays may be followed by ``-4'' ...\& ``+5'' (aliases for
 184 last, first, second, third, fourth) for moving events like
 185 ``the last Monday in April''.
 186 .Pp
 187 By convention, dates followed by an asterisk are not fixed, i.e., change
 188 from year to year.
 189 .Pp
 190 Day descriptions start after the first <tab> character in the line;
 191 if the line does not contain a <tab> character, it is not displayed.
 192 If the first character in the line is a <tab> character, it is treated as
 193 a continuation of the previous line.
 194 .Pp
 195 The
 196 .Nm
 197 file is preprocessed by a limited subset of
 198 .Xr cpp 1
 199 internally, allowing the inclusion of shared files such as
 200 lists of company holidays or meetings.
 201 This limited subset consists of \fB#include\fR, \fB#define\fR,
 202 \fB#undef\fR, \fB#ifdef\fR, \fB#ifndef\fR, \fB#else\fR, \fB#warning\fR,
 203 and \fB#error\fR.
 204 .Pp
 205 Conditions can be nested and the consistency of opening and closing
 206 instructions is checked.
 207 Only the first word after #define is used as the name of the
 208 condition variable being defined.
 209 More than word following #ifdef, #ifndef, or #undef is considered a syntax
 210 error, since names cannot include white-space.
 211 Included files are parsed in a global scope with regard to the condition
 212 variables being defined or tested therein.
 213 All conditional blocks are implicitly closed at the end of a file,
 214 and missing #endif instructions are assumed to be present on implied
 215 succeeding lines.
 216 .Pp
 217 If the shared file is not referenced by a full pathname,
 218 .Nm
 219 searches in the current (or home) directory first, and then in the
 220 directory
 221 .Pa /usr/share/calendar .
 222 Empty lines and text protected by the C commenting syntax
 223 .Pq Li /* ... */
 224 or
 225 .Pq Li //
 226 are ignored.
 227 .Pp
 228 Some possible calendar entries (<tab> characters highlighted by
 229 \fB\et\fR sequence):
 230 .Bd -unfilled -offset indent
 231 LANG=C
 232 Easter=Ostern
 233
 234 #include <calendar.usholiday>
 235 #include <calendar.birthday>
 236
 237 6/15\fB\et\fRJune 15 (if ambiguous, will default to month/day).
 238 Jun. 15\fB\et\fRJune 15.
 239 15 June\fB\et\fRJune 15.
 240 Thursday\fB\et\fREvery Thursday.
 241 June\fB\et\fREvery June 1st.
 242 15 *\fB\et\fR15th of every month.
 243 2010/4/15\fB\et\fR15 April 2010
 244
 245 May Sun+2\fB\et\fRsecond Sunday in May (Muttertag)
 246 04/SunLast\fB\et\fRlast Sunday in April,
 247 \fB\et\fRsummer time in Europe
 248 Easter\fB\et\fREaster
 249 Ostern-2\fB\et\fRGood Friday (2 days before Easter)
 250 Paskha\fB\et\fROrthodox Easter
 251
 252 .Ed
 253 .Sh FILES
 254 .Bl -tag -width calendar.christian -compact
 255 .It Pa calendar
 256 file in current directory.
 257 .It Pa ~/.calendar
 258 .Pa calendar
 259 HOME directory.
 260 A chdir is done into this directory if it exists.
 261 .It Pa ~/.calendar/calendar
 262 calendar file to use if no calendar file exists in the current directory.
 263 .It Pa ~/.calendar/nomail
 264 do not send mail if this file exists.
 265 .It Pa /usr/share/calendar
 266 system wide location of calendar files provided as part of the base system.
 267 .It Pa /usr/local/share/calendar
 268 system wide location for calendar files provided by a port or package.
 269 .El
 270 .Pp
 271 The order of precedence in searches for a calendar file is:
 272 current directory, ~/.calendar, /usr/local/share/calendar, /usr/share/calendar.
 273 Files of similar names are ignored in lower precedence locations.
 274 .Pp
 275 The following default calendar files are provided by the
 276 deskutils/calendar-data port.
 277 .Pp
 278 .Bl -tag -width calendar.southafrica -compact
 279 .It Pa calendar.all
 280 File which includes all the default files.
 281 .It Pa calendar.australia
 282 Calendar of events in Australia.
 283 .It Pa calendar.birthday
 284 Births and deaths of famous (and not-so-famous) people.
 285 .It Pa calendar.christian
 286 Christian holidays.
 287 This calendar should be updated yearly by the local system administrator
 288 so that roving holidays are set correctly for the current year.
 289 .It Pa calendar.computer
 290 Days of special significance to computer people.
 291 .It Pa calendar.croatian
 292 Calendar of events in Croatia.
 293 .It Pa calendar.dutch
 294 Calendar of events in the Netherlands.
 295 .It Pa calendar.freebsd
 296 Birthdays of
 297 .Fx
 298 committers.
 299 .It Pa calendar.french
 300 Calendar of events in France.
 301 .It Pa calendar.german
 302 Calendar of events in Germany.
 303 .It Pa calendar.history
 304 Everything else, mostly U.S.\& historical events.
 305 .It Pa calendar.holiday
 306 Other holidays, including the not-well-known, obscure, and
 307 .Em really
 308 obscure.
 309 .It Pa calendar.judaic
 310 Jewish holidays.
 311 The entries for this calendar have been obtained from the
 312 deskutils/hebcal port.
 313 .It Pa calendar.music
 314 Musical events, births, and deaths.
 315 Strongly oriented toward rock 'n' roll.
 316 .It Pa calendar.newzealand
 317 Calendar of events in New Zealand.
 318 .It Pa calendar.russian
 319 Russian calendar.
 320 .It Pa calendar.southafrica
 321 Calendar of events in South Africa.
 322 .It Pa calendar.usholiday
 323 U.S.\& holidays.
 324 This calendar should be updated yearly by the local system administrator
 325 so that roving holidays are set correctly for the current year.
 326 .It Pa calendar.world
 327 Includes all calendar files except for national files.
 328 .El
 329 .Sh COMPATIBILITY
 330 The
 331 .Nm
 332 program previously selected lines which had the correct date anywhere
 333 in the line.
 334 This is no longer true, the date is only recognized when it occurs
 335 at the beginning of a line.
 336 .Sh SEE ALSO
 337 .Xr at 1 ,
 338 .Xr mail 1 ,
 339 .Xr cron 8
 340 .Sh HISTORY
 341 A
 342 .Nm
 343 command appeared in
 344 .At v7 .
 345 .Sh NOTES
 346 Chinese New Year is calculated at 120 degrees east of Greenwich,
 347 which roughly corresponds with the east coast of China.
 348 For people west of China, this might result that the start of Chinese
 349 New Year and the day of the related new moon might differ.
 350 .Pp
 351 The phases of the moon and the longitude of the sun are calculated
 352 against the local position which corresponds with 30 degrees times
 353 the time-difference towards Greenwich.
 354 .Pp
 355 The new and full moons are happening on the day indicated: They
 356 might happen in the time period in the early night or in the late
 357 evening.
 358 It does not indicate that they are starting in the night on that date.
 359 .Pp
 360 Because of minor differences between the output of the formulas
 361 used and other sources on the Internet, Druids and Werewolves should
 362 double-check the start and end time of solar and lunar events.
 363 .Sh BUGS
 364 The
 365 .Nm
 366 does only recognise the cpp directives #include, #define, #ifdef,
 367 #ifndef and #else.
 368 It supports nested conditions, but does not perform any validation
 369 on the correct use and nesting of conditions.
 370 #endif without prior #ifdef or #define is ignored and #else outside
 371 a conditional section skips input lines up to the next #endif.
 372 .Pp
 373 There is no possibility to properly specify the local position
 374 needed for solar and lunar calculations.