Take Command

Calendar Programs

Mr. Stutz introduces us to a digital method for keeping track of appointments and those important dates in our lives.

by Michael Stutz

I am obsessive about keeping track of things. I used to get a free calendar each year from the local phone company. It was the perfect interface for all my appointments--a slim, spiral-bound calendar that I kept on my desktop and used to record any upcoming appointments, as well as mark the birthdays of my friends and family. Every year around the holidays I'd get a new calendar and dutifully re-transcribe the birthdays and other annual appointments into the new calendar.

A few years ago, the phone company decided to stop sending out these free calendars, but fortunately I had found a better way. By using cal and calendar programs, I can leave all my old analog date books behind.

Different versions of these utilities exist. Originally part of the BSD utilities, a GNU version called gcal with some advanced features has been released. I will focus this tutorial on the original BSD programs since they're widely available, as well as mention some other related programs at the end of the article.

You'll first want to find out if you have these programs installed on your system by typing:

which cal

If which returns a full pathname of the cal program, it is installed. If instead you are immediately returned to a shell prompt, then you will need to obtain and install this program. You can use which again to see if you have the calendar program installed as well; they are different programs and you will need them both.

If you use the Debian distribution of Linux, both programs are available in the bsdmainutils package. Otherwise, consult your distribution, or search the Linux Software Map at http://www.linuxresources.com/apps.html.

Using Calendar

calendar is a basic reminder service. It reads a file called calendar in the current directory and prints lines which start with today's or tomorrow's dates. The calendar file is a text file that can be created and edited with any text editor.

This program is more powerful than it may seem at first. The general format for a calendar file entry is the month and day to the immediate left, followed by a tab and the reminder text. The month and day can be skipped--each line beginning with a tab carries the same month and day value as the line preceding it.

There is quite a varied syntax for the month and day. To demonstrate, let's make up a sample calendar file and look at it line by line:

10/31	Johnny's Halloween party
Friday	Garbage day
Nov. 20	Dentist appointment, 9:30am
20/11	Mandatory staff meeting, 10:00am
January	Happy new year!
	Have you made your resolutions yet?
18 *	Rent's due

Let's imagine that today is Friday, October 31, 1997. At the shell prompt, type:

calendar

With the sample calendar file in your current directory, you will see this output:

10/31	Johnny's Halloween party
Friday	Garbage day

The 10/31 in the first line tells calendar to print that line if it is October 31 (or the day before), and the Friday in the second line tells it to print (you guessed it) every Friday.

As you can see, you can also use an abbreviated form of writing out the month, as in the example line starting with Nov. 20. Now, on the fourth line, the mm/dd format is reversed--in this case, calendar figures that out and will print it on the 20th day of November. It's probably not a good idea to keep records in this format. If you were to write May 10th as 10/5, calendar will assume you mean the U.S. convention of mm/dd and print that entry on October 5th.

If you have just the name of a month in the first column, calendar will print the entry on the first of that month. If you eliminate that column altogether by inserting a tab and some reminder text, calendar will print the line on the date of the preceding entry. Thus, on New Year's Day, our example calendar will output:

January	Happy new year!
	Have you made your resolutions yet?

Finally, substituting an asterisk for the month will print that entry on the stated date each month. In our example, a reminder to pay the rent will be displayed on the eighteenth of each month.

Keeping Your Dates Separate

Since it is pre-processed by cpp, the C preprocessor, calendar recognizes include files. This allows you to keep and use special lists, such as a personal list of birthdays, without cluttering up your main calendar file. The calendar program comes with a set of such files in /usr/lib/calendar/ to get you started:

calendar.birthday: birth and death dates of many famous historical figures
calendar.computer: important dates in the history of computing
calendar.holiday: known (and not-so-well-known) holidays
calendar.music: important dates in music, especially mainstream rock-n-roll
calendar.christian: Christian holidays
calendar.history: many historical events
calendar.judaic: Jewish holidays
calendar.usholiday: standard US holidays

When you use an include statement, calendar first searches the directory it was called in, and then looks in /usr/lib/calendar/. Including this line in your file,

#include <calendar.usholiday>

means calendar will first look in the current directory for such a file. If not present, it will then check /usr/lib/calendar/, and if the appropriate file is found, include it.

One of the functions of my old paper calendar was to record and keep a record of important events in my life. I was able to reproduce this function by keeping this information in files named calendar.yyyy, such as calendar.1997. Looking through the files in order gives me a chronological record of major events in my life, and if I ever wanted to see what I was doing around today's date in a certain year or years, I could add include statements for the appropriate calendar.yyyy files in my calendar file.

Automating Calendar

You can run calendar whenever you like, but it might be more useful to put it in your profile file (~/.bash_profile if you use the bash shell). Then calendar will run each time you log in to the system.

I keep my personal calendar file in the doc/etc/ subdirectory of my home directory, so I would include the following line in my profile:

cd /home/m/doc/etc/; calendar; cd

Putting the same line in your .bashrc file (again, only if you use the bash shell--others are different) also works to run calendar each time you start a shell.

Sometimes even this isn't enough--if your machine is on all the time and you haven't been starting any new shells or xterms, you might miss a reminder. So you could schedule a cron job to run calendar each day, e-mailing the output to you as a reminder.

Using cal

The cal program displays a text calendar. If you call it without any options by typing:

cal

the current month will be displayed on the terminal like this (assuming September, 1998):

  September 1998
 S  M Tu  W Th  F  S
       1  2  3  4  5
 6  7  8  9 10 11 12
13 14 15 16 17 18 19
20 21 22 23 24 25 26
27 28 29 30

It's pretty no-frills, but can work on any terminal. To get a calendar of the whole year, call cal with the year as argument.

cal 1950

Typing:

cal -y

will print a calendar for the current year.

cal can also display any arbitrary month. If you want to see the month of December 1999, for instance, use:

cal 12 1999

in which case you'll see:

December 1999
 S  M Tu  W Th  F  S
          1  2  3  4
 5  6  7  8  9 10 11
12 13 14 15 16 17 18
19 20 21 22 23 24 25
26 27 28 29 30 31

Other Calendar Programs

While cal is quite useful for creating simple calendars, sometimes when printing you might want a nicer output. pcal is a program that creates very nice calendars in PostScript. Its options are very similar to that of cal. It is available from http://garbo.uwasa.fi/unix/pcal.html.

Other programs that handle calendar functions in a more graphically-intense way (and can be used only in X) include ical, at http://www.research.digital.com/SRC/personal/Sanjay_Ghemawat/ical/home.html and plan, found at http://www.in-berlin.de/User/bitrot/plan.html. There are many variants of the basic UNIX calendar programs--check the Linux Software Map for more.

With this overview of the power and flexibility of these simple calendar programs, you too can leave your analog calendar systems behind.

Michael Stutz is a writer whose first novel, Sunclipse, is freely distributed under GNU GPL copyleft--just like Linux--and is on the Web at http://dsl.org/m/doc/lit/sunclipse.html. He can be reached via e-mail at stutz@dsl.org.