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. All advertising materials mentioning features or use of this software
  13 .\"    must display the following acknowledgement:
  14 .\"     This product includes software developed by the University of
  15 .\"     California, Berkeley and its contributors.
  16 .\" 4. Neither the name of the University nor the names of its contributors
  17 .\"    may be used to endorse or promote products derived from this software
  18 .\"    without specific prior written permission.
  19 .\"
  20 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
  21 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  22 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  23 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
  24 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  25 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  26 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  27 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  28 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  29 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  30 .\" SUCH DAMAGE.
  31 .\"
  32 .\"     @(#)calendar.1  8.1 (Berkeley) 6/29/93
  33 .\" $FreeBSD: src/usr.bin/calendar/calendar.1,v 1.16.2.9 2003/04/06 20:04:56 dwmalone Exp $
  34 .\" $DragonFly: src/usr.bin/calendar/calendar.1,v 1.2 2003/06/17 04:29:25 dillon Exp $
  35 .\"
  36 .Dd June 13, 2002
  37 .Dt CALENDAR 1
  38 .Os
  39 .Sh NAME
  40 .Nm calendar
  41 .Nd reminder service
  42 .Sh SYNOPSIS
  43 .Nm
  44 .Op Fl a
  45 .Op Fl A Ar num
  46 .Op Fl B Ar num
  47 .Op Fl F Ar friday
  48 .Op Fl f Ar calendarfile
  49 .Oo
  50 .Bk -words
  51 .Fl t Ar dd Ns
  52 .Sm off
  53 .Op . Ar mm Op . Ar year
  54 .Sm on
  55 .Ek
  56 .Oc
  57 .Op Fl W Ar num
  58 .Sh DESCRIPTION
  59 The
  60 .Nm
  61 utility checks the current directory for a file named
  62 .Pa calendar
  63 and displays lines that begin with either today's date
  64 or tomorrow's.
  65 On the day before a weekend (normally Friday), events for the next
  66 three days are displayed.
  67 .Pp
  68 The following options are available:
  69 .Bl -tag -width Ds
  70 .It Fl A Ar num
  71 Print lines from today and the next
  72 .Ar num
  73 days (forward, future).
  74 .It Fl a
  75 Process the ``calendar'' files of all users and mail the results
  76 to them.
  77 This requires super-user privileges.
  78 .It Fl B Ar num
  79 Print lines from today and the previous
  80 .Ar num
  81 days (backward, past).
  82 .It Fl F Ar friday
  83 Specify which day of the week is ``Friday'' (the day before the
  84 weekend begins).
  85 Default is 5.
  86 .It Fl f Pa calendarfile
  87 Use
  88 .Pa calendarfile
  89 as the default calendar file.
  90 .It Xo Fl t
  91 .Sm off
  92 .Ar dd
  93 .Op . Ar mm Op . Ar year
  94 .Sm on
  95 .Xc
  96 For test purposes only: set date directly to argument values.
  97 .It Fl W Ar num
  98 Print lines from today and the next
  99 .Ar num
 100 days (forward, future).
 101 Ignore weekends when calculating the number of days.
 102 .El
 103 .Pp
 104 To handle calendars in your national code table you can specify
 105 .Dq LANG=<locale_name>
 106 in the calendar file as early as possible.
 107 To handle national Easter
 108 names in the calendars
 109 .Dq Easter=<national_name>
 110 (for Catholic Easter) or
 111 .Dq Paskha=<national_name>
 112 (for Orthodox Easter) can be used.
 113 .Pp
 114 Other lines should begin with a month and day.
 115 They may be entered in almost any format, either numeric or as character
 116 strings.
 117 If the proper locale is set, national month and weekday
 118 names can be used.
 119 A single asterisk (``*'') matches every month.
 120 A day without a month matches that day of every week.
 121 A month without a day matches the first of that month.
 122 Two numbers default to the month followed by the day.
 123 Lines with leading tabs default to the last entered date, allowing
 124 multiple line specifications for a single date.
 125 .Pp
 126 ``Easter'', is Easter for this year, and may be followed by a positive
 127 or negative integer.
 128 .Pp
 129 ``Paskha'', is Orthodox Easter for this year, and may be followed by a
 130 positive or negative integer.
 131 .Pp
 132 Weekdays may be followed by ``-4'' ... ``+5'' (aliases for
 133 last, first, second, third, fourth) for moving events like
 134 ``the last Monday in April''.
 135 .Pp
 136 By convention, dates followed by an asterisk are not fixed, i.e., change
 137 from year to year.
 138 .Pp
 139 Day descriptions start after the first <tab> character in the line;
 140 if the line does not contain a <tab> character, it is not displayed.
 141 If the first character in the line is a <tab> character, it is treated as
 142 a continuation of the previous line.
 143 .Pp
 144 The ``calendar'' file is preprocessed by
 145 .Xr cpp 1 ,
 146 allowing the inclusion of shared files such as lists of company holidays or
 147 meetings.
 148 If the shared file is not referenced by a full pathname,
 149 .Xr cpp 1
 150 searches in the current (or home) directory first, and then in the
 151 directory
 152 .Pa /usr/share/calendar .
 153 Empty lines and lines protected by the C commenting syntax
 154 .Pq Li /* ... */
 155 are ignored.
 156 .Pp
 157 Some possible calendar entries (<tab> characters highlighted by
 158 \fB\et\fR sequence)
 159 .Bd -unfilled -offset indent
 160 LANG=C
 161 Easter=Ostern
 162
 163 #include <calendar.usholiday>
 164 #include <calendar.birthday>
 165
 166 6/15\fB\et\fRJune 15 (if ambiguous, will default to month/day).
 167 Jun. 15\fB\et\fRJune 15.
 168 15 June\fB\et\fRJune 15.
 169 Thursday\fB\et\fREvery Thursday.
 170 June\fB\et\fREvery June 1st.
 171 15 *\fB\et\fR15th of every month.
 172
 173 May Sun+2\fB\et\fRsecond Sunday in May (Muttertag)
 174 04/SunLast\fB\et\fRlast Sunday in April,
 175 \fB\et\fRsummer time in Europe
 176 Easter\fB\et\fREaster
 177 Ostern-2\fB\et\fRGood Friday (2 days before Easter)
 178 Paskha\fB\et\fROrthodox Easter
 179
 180 .Ed
 181 .Sh FILES
 182 .Bl -tag -width calendar.christian -compact
 183 .It Pa calendar
 184 file in current directory
 185 .It Pa ~/.calendar
 186 .Pa calendar
 187 HOME directory.
 188 A chdir is done into this directory if it exists.
 189 .It Pa ~/.calendar/calendar
 190 calendar file to use if no calendar file exists in the current directory.
 191 .It Pa ~/.calendar/nomail
 192 do not send mail if this file exists.
 193 .El
 194 .Pp
 195 The following default calendar files are provided:
 196 .Pp
 197 .Bl -tag -width calendar.southafrica -compact
 198 .It Pa calendar.all
 199 File which includes all the default files.
 200 .It Pa calendar.australia
 201 Calendar of events in Australia.
 202 .It Pa calendar.birthday
 203 Births and deaths of famous (and not-so-famous) people.
 204 .It Pa calendar.christian
 205 Christian holidays.
 206 This calendar should be updated yearly by the local system administrator
 207 so that roving holidays are set correctly for the current year.
 208 .It Pa calendar.computer
 209 Days of special significance to computer people.
 210 .It Pa calendar.croatian
 211 Calendar of events in Croatia.
 212 .It Pa calendar.freebsd
 213 Birthdays of
 214 .Fx
 215 committers.
 216 .It Pa calendar.french
 217 Calendar of events in France.
 218 .It Pa calendar.german
 219 Calendar of events in Germany.
 220 .It Pa calendar.history
 221 Everything  else, mostly U.S. historical events.
 222 .It Pa calendar.holiday
 223 Other  holidays, including the not-well-known, obscure, and
 224 .Em really
 225 obscure.
 226 .It Pa calendar.judaic
 227 Jewish holidays.
 228 This calendar should be updated yearly by the local system administrator
 229 so that roving holidays are set correctly for the current year.
 230 .It Pa calendar.music
 231 Musical  events,  births, and deaths.
 232 Strongly  oriented  toward  rock 'n' roll.
 233 .It Pa calendar.usholiday
 234 U.S. holidays.
 235 This calendar should be updated yearly by the local system administrator
 236 so that roving holidays are set correctly for the current year.
 237 .It Pa calendar.french
 238 French calendar.
 239 .It Pa calendar.german
 240 German calendar.
 241 .It Pa calendar.newzealand
 242 Calendar of events in New Zealand.
 243 .It Pa calendar.russian
 244 Russian calendar.
 245 .It Pa calendar.southafrica
 246 Calendar of events in South Africa.
 247 .It Pa calendar.usholiday
 248 Calendar of holidays specific to the United States of America.
 249 .It Pa calendar.world
 250 Includes all calendar files except for national files.
 251 .El
 252 .Sh SEE ALSO
 253 .Xr at 1 ,
 254 .Xr cpp 1 ,
 255 .Xr mail 1 ,
 256 .Xr cron 8
 257 .Sh COMPATIBILITY
 258 The
 259 .Nm
 260 program previously selected lines which had the correct date anywhere
 261 in the line.
 262 This is no longer true, the date is only recognized when it occurs
 263 at the beginning of a line.
 264 .Sh HISTORY
 265 A
 266 .Nm
 267 command appeared in
 268 .At v7 .
 269 .Sh BUGS
 270 The
 271 .Nm
 272 utility doesn't handle Jewish holidays and moon phases.