When - a minimalistic personal calendar program

when

when [options] [commands]

i

Print upcoming items on your calendar. (This is the default command.)

c

Print calendars for last month, this month, and next month.

e

Invoke your favorite editor to edit your calendar file.

w,m,y

Print items for the coming week, month, or year, rather than for the default period of two weeks.

j

Print the modified Julian day (useful for finding the time interval between two dates).

d

Print nothing but the current date.

All of the following options, except --help, can be set in the preferences file. True/false options can be set on the command line as --option or --nooption, and in the preferences file by setting option to 0 or 1.

--help

Prints a brief help message.

--version

Prints a brief message, including a statement of what version of the software it is.

--language=LANG

Set the language to LANG. See the section below on internationalization. This option is not normally needed, because the language is automatically detected.

--past=DAYS

How many days into the past the report extends. Default: -1

--future=DAYS

How many days into the past the report extends. Default: 14

--calendar=FILE

Your calendar file. The default is to use the file pointed to by your preferences file, which is set up the first time you run When.

--wrap=COLUMNS

Number of columns of text for the output (or 0 if you don't want wrapping at all). Default: 80

--rows=COLUMNS

Number of rows of text that will fit in the terminal window. When listing your calendar, output will be truncated to this length, unless that would result in listing less than three days into the future. Default: 30

--editor=COMMAND

Command used to invoke your editor. Default: emacs -nw Example: when --editor=vi -R

--[no]filter_accents_on_output

Whether to change accented characters to unaccented ones. Default: yes, unless the CW$TERM environment variable equals mlterm or xterm.

--[no]styled_output

If the output is a terminal, should we use ANSI terminal codes for styling? Default: yes

--[no]styled_output_if_not_tty

Style the output even if it's not a terminal. Default: no

--calendar_today_style=STYLE

How to style today's date when doing the calendar (c) command. Default: bold

--items_today_style=STYLE

How to style the word ``today'' when doing the items (i) command. Default: bold Pretend today is some other date.

--[no]monday_first

Start the week from Monday, rather than Sunday. Default: no

--[no]ampm

Display the time of day using 12-hour time, rather than 24-hour time. Default: yes

--test_expression

Used internally by `make test'.

--bare_version

Used internally by the Makefile.

The styling of output can be specified using the following keywords: bold, underlined, flashing. To change the color of the text, use these: fgblack, fgred, fggreen, fgyellow, fgblue, fgpurple, fgcyan, fgwhite. To change the background color, use similar keywords, but with bg instead of fg. Example: when --calendar_today_style=bold,fgred,bgcyan c

When is an extremely simple personal calendar program, aimed at the Unix geek who wants something minimalistic. It can keep track of things you need to do on particular dates. There are a lot of calendar and ``personal information manager'' programs out there, so what reasons are there to use When?

It's a very short and simple program, so you can easily tinker with it yourself.

It doesn't depend on any libraries, so it's easy to install. You should be able to install it on any system where Perl is available, even if you don't have privileges for installing libraries.

Its file format is a simple text file, which you can edit in your favorite editor.

Although When should run on virtually any operating system where Perl is available, in this document I'll assume you're running some flavor of Unix.

While logged in as root, execute the following command:

       make install

Run When for the first time using this command:

       when

You'll be prompted for some information needed to set up your calendar file.

If you run When again after the initial setup run, it should print out a single line of text, telling you the current date. It won't print out anything else, because your calendar file is empty, so you don't have any appointments coming up.

Now you can start putting items in your calendar file. Each item is a line of text that looks like this:

        2003 feb 3 , Fly to Stockholm to accept Nobel Prize.

A convenient way to edit your calendar file is with this command:

        when e

This pops you into your favorite editor (the one you chose when you ran When for the first time).

The date has to be in year-month-day format, but you can either spell the month or give it as a number. (Month names are case-insensitive, and it doesn't matter if you represent February as F, Fe, Feb, Februa, or whatever. It just has to be a unique match. You can give a trailing ., which will be ignored.) Extra whitespace is ignored until you get into the actual text after the comma. Blank lines and lines beginning with a # sign are ignored.

For events that occur once a year, such as birthdays and annivesaries, you can either use a * in place of the year,

        * dec 25 , Christmas

or use a year with an asterisk:

        1920* aug 29 , Charlie Parker turns \a, born in \y

In the second example, \a tells you how old Charlie Parker would be this year, and \y reproduces the year he was born, i.e., the output would be:

        today     2003 Aug 29 Charlie Parker turns 83, born in 1920

For things you have to do every week, you can use an expression of the form w=xxx, where xxx is the first few letters of the name of the day of the week in your language. (You have to supply enough letters to eliminate ambiguity, e.g., in English, w=th or w=tu, not just w=t.) Example:

        w=sun , go to church, 10:00

You can actually do fancier tests than this as well; for more information, see the section 'fancy tests' below.

If you now run When, it will print out a list of all the items in your calendar file that fall in the time interval from yesterday through the next two weeks. To see all your items for the next month, do ``when m'', and similarly for a year, y, or a single week, w.

If you do ``when c'', When prints out calendars for last month, this month, and next month.

You can combine these commands. For instance, ``when cw'' will print out calendars, and then show you your items for the next week.

When has at least partial support for English, Polish, Italian, German, Dutch, and French. If When has not been translated into your language, or has only been partially translated, the text that hasn't been translated will be displayed in English. When should automatically detect what language you use (via your CW$LANG environment variable), and if When has been translated into that language, that's what you'll get When's output will be in your language, and When will also expect you to use that language in your calendar file for the names of the months and the days of the week.

Some terminal emulators (aterm, ...) display accented characters as garbage, but others (mlterm, xterm...) can display them correctly. When checks the CW$TERM environment variable, and if it equals mlterm or xterm, then accented characters will be displayed. Otherwise, they are filtered out of the output. You can override this by putting a line like

        filter_accents_on_output = 0

or

        filter_accents_on_output = 1

in your ~/.when/preferences file. I'd be interested in hearing from any users who can suggest a better mechanism for this than attempting to interpret the CW$TERM variable.

On input, accents are allowed, but not required, e.g., in a French-language input file, the date 2005 Fev 17 could be given with an accented e or an unaccented one, and either will work. The input file and command-line options can be encoded in UTF-8, or plain ASCII (which is a subset of UTF-8). If an input month or day of the week does not match any of the ones for your language, then When will try to interpret it as English instead.

You can put a line like

        language = fr

in your preferences file to set your language, or supply the --language option on the command line, but that's not necessary if your CW$LANG environment variable is set correctly.

Each line consists of something like this:

        variable = value

Whitespace is ignored everywhere except inside the value. Variable names are case-insensitive. Blank lines are ignored.

A useful command to have your shell execute when you log in is this:

        when --past=0 --future=1

To print out a calendar for a full year to come:

        when --past=0 --future=365 c

Your calendar doesn't do you any good if you forget to look at it every day. An easy way to make it pop up when you log in is to make your .xsession or .xinitrc file look like this:

        /usr/bin/when --past=0 --future=1 &>~/when.today
        emacs -geometry 70x25 -bg bisque ~/when.today &
        startkde

The .xsession file is used if you have a graphical login manager set up on your machine, the .xinitrc if you don't. In this example, the first line outputs your calendar to a file. The complete path to the When program is given, because your shell's path variable will not yet be properly initialized when this runs. The second line pops up a GUI emacs window, which is distinctively colored so that it will catch your eye. The last line starts your window manager, KDE in this example. Whatever window manager you use, just make sure to retain the preexisting line in the file that starts it, and make sure that that line is the very last one in the file.

Besides testing w, the day of the week, you can also test the variables y, m, d, and j, which stand for the year, month, day of the month, and modified Julian day number. You can specify months either as numbers, m=2, or as names in your language, m=feb. You can also use the logical operators & (and) and | (or). The following example reminds you to pay your employees on the first and fifteenth day of every month:

        d=1 | d=15 , Pay employees.

The following two lines

        * dec 25 , Christmas
        m=dec & d=25 , Christmas

both do exactly the same thing, but the first version is easier to understand and makes the program run faster. (When you do a test, When has to run through every day in the range of dates you asked for, and evaluate the test for each of those days. On my machine, if I print out a calendar for a whole year, using a file with 10 simple tests in it, it takes a few seconds.) Parentheses can be used, but nested parentheses are not allowed. There is a not operator, !:

        w=fri & !(m=dec & d=25) , poker game

There is a modulo operator, %, and a subtraction operator, -. Using these, along with the j variable, it is just barely possible for When's little parser to perform the following feat:

        !(j%14-1) , do something every other Wednesday

The logic behind this silly little piece of wizardry goes like this. First, we determine, using the command `when j --now=2005 jan 26', that the first Wednesday on which we want to do this has a Julian day that equals 1, modulo 14. Then we write this expression so that if it's a Wednesday whose Julian day equals 1, modulo 14, the quantity in parentheses will be zero, and taking its logical negation will yield a true value.

The operators' order of priority is like this:

        = < > <= >= %      high
        & | ! -            low

Within each group of operators, priority and associativity are undefined.

$LANG to automatically detect the user's language

$TERM to try to figure out of the terminal emulator can display accented characters

$HOME/.when/calendar - The default location for the user's calendar (pointed to by the preferences file)

$HOME/.when/preferences - The user's preferences.

When's web page is at

        http://www.lightandmatter.com/when/when.html   ,

where you can always find the latest version of the software. There is a page for When on Freshmeat, at

        http://freshmeat.net/projects/when/   ,

where you can give comments, rate it, and subscribe to e-mail announcements of new releases.

The parser for fancy expressions should accept nested parentheses. In general, this part of the parser is poorly engineered, and will therefore be difficult to maintain and extend. It really should be rewritten from scratch.

When was written by Ben Crowell, http://www.lightandmatter.com/personal/. This man page was based on Bryce Harrington's man page for inkscape.

Copyright (C) 2003-2005 by Benjamin Crowell.

When is free software; you can redistribute it and/or modify it under the terms of the GPL, or, optionally, Perl's license.