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