This version of etm is no longer being actively maintained. A newer, second generation, version of etm is available at etmtk.

etm provides a simple, intuitive format for using plain text files to store data, a command line interface for viewing events and tasks in a variety of convenient ways and a cross-platform, wx(python)-based GUI for creating and modifying events and tasks as well as viewing them. Displayed items can be grouped by year, month, day, week number, quarter, context, keyword, location, user, file and/or priority and can be filtered in comparable ways. The display shows the number of items and time totals broken down by group headings. A display of busy and free times is also supported. Alarms are supported for events and repetition for both events and tasks in a powerful and flexible manner.

Quick completion of entry fields. When creating or modifying an item, enter '@c' and press Shift and Space to select from a list of all your previously used contexts or enter '@c er' and press Shift and Space to select from contexts beginning with 'er'. Quick completion also works after @k for keywords. When entering viewing options, quick completion can also be used after '-c' and '-k'.

Tab completion from view option histories. When entering options for main, item, busy or ledger views, select from a list of previously used option strings.

View items sorted by date, project, context or keyword.

Specify a list of minutes prior to an event at which to trigger early warning alerts.

Have alerts make spoken announcements and/or pop up displays using either the internal alert mechanism or one of your platform tools, e.g., growl on OS X or notify-send on Linux. (Alerts are only triggered when the etm GUI is running.)

Run arbitrary system commands at scheduled times. (Commands are only triggered with the etm GUI is running.)

Limit the display to any combination of events, actions, tasks, finished tasks, tasks whose begin dates have arrived, tasks waiting for completion of prerequisites and notes.

Export the items which satisfy the other item view criteria in iCalendar format.

Export the items which satisfy the other item view criteria in CSV (comma delimited) format.

See schedules of busy and free times for a range of dates. Limit displayed free times to certain hours each day, .e.g., 8:00a-5:00p, and to periods of at least a minimum number of minutes in duration and with a minimum number of 'wrap' minutes on either end.

Make records of expenditures of your time using the built-in timer and then use date, context and keyword to categorize them.

Use ledger (time reports) to see how your time has been used. Compute totals using any combination of date, context and keyword.

View the queue of coming alerts for the current day. The next alert is always displayed in the etm gui status bar.

Specify a number of days prior to the due date to be reminded to begin a task.

Automatically keep complete records of the dates when tasks were completed.

Dates and calendars use locale settings and thus should appear in your native language. Other settings determine the first day of the week and the words and phrases used in displays and alerts.

Pop up a twelve month planning calendar. Use Left and Right arrows to shift backward and forward a year at a time.

Calculate dates from the command line or by pressing F5 in the gui. For example:

Making Getting Things Done easier is etm's goal. Getting Things Done, commonly abbreviated as GTD, is an action management method, and the title of a extremely popular book by David Allen. GTD rests on the common sense notion that with a complete and current inventory of all commitments, organized and reviewed in a systematic way, the mind is freed from the job of remembering everything that needs to be done, and can focus on actually performing those tasks.

Three observations are critical:

Projects usually involve a series of steps, some of which must be carried out consecutively, e.g., parts must be acquired before assembly can begin.

The steps of a project are carried out in a context which may vary from step to step, e.g., parts may be acquired in the context 'errands' but assembly may be in the context 'workshop'.

While focusing on projects is great for planning, for actually doing things it would be more convenient to focus on context so that, for example, you could see all actions from all projects with context 'errands' before you drive off. To focus on what needs to be done, it would also be useful to be able to hide actions that are not yet available so that, for example, 'assemble parts' is not displayed until 'acquire parts' is complete.

GTD thus requires convenient methods for:

planning:

storing and organizing all the bits.

acting:

displaying just the information you need, when you need it.

reviewing:

checking the status of all items your projects.

etm allows you to store and organize your commitments using a simple,
intuitive format using plain text files. Tasks can be entered in an 'outline
format' in which which parent tasks are treated as prerequisites for their
lower level offspring tasks.

Your commitments can be viewed grouped and sorted by date, context, keyword,
location, priority or project. Using the outline groupby option '-g F' you can
check the status of all items in your projects regardless of their due
dates.You can hide finished tasks, or waiting tasks, or events. You can display
only items whose contexts or keywords match a given regular expression. You can
display busy and/or free times for an arbitrary period. You can prepare a
ledger view of your time broken down by any combination of date, keyword,
and/or context. You can export matchingitems in vCal/iCal format.

In short, etm makes it easy for you to store and organize all the bits and to
display just the information you need, when you need it.

The way in which data is stored and manipulated internally has been
completely rewritten. The result is much, much faster performance in both
the GUI and the interactive CLI.

The main GUI view now uses an outline tree format with quick navigation
and the option to expand or collapse branches. Press Ctrl-Y (yank) and the
selection is copied to the system clipboard. Similarly, Ctrl-V exports the
selection in vCal format to the clipboard, Ctrl-F exports the selection in
vCal format to a file and Ctrl-P opens a preview of the branch for
printing. These operations omit portions of branches which are are
collapsed.

Support for interactive use has been added to the CLI. Enter a command at
the prompt and the results are displayed instantly followed by another
prompt.

The command structure for both the GUI and the CLI has been simplified.
There are now only two commands, one for outline view and one for busy
view. The fuctionality of the old ledger and report views is now available
within the outline view.

Improved 'cloning' in the GUI. Say a task is selected and 'a' is pressed
to create an action. Then the entry area will automatically be populated
with all the relevant fields from the selected task. A similar thing
happens whatever type of item is being created and whatever type of item
is selected. Want to finish a task and record the time, for example? Just
select the task, press 'a' and an action timer will be started with all
the relevant fields from the task already entered.

You can now start an action timer with a starting time. Say you're working on
something and 15 minutes after you start you decide to create an action.
Press 'a' to create an initial entry for the action, add '@e +15' to the
options, press Shift-Return to save and the timer will start with 15 minutes
already elapsed.

Improved sorting/grouping using the '-g' (groupby) option in the outline
view. For example, the default

-g ((y,m,d),)

groups and sorts items by year, month and day to give output like

Fri Jun 3 2011 (17) 3.5h

3:00p Conference
... 16 other items for June 3

Sat Jun 4 2011 (3) 1.0h

... 3 items for June 4

As another example, suppose keywords have the format 'client name:project
name'. Then

-g (k1, (y, q, m), k2)

would group and sort by client, then by year, quarter and month combined
and finally by project to give output such as:

client 1 (3) 1.5h

2nd quarter 2011 Jun (3) 1.5h

project E (3) 1.5h

... 3 items for 'client 1:project E'

The old ledger functionality is now built-in to the outline view. Note in
the examples above that '(number of included items) total time' is
automatically appended to each node.

A final groupby option is to use '-g F' to group and sort by project F)ile.
When this option is used other groupby and begin and end date options are
ignored to show all items outlined by project file.

Examples:

show all your notes outlined by project file:

-g F -o !n

show all your unfinished tasks organized by project file:

-g F -o !ut

The details option in outline view makes it possible to limit the output
to just the group headings and totals using '-d 0' or to include more
detail in the output, say l)ocations and n)otes using '-d ln'. The
default, '-d 1', includes the items (leafs) themselves but omits the item
details.

No more 'done' files. Completion (finish) dates are now stored within the
relevant task.

No more reminder files. Reminders are just events with starting time(s)
and zero extent. [Actually, actions are just events with extent but
without starting times, but for a variety of reasons are treated
separately.]

Monthly files are no longer rotated. Prior to version 846, etmrc had option settings that determined whether or not monthly files were created and rotated.
Suppose, for example, that 'rotate_actions = True' and that it is currently July 2011. Then previously etm would would have created '07_actns.text' in the path for 'etmActions', if it didn't already exist and, by default, actions created during July would have be written to this file. Similar files would have been created and become the defaults as subsequent months arrive. Then when July 2012 rolled around, '07_actns.text' will have been moved to '.2009-02_actns.text', where it would be ignored by etm, and and a new '02_acnts.text' would have been created. A similar thing would have happened when 'rotate_events', 'rotate_notes' and/or 'rotate_tasks' is true.

Now monthly files are created within a yearly directory and are no longer rotated. E.g., if it is currently July, 2011, then etm will create the file '07_actns.text' in the '2011' subdirectory of the path of 'etmActions', if it doesn't already exist, and set this to be the default for action entries created in July. When July, 2012 rolls around, '07_actns.text' will be created in the subdirectory '2012' of the path for 'etmActions' and the file for 2011 will be left untouched.

Two starting etm data files will automatically be created for new users of
etm and those upgrading from pre 800 versions:

~/.etm/etmdata:
usholidays.text # new users and those upgrading from pre 800 versions
etm-examples.text # new users only

Both contain examples of etm usage and can be deleted when no longer
useful. The first, as the file name suggests, contains common US holidays.
The second contains a variety of examples of events and tasks the dates of
which are set relative to the date that e.py or e.pyw was run for the
first time. Since both e.py and e.pyw display the current week on startup,
you will see a variety of items displayed and even an alert scheduled to
be triggered within the next few minutes.

The @n (note) field for actions, events, tasks and notes can span more
than one line. Within the note field newlines and leading whitespace
are preserved to permit some formatting of field contents. In all other
fields, consecutive whitespace characters, including new line characters,
will be converted to a single space.

The @f field can have more than one finish date - this eliminates the
need for done files for repeating tasks and the need for adjusting the
@d date for the task on completion.

In tasks, '-' and '+' replace '.' and '_', respectively.

The @p field in actions is replaced by @e for consistency with events and
@p is now used for priority. The @e field is now interpreted as the extent
or duration of the action or event. When entering a value for @e in an
event with a single starting time in the GUI, the ending time can still be
entered but it will automatically be converted to +H:MM format. In all other
circumstances, the value must be entered either in +M (integer minutes) format
or in +H:MM (hours and minutes) format.

The @s field for events now allows for a list of starting times. E.g.,

office hours @s (10a, 1p, 4p) @e +60 ...

describes three events: 10am-11am, 1pm-2pm and 4pm-5pm.

The @l field for include has been replaced by @+ and @l is now used for
location. The @x field which was used for exclude in repeating items has
been replaced by @- and @x is no longer used. Using @- for exclude and @+
for include seems more intuitive.

In addition to hierarchial keywords using @k, etm now supports
non-heirarchial tags using @t. Either a single tag or a list of tags in
parentheses can be entered. Items can be filtered by location and tag.
Using

-t tag a -t tag b

for example, output would be limited to items which have both 'tag a' and
'tag b'.

There is a new @U field for user. Items can be filtered by user.

There is a new @C count field for repetitions. Using @C 3, for example,
would generate only the first three items from the recurrence rule.

There is a new @S setpos field for repetitions. E.g.,

payday @d 2010-07-01 @r m @w (MO,TU,WE,TH,FR) @m (23,24,25) @S -1

would repeat on the last weekday of each month that falls on or before the
25th.

Users of etm versions prior to 800

Installing the new version of etm will not affect either your configuration
files or your data files.

Configuration settings are now stored in '~/.etm/etmrc' instead of
'~/.etm/rc' and data files, by default, are stored in '~/.etm/etmdata'
instead of '~/.etm/data'. Additionally, data files now use the extension
'.text' instead of '.txt'.

The first time you run either e.py or e.pyw, your
existing '~/.etm/rc' file will be read (not changed) to determine the path(s)
to your existing data files. These data files will then be copied (not
changed) to '~/.etm/etmdata' with the relative paths preserved. (Your hidden
log, backup and archive files will not be copied.) The newly copied data
files will then be updated automatically to conform to the new format and
their extensions changed from '.txt' to '.text'. Finally a new '~/.etm/etmrc'
file will be created for you using default settings. Note that you will need
to copy any custom settings from your existing '~/.etm/rc' to the new
'~/.etm/etmrc' for them to take effect.

If you need to update old files after you have run e.py, you can use the provided python script, 'old2new.txt'. Run

The current date and time is displayed at the left. This is
followed by the interval of days currently being displayed and
an entry area which permits a case-insensitve search for all
items matching a regular expression. Matching items are listed
in the outline panel below.

Monthly calendar

The color of each month day number reflects the number of
minutes of scheduled events for that date. The days of the
currently selected week (the selected day and the six following
days) are highlighted.

With the focus in the calendar, the right and left arrow keys
change the selection forward and backward one day at a time.
Down and up arrow keys change the selection forward and backward
one week at a time and Page Down and Page Up change the
selection one month at a time.

Busy panel

The periods of schduled events for the selected days in calendar
are highlighted. Clicking on a highlighted area will select the
corresponding event in the outline panel and double clicking
will open the event for editing in the details panel.

Outline panel

This panel displays data reflecting the current options in
outline form. When an item is selected, the item's details are
displayed below in the details panel.

Details panel

When an item is selected in the outline panel, the item's
details are displayed here.

Additionally, this area is used to edit exising items, to create
new items and to set the options for the outline panel display
and for busy reports. See Options for Actions, Events, Notes and
Tasks and Options for Outline and Busy Views for details.

Press Shift-Return or Ctrl-S to process the contents or press
Escape to cancel.

Status Line

At the left, the status line displays a permanent reminder that
pressing F1 activates the help system. If one or more alarms is
in the queue for the current date, then the time of the next
scheduled alarm follows. This is followed by a list of the
current display options. The remaining space is used to display
a variety of information. If a timer is running for an action,
for instance, then the name of the action and the current
elapsed time and status (running or paused) is displayed.

A record of the time-consuming action required to complete a
task or participate in an event. Actions are not reminders,
they are instead records of how time was actually spent.
Action lines begin with a '~' character.

Event

Something that will happen on a particular day (or days)
and, perhaps, at particular times. Alerts are optional for
events with starting times. Event lines begin with a '**'
character.

Note

A record of some useful information. Note lines begin with a '!'
character.

Task

Something that needs to be done. It may or may not have a due
date. Task lines begin with one or more '-' or '+' characters.

Etm data files begin with a 'project line' that gives the project title and,
perhaps, options. Items follow with each item occupying one or more lines. Each
item begins with '~', '*', '!', '-' or '+' as the first character on the line,
followed by the title of the item and then field keys and values. The item
continues either until the file ends or another line is found that begins with
'~', '*', '!', '-' or '+'. E.g,

----------file begins-------------------------------------
the title of the project file
...
* my event title @d 8/23 @s 9a @n A note for my event that
continues on the next line.
...
----------file ends --------------------------------------

See Options for Actions, Events, Notes and Tasks for details.

Note that item options added to the project line become the
defaults for each of the items in the same file. Suppose, for
example, that the project file concerns 'Project A' for client 'John
Smith'. Then adding '@k Smith, John:Project A' to the project line
would set the client and project keyword for every item in the file.

To create a new event, press 'e' (or '*') and the details bar will
be focused and ready for your entry.To see how this works, create a
test entry such as

* test event @s 3p @e 4p

and press Shift and Return at the same time to record your event.
You will then be prompted for a file to store the entry. Before you
choose a file, drag the file selection dialog to one side and notice
that your entry has been changed to something like

* test event @d 2011-06-25 @s (3:00p) @e +1:00 @z Europe/Paris

with the starting time expanded, the ending time replaced with the
duration of the event and with the current date and local timezone
added.

Creating an action (press 'a' or '~'), a note (press 'n' or '!') or
a task (press 't', '-' or '+') is similar.

An event without either a starting time or an extent (duratation) is
regarded as an all day event. All day events are displayed at the
top of the daily schedule.

An event with one or more staring times but without an extent is
regarded as a reminder. E.g.,

* test reminder @d 6/25 @s (10a, 2p, 4p) @a (15, 0)

would create a reminder for 10:00am, 2:00pm and 4:00pm on June 25
with alerts to be triggered at both 15 minutes before and at the
time of the reminder. Reminders, even with multiple starting times,
are displayed only once in the daily schedule.

An event with one or more starting times and an extent is treated
as a scheduled event. Each starting time is displayed on the daily
schedule and the corresponding periods are displayed in the busy
panel.

An action might be regarded as an event with an extent but
without a starting time but since actions are important for uses such
as time billing, they are treated as a separate type. When an action
is created by pressing either 'a' or '~', you can provide an initial
entry and then press Shift-Return. A timer will then be started
which can be paused and restarted by pressing 'a'. A reminder will
be sounded periodically to remind you when the timer is running. You
can press 'A' to stop the timer and make final changes to the action
entry. The total elapsed time will be entered automatically.

A note is created by pressing either 'n' or '!. You could,
for example, use notes to keep a daily log or diary. As with other
items, new lines and other white space within a field are preserved
and can be used for rudimentary formatting.

A task is created by pressing either 't', '-' or '+'. A task
without an "@d" entry is regarded as a floating task and
always appears to be due on the current date. A task with an "@d"
entry is treated as being due on the specified date. If unfinished,
it will appear on the daily schedule for the due date. If it becomes
past due then it will also appear on the daily schedule for the
current date with a reminder of the number of days it is past due.
Etm not only can nag you about past due tasks, it can also alert you
to an upcomming due date as well. E.g.

- take out trash @d 6/1 @r w @w FR @b 1 @o s

would remind you to put out the trash each Friday and, because of
the "@b 1" entry, you would be notified of this beginning one day
before the due date. The "@o s" in this entry, by the way, means
that when the task is (o)verdue, etm should (s)kip the nagging and
simply inform you of the next due date.

When a task is completed, it will appear in the daily schedule for
the date it was finished with an indication that it has been
completed.

For GTD (Getting Things Done) usage. Typical contexts
include 'home', 'office', 'phone', 'computer' and 'errands'.
If you are about to run errands, for example, you could use
the outline display option -c errands to show
only items with the context 'errands'.

@k KEYWORD

For time billing. One pattern of usage would be to use
keywords with the format 'client:project'. Then the outline
display option -g (k1, (y,m), k2) would group and
total times first by k1 (client), then by year and month
combined and finally by k2 (project).

@l LOCATION

This field is supported when exporting in vCal format.

@p PRIORITY

This field is supported when exporting in vCal format. Note
that etm's integer priorities may be converted by some
applications. iCal, for example, makes the following
conversions:

etm iCal
----- ------
1-4 High
5 Medium
6-9 Low

@t TAGS

This field is exported as 'categories' in vCal format.
Multiple tags can be used when separated by commas and
enclosed in parentheses.

@U USER

For multiuser application. This field could be used to
distinguish responsibility for billing times or task
completion.

Items can be grouped and/or filtered by any combination of these
classifiers and additionally by the name of the file and by the
title of the project (from the first line of the file). For details of these
and other options see Options for Outline and Busy Views.

Similarly, in fields calling for a time, entering '6p' would
give after parsing '06:00PM' and so would '18:00'.

A further option is available when entering the extent, @e, for
an event. The extent can be specified as the duration or extent
of the event by preceeding the entry with a plus sign or, for
events with a single starting time, by the ending time of the
event. For example, all of the following are equivalent:

Alerts for an event or reminder are set by adding an '@a' field
to the event, e.g.,

* phone conference with CR @d tue @s 2p @a (15, 5)

would set alerts for 15 minutes before the event and 5 minutes
before the event. What happens when an alert is triggered is
determined by the setting for 'alertcmd' in '~/.etm/rc'. With
the default setting

alertcmd = ''

a message would be displayed with the current time and the text
of the message.

(all one one line) to have the message both spoken and displayed
using growl. On linux systems with 'notify-send' (provided by
libnotify-bin), a warning sound followed by a 5 second popup
display of the alert message could be produced with

More generally, any command that will accept a string argument
could be used.

Anniversary Substitutions

When items are processed whose titles contain a string of the form !YYYY!,
the string will be replaced with N## where N is the number of years from
YYYY until the current year and ## is either 'st', 'nd', 'rd', or 'th'. For
example, on August 23, 2010, the event

* Will's !1985! birthday @d 2010-01-01 @r y @M 8 @m 23

would be displayed as

Will's 25th birthday

Limitations

In displays when grouping by date, etm will only display an item
or trigger an alert on the date of its starting time. This
means, for example, that the event

* event @d 2010-12-01 @s 23:00 @e +2h

would only display on December 1 even though the event lasts
until 1:00 on December 2. Similarly

* event @d 2010-12-01 @s 1:00 @a (90, 30)

would trigger an alert at 0:30 on 12/1 but would not trigger an alert at
23:30 on 11/30.

Dates and times in etm either have time zone information associated
with them or are treated as 'naive' date times. The treatment of
date times depends upon whether or not the item includes an @z ZONE
entry and, if it does, the value of ZONE. There are two
possibilities for lines in the etm data files:

The item

does not have an @z ZONE entry or

the item does have an @z ZONE entry but the value of ZONE is 'none'.

Item date times are interpreted as naive and are displayed unchanged.

E.g., the events:

* event @d 2010-11-28 @s 17:00
* event @d 2010-11-28 @s 17:00 @z none

would both be interpreted as starting at 17:00 on Nov 28 no
matter what the time zone of the user's system. Some calendar
applications would refer to these as floating events.

The item has an @z ZONE entry and the value of ZONE is not 'none'.

Item date times are interpreted as being in ZONE time and would
be displayed as local date times for the user's system time zone.
E.g., the event:

* event @d 2010-12-01 @s 12:00 @z Pacific/Auckland

would be interpreted as starting at 12:00 December 1
Pacific/Auckland time and, if the users time zone were
US/Eastern, would be displayed as starting at 18:00 on November
30.

When creating new items in etm, time zone information that you
enter, provided that it is valid, will be left unchanged. This
includes '@z none'. What happens when you create an item without an
'@z' entry depends upon the value of 'auto_set_timezone' in your rc
file. If 'True' (the default), then '@z ZONE' will automatically be
appended to your entry with ZONE equal to your local time zone. If
'False', then your entry will be saved as it is and its dates and
times will subsequently be interpreted as naive.

When entering zone information in etm, completion is available.
Suppose, for example, that you have entered

* event @d 12/1 @s 12 @z US

and press Ctrl-Space with the cursor after 'US'. Then etm would
display a pop-up list of possible completions from 'timezones' in
your rc file for your selection. With the default value of
'timezones', this list would include 'US/Alaska', 'US/Central',
'US/Eastern' and the others that begin with 'US'.

Zone information in etm, other than 'none', automatically adjusts
for daylight saving. Consider, for example, the following two
events:

While both would display on the given dates as starting at 17:00,
this would be EDT for the first and EST for the second. This means
that when you change the date for a task with zone information, you
do not need to concern yourself with making adjustments for daylight
saving.

The values of 'due_hour' (0-23) and 'due_minute' (0-59) from your rc
file set the implicit times for tasks and other items without
starting times. These values have no effect unless '@z ZONE' is set
and ZONE is not equal to 'none'. The default, 'due_hour = 12' and
'due_minute = 0', corresponds to most expectations. E.g, a task that
is due at noon on November 30 in New York (12:00 11/30 EST), would
also be due on November 30 in London (17:00 11/30 GMT) and Honolulu
(7:00 11/30 HST), but would be due on December 1 on the other side
of the international date line in Tokyo (2:00 12/1 JST) and
Singapore (1:00 12/1 SGT).

A final groupby option is to use '-g F' to group and sort by project F)ile.
When this option is used other groupby and begin and end date options are
ignored to show all items outlined by project file.

Etm supports the use of case-insensitive, regular expression
matching when searching and when filtering by context, keyword,
location, priority, tag, user, file and/or project. E.g., an option
setting which included '-c errands' would limit the display to items
which contain 'errands' in the context field.

Alternatively, '-c !errands' would limit the display to items which
do not have contexts matching 'errands'. Note: when using the
command line the latter expression should be wrapped in single
quotes, e.g.,

e.py o -c '!errands'

An excellent introduction to the use of regular expressions is
provided by

www.duke.edu/~dgraham/ETM/LearningtoUseRegularExpressions.html

Skip down to 'Matching Patterns in Text: The Basics' and note that
the surrounding '/' delimiters are not needed in etm.

Entering a regular expession in the search bar of the GUI or passing the
expression as an option to outline view using '-s' works differently than the
filters described above in two ways:

1) Search applies to all items processed by etm. This means all undated items
and at least one occurance of all dated items are included in searches.
Filters, on the other hand, apply only to undated items and those between '-b
BEGIN' (default today) and '-e END' (default 6 days after BEGIN).

2) Search identifies items in which any field matches the expression. Thus
'-s smith' would match items that have 'smith' (case insensitive) in the
title, context, keyword, location, note or anywhere else. On the other hand,
a filter such as '-k smith' would only match items with 'smith' in the
keyword field.

In the GUI, press either 'a' or '~' to create an action, 'e' or '*' to create
an event, 'n' or '!' to create a note and either 't', '-' or '+' to create
a task. Optional (O) and required (R) fields are listed below.

Key

Value

Action

Event

Note

Task

Description

@d

DATE

R

R

O

O

a date (fuzzy parsed).

@b

BEGIN

O

an integer number of days before a task with a due date at which
to begin giving advance warnings of the upcomming due date.

@f

FINISH

O

a date or, for a repeating task, a list of dates in
parentheses, on which the task was completed (fuzzy parsed).

@s

STARTTIME

O

a time or a list of times in parentheses (fuzzy parsed). An
event without a start time is regarded as an all day event.

@a

ALERTS

O

an interger or a list of integer minutes in parentheses. Alerts
will be triggered at times corresponding the these numbers of
minutes before STARTTIME.

@A

ALTCMD

O

an alternative command to run when alerts are triggered instead
of the default. Accepts the same substitution strings as
alertcmd in the etm rc file.

@e

EXTENT

R

O

O

a integer number of minutes preceeded by a "+" (plus
sign). Optionally, an ending time (fuzzy parsed) can be given
for an event with a single starting time. An event with
one or more start times but without an extent is treated as a
reminder.

@n

NOTE

O

O

O

O

a string. Newlines and leading whitespace are preserved within
the body of the note.

@g

GOTO

O

O

O

O

a file path or URL, or a comma separated list of paths or URLs in
parentheses, to be opened using the system default application if
the user presses "g" when the item is selected. If a list is
given, a selection list will be provided from which to choose the
item to be opened.

@z

TIMEZONE

O

O

O

O

a time zone, e.g., "US/Eastern".

@l

LOCATION

O

O

O

O

a string.

@U

USER

O

O

O

O

a string.

@c

CONTEXT

O

O

O

O

a string.

@k

KEYWORD

O

O

O

O

a string which optionally contains colons, e.g, "@k
first:second:third:fourth". When grouping/sorting 'k1' would refer to
'first', 'k2' to 'second' and 'k3' to 'third:fourth'.

@p

PRIORITY

O

an integer in the range from 1 (highest priority) to 9 (lowest
priority).

a single character from "d" (daily), "w" (weekly), "m"
(monthly), "y" (yearly) or "l" (list) describing the frequency
at which the event or task repeats. This field
is always required for repeating items..

@i

INTERVAL

a positive integer interval at which the task repeats. E.g., "@r
w @i 3" would repeat every third week. Default: 1.

@u

UNTIL

a date at which repetitions should end (fuzzy parsed). Default:
none, i.e., repetitions continue forever.

a string or list of strings in parentheses from
"MO", "TU", "WE", "TH", "FR", "SA", "SU" or an integer or list
of integers from 0 (MO) through 6 (SU). Default: any weekday.
E.g., "@r m @w (MO(1), FR(-1))" would repeat on the
first Monday and the last Friday of each month.

@W

WEEKNUM

an integer week number or a list of week numbers from 0 through
53. Default: any week number.

@m

MONTHDAY

an integer month day number or a list of month day numbers from
1 through 31. Note that "@r m @m 31" would only repeat
on months that have 31 days but "@r m @m -1" would
repeat on the last day of every month. Default: any month day.

@M

MONTHNUM

an integer month number or a list of month numbers from
1 through 12. Default: any month number.

@+

INCLUDEDATES

a date or a list of dates to add to the dates that would
otherwise be generated by the recurrence rule. E.g., "@r m @m 1
@+ (Feb 5, Feb 7)" would repeat on the 1st of each month
and, additionally, on Feb 5 and Feb 7. Note that it is possible
with this field to specify specific dates for an item. E.g., "@r
l @+ (Feb 28, Jul 3, Aug 27)" would repeat only on the
three specified dates. When '@r l' (list) is used an entry for '@+
INCLUDEDATES' is required and an entry for '@d DATE' is optional.
Otherwise, an entry for '@d DATE' is required and an entry for '@+
INCLUDEDATES' is optional. Default: none.

@-

EXCLUDEDATES

a date or a list of dates to remove from the dates that would
otherwise be generated by the recurrence rule. E.g., "@r m @m 1
@- (Mar 1, Jun 1)" would repeat on the 1st of each month
except for Mar 1 and Jun 1. Default: none.

@S

SETPOSITION

a integer specifying the date from the list of dates that
would otherwise satisfy the recurrence rule. E.g., "@r m @w (MO,
TU, WE, TH, FR) @m (23, 24, 25)" would repeat on every
weekday that is a 23rd, 24th or 25th of the month. For June
2011, for example, this would include Thursday, June 23 and
Friday, June 24. By adding "@S -1", only the last of these,
Friday, June 24, would be included. Thus "@r m @w (MO,
TU, WE, TH, FR) @m (23, 24, 25) @S -1" would repeat on the
last weekday in each month that falls on or before the 25th.
Default: none.

@o

OVERDUE

either 'k' (keep), 's' (skip) or 'r' (restart). The
specification of how to handle due dates for repeating tasks.
This is explained below. Default: k.

A repeating task that is finished on its due date presents no
difficulty. But what if it's finished early or becomes overdue?
There are three options with etm:

@o k: Keep the current due date if it becomes overdue and use the
next due date from the recurrence rule if it is finished early. This
would be appropriate, for example, for the task 'file tax return'.
The return due April 15, 2009 must still be filed even if it is
overdue and the 2010 return won't be due until April 15, 2010 even
if the 2009 return is finished early.

@o s: Skip overdue due dates and set the due date for the next
repetition to the first due date from the recurrence rule on or
after the current date. This would be appropriate, for example, for
the task 'put out the trash' since there is no point in putting it
out on Tuesday if it's picked up on Mondays. You might just as well
wait until the next Monday to put it out. There's also no point in
being reminded until the next Monday.

@o r: Restart the repetitions based on the last completion date.
Suppose you want to mow the grass once every ten days and that when
you mowed yesterday, you were already nine days past due. Then you
want the next due date to be ten days from yesterday and not today.
Similarly, if you were one day early when you mowed yesterday, then
you would want the next due date to be ten days from yesterday and
not ten days from today.

In the GUI, press 'o' to set options for outline view or 'b' to set
options for busy view. Allowed options are indicated below by 'O'.

Outline

Busy

Description

-b

BEGIN

O

O

Date. Display items on or after this (fuzzy parsed) date.
A relative date can be entered, e.g., '-b -14' would set BEGIN to 14
days before the current date. Relative month expressions
can also be used so that, for example, '-b -1/1' would set BEGIN to
the first day of the previous month.

-e

END

O

O

Date or a plus sign followed by an integer. Display items before (but not on) this (fuzzy parsed) date or for this integer number of days starting with BEGIN. E.g., both '-b 7/1 -e 7/8' and '-b 7/1 -e +7' would include items for the seven days from July 1 through July 7. As with BEGIN, relative month
expressions can be used, e.g., '-b -1/1 -e 1' would include all
items from last month and '-b -2/1 -e -1/1' from the month before
last.

-g

GROUPBY

O

Available group/sort keys include y (year), m (month),
d (day), e (extent), w (week number in year), q (quarter number), c
(context), l (location), u (user), s (item type), k1, k2 and k3, (first,
second and all remaining keywords). A final groupby option is to use '-g
F' to group and sort by project F)ile. When this option is used other
groupby and begin and end date options are ignored to show all items
outlined by project file.
See the discussion under Grouping and Sorting in Overview for further
details.

-o

OMIT

O

O

String with characters from a (actions), b (task begin dates), d (all day
events), e (scheduled events), n (notes), r (reminders), f (finished
tasks), u (undated tasks), w (waiting tasks), p (past due tasks) and t
(active tasks), If OMIT begins with '!', then only show items with types
belonging to OMIT. Otherwise only show items with types not belonging to
OMIT. Only items with extents (actions and events) are relevant to busy
view.

-d

DETAILS

O

0, 1 or a string composed of item field keys or *. Display only group
headings if 0. If 1 show items (leaves) as well. If a string of field
keys, then open a print preview showing details corresponding to the
keys as well as the items. E.g., '-d ln' would open a print preview
showing items, their l)ocations and their n)otes. If '*' then show
details corresponding to all field keys. Default: 1.

-T

TOTALSFIRST

O

0 or 1. Display time totals before the group titles if
1. Otherwise after the group titles. Default: 0.

-s

SEARCH

O

O

Regular expression. include items, regardless of date, in which
any field value matches SEARCH (ignoring case). Prepend an
exclamation mark to include items which do not have any field values
matching SEARCH.

-c

CONTEXT

O

O

Regular expression. include items with contexts matching CONTEXT
(ignoring case). Prepend an exclamation mark to include items which do
not have contexts matching CONTEXT.

-k

KEYWORD

O

O

Regular expression. include items with keywords matching KEYWORD
(ignoring case). Prepend an exclamation mark to include items which do
not have keywords matching KEYWORD.

-p

PRIORITY

O

O

Regular expression. Include items with priorities matching PRIORITY.
For example, '-p [123]' would select items with the top three
priorities and '-p ![123]' would select items with priorities lower than
3 or no priority.

-t

TAG

O

O

Regular expression. include items with tags matching TAG (ignoring
case). Prepend an exclamation mark to include items which do not have
tags matching TAG. Multiple uses of this option are possible. E.g., use
'-t tag 1 -t tag 2' to show items with both 'tag 1' and 'tag
2'.

-l

LOCATION

O

O

Regular expression. include items with locations matching LOCATION
(ignoring case). Prepend an exclamation mark to include items which do
not have locations matching LOCATION.

-u

USER

O

O

Regular expression. include items with users matching USER
(ignoring case). Prepend an exclamation mark to include items which do
not have users matching USER.

-P

PROJECT

O

O

Regular expression. include items with projects matching PROJECT
(ignoring case). Prepend an exclamation mark to include items which do
not have projects matching PROJECT.

-f

FILE

O

O

Regular expression. include items with files matching FILE
(ignoring case). Prepend an exclamation mark to include items which do
not have projects matching FILE.

Display outline report using provided options.
Options:
-h, --help show this help message and exit
-b BEGIN_DATE Date. Display items beginning with this date (fuzzy parsed)
and continuing until END_DATE. Default: today.
-e END_DATE Date. Display items beginning with BEGIN and ending with this
date (fuzzy parsed). Default: BEGIN plus 6 days.
-f FILE Regular expression. Include items with project file names
matching FILE (ignoring case) within the BEGIN ~ END
interval. Prepend an exclamation mark, i.e., use !FILE rather
than FILE, to include items which do NOT have file names
matching FILE.
-P PROJECT Regular expression. Include items with project titles
matching PROJECT (ignoring case) within the BEGIN ~ END
interval. Prepend an exclamation mark, i.e., use !PROJECT
rather than PROJECT, to include items which do NOT have
project titles matching PROJECT.
-c CONTEXT Regular expression. Include items with contexts matching
CONTEXT (ignoring case) within the BEGIN ~ END interval.
Prepend an exclamation mark, i.e., use !CONTEXT rather than
CONTEXT, to include items which do NOT have contexts matching
CONTEXT.
-k KEYWORD Regular expression. Include items with contexts matching
KEYWORD (ignoring case) within the BEGIN ~ END interval.
Prepend an exclamation mark, i.e., use !KEYWORD rather than
KEYWORD, to include items which do NOT have keywords matching
KEYWORD.
-t TAG Regular expression. Include items with tags matching TAG
(ignoring case) within the BEGIN ~ END interval. Prepend an
exclamation mark, i.e., use !TAG rather than TAG, to include
items which do NOT have tags matching TAG. This switch can be
used more than once, e.g., use '-t tag 1 -t tag 2' to match
items with tags that match 'tag 1' and 'tag 2'.
-u USER Regular expression. Include items with user matching USER
(ignoring case) within the BEGIN ~ END interval. Prepend an
exclamation mark, i.e., use !USER rather than USER, to
include items which do NOT match USER.
-l LOCATION Regular expression. Include items with location matching
LOCATION (ignoring case) within the BEGIN ~ END interval.
Prepend an exclamation mark, i.e., use !LOCATION rather than
LOCATION, to include items which do NOT match LOCATION.
-p PRIORITY Regular expression. Include items with project titles
matching PRIORITY within the BEGIN ~ END interval. Prepend an
exclamation mark, i.e., use !PRIORITY rather than PRIORITY,
to include items which do NOT have priorities matching
PRIORITY.
-s SEARCH Regular expression. Include items containing SEARCH (ignoring
case) in the task title or note within the BEGIN ~ END
interval. Prepend an exclamation mark, i.e., use !SEARCH
rather than SEARCH, to include items which do NOT have titles
or notes matching SEARCH.
-o OMIT string. show/hide a)ctions, task b)egin dates, all d)ay
events, scheduled e)vents, f)inished tasks, n)otes,
r)eminders, u)ndated tasks, w)aiting tasks and/or active
t)asks depending upon whether omit contains 'a', 'b', 'e',
'f', 'n', `'r', 'u', 'w' and/or 't' and begins with '!'
(show) or does not begin with '!' (hide). default: none.
-g COLS A tuple of elements from y (year), m (month), d (day), s
(sort or type number), e (extent minutes), w (yearly week
number), q (quarter number), c (context), k1 (keyword 1), k2
(keyword 2), k3 (keyword 3), l (location), n (item name), f
(file name and line numbers), u (user), p (project name)
and i (id). For example, the default, -g ((y, m, d),), sorts
by year, month and day together to give output such as
Fri Apr 1 2011
items for April 1
Sat Apr 2 2011
items for April 2
...
As another example, -g ((y, q), m, d), would sort by year
and
quarter, then month and finally day to give output such as
2011 2nd quarter
Apr
Fri 1
items for April 1
Sat 2
items for April 2
...
A final option is to group by file path using '-g F'. Note
that if 'F' should not be combined with any other groupby
options.
-d DETAILS String. Controls the display of item details. With '-d 0',
item details would not be displayed. With '-d 1' (the
default), the prefix and title (description) would be
displayed. With '-d len', for example, a second details
line
would be appended displaying the item l)ocation, e)xtent
and
n)ote entries.
-T Boolian. Display minute totals at the beginning rather than
the end of the line.
-x VALUES Comma separated list of field keys. Export displayed items
in CSV (comma separted values) format to export.csv in the
'export' directory specified in the etm rc file. Values
exported for each item include 1) item id, 2) item type
number, 3) item description (title) and, in order, values
corresponding to the keys in VALUES. Possible keys include
y (year), m (month), d (day), e (extent minutes), p
(priority), w (week number), q (quarter number), c
(context), k1, k2, k3, (keywords 1, 2 and beyond), l
(location), u (user), P (project name), t (tags) and n
(note).
-v Export items in vCal/iCal format to export.ics in the
directory specified by 'export' in the etm rc file.

Item numbers are only displayed in the interactve version and can be toggled on and off with:

etm: numbers

The default value is given by 'show_nums' in your etmrc. Similarly, the use of colors in the display can be toggled on and off with:

etm: colors

The default value is given by 'use_colors' in your etmrc.

It is also possible to provide options on the command line to get a
non-interactive version. E.g.,

e.py o -g(k1, (y,m), k2) > report.txt

would write an output report directly to the specified file.

Finally, you can run

e.pyw

to open the wx(python) GUI interface and press F1 to see a list of available commands.

Alternatively, a shell script such as:

#!/bin/bash
e.pyw &

could be created and automatically invoked by your startup process. Under OS X, naming this file using the suffix 'command', e.g., 'etm.command', would allow you to add the file to your login items and/or add the command to your dock.

wxPython is being very actively developed and it is both easy and well worth the effort to update to the latest version. There are self-installing binaries for all common platforms. Just be sure to get one that matches your python version. (To check your python version run 'python -V' in a terminal.) I recommend getting the unicode version rather than the ansi version.

If you use either setup.py or easy_install to install etm, dateutil and vobject will automatically be installed along with etm. Otherwise, you can install them in the normal python way. Download, unpack, cd to the resulting directory and run 'sudo python setup.py install'.

etm can be installed in the normal python way: download, unpack the etm source in a temporary directory, open a terminal ('Command Prompt' in Windows), cd to that directory and then run:

sudo python setup.py install

Windows users can omit the 'sudo'. The temporary directory can then be removed. This will download and install any necessary supporting modules (dateutil, vobject), install the etm package in the 'site-packages' subdirectory of your python distribution and install the executable e.py in the 'bin' subdirectory of your python distribution.

If you have setuptools installed, you can skip downloading and use:

sudo easy_install -U etm

either to install etm or to update to the latest version.

Easy_install is part of the python package setuptools. To install it, download the appropriate egg file for your platform, e.g.,

setuptools-0.6c11-py2.6.egg.sh

Then cd to the directory containing the egg file and, if necessary, rename it to remove the '.sh' extension:

mv setuptools-0.6c11-py2.6.egg.sh setuptools-0.6c11-py2.6.egg

The last step is to run the (renamed) egg file as if it were a shell script:

sudo sh setuptools-0.6c11-py2.6.egg

Setuptools will install itself using the matching version of python (e.g. 'python2.6'), and will place the 'easy_install' executable in the default location for python scripts.

A standalone version, etm.app, is provided for Mac OS X users as a standard dmg file. Download this file, click on it and then drag etm.app to your Applications folder. Note that this application provides the gui version of etm but not the command line version.

If you would like to try etm out without installing the system files or if you don't have root privileges but would like to install etm for your own use, the process is simple. Unpack the etm source in a convenient directory, cd to that directory and then run

./e.py [options]

This does not require root privileges and will not install any system files but will create the user specific configuration, data and alert files mentioned below in your home directory. You could, of course, use aliases or symbolic links to these files and avoid even having to change to this directory, e.g., if these files are located in ETMDIR, then you could add these lines to your ~/.bash_profile:

alias e.py='ETMDIR/e.py'

replacing ETMDIR, of course, with the actual path. These aliases would then function in the way described under Command line usage below.

Users of etm versions prior to 800 can preview the new version by downloading
the new version of etm, upacking it into a temporary directory, opening a
terminal window, changing to the temporary directory and then running either
'./e.py' for the CLI version or './e.pyw' for the GUI version. This will
display your data using the new version without affecting your existing
installation in any way.

The directory '~/.etm' and the following files are created the first time you run e.py.

Test settings

If the current working directory contains a file named etmrc when e.py is run then configuration settings, including the setting for etmdata, will be taken from that file instead of ~/.etm/etmrc.

~/.etm/etmrc:

All configuration settings are kept in this file. It will automatically be created if it doesn't already exist and populated with default values. This configuration file is self-documented and can be freely edited. If you make changes you don't like you can simply erase the offending part, or even the entire file, and it will be recreated with defaults the next time you run e.py.

~/.etm/etmdata/:

Project files are, by default, kept in this directory and its subdirectories though the setting for etmdata can be changed in '~/.etm/rc'. It is automatically created and populated with the rotating project files for events and tasks for the previous and current months discussed in Monthly data files below.

~/.etm/export/:

Views exported in iCal or CSV format are, by default, kept in this directory.

When entering options for items in the GUI details panel, completion is
available for contexts, keywords and locations by pressing Ctrl-Space. E.g.,
if you are creating or modifying the event

* my event @c e| @d tue

and press Ctrl-Space with the cursor at the position indicated by '|', then
you will be able to select a context from a list of those beginning with 'e'.
Which contexts belong to this list depends upon the contents of 'context.txt'
and whether 'addFileContexts' is true or false.

~/.etm/contexts.txt

Contexts added to this file, one per line, will be available for Ctrl-Space completion. If 'addFileContexts = True', contexts used in your data files will also be available for Ctrl-Space completion.

~/.etm/keywords.txt

Keywords added to this file, one per line, will be available for Ctrl-Space completion. If 'addFileKeywords = True', keywords used in your data files will also be available for Ctrl-Space completion.

~/.etm/locations.txt

Locations added to this file, one per line, will be available for Ctrl-Space completion. If 'addFileLocations = True', locations used in your data files will also be available for Ctrl-Space completion.

The file specified by 'abbreviationsFile' in etmrc is a plain text file with
one abbreviation per line in the format "X|Y" where X is an alpha-numeric
string without spaces (the abbreviation) and Y is the replacement string.
Occurances of ":X:" in an etm action, event, note or task will then be replaced
by "Y", e.g., if abbreviations.txt contains the line "chtc|Chapel Hill Tennis
Club" then ":chtc:" in an event would become "Chapel Hill Tennis Club".

Many times it will be convenient to create a project file to hold a collection
of related items as in the illustrative case of the report. Often, however,
items will be created that are independent of one another. There is no need to
create separate project files in such circumstances. etm, in fact, will
automatically create files that can you can use for such independent items.

Suppose that it is currently July 2011. Then etm will automatically create
'07_actns.text' in the '2011' subdirectory of the path for 'etmActions' the
first time it is run. By default, actions created during July will be written
to this file. Similar files will be automatically be created and become the
defaults as subsequent months and years arrive. A similar thing happens for
events, notes and tasks.

If you want to remove obsolete data entries, you could, of course, delete the
file or directory or you could simply change the name of a file or directory to
begin with a '.' (period) and, as a hidden file, etm would ignore it. On the
other hand, you can use the values of 'year_beg' and 'year_end' in your etmrc
file to control which items etm displays. Etm always processes all, non-hidden
'*.text' files in its data directories. But it only loads (stores in memory)
(1) undated items, (2) dated items with occurances (dates) between January 1 of
the year that is 'year_beg' (default 1) years before the current year and
December 31 of the year that is 'year_end' (default 5) years after the current
year and, for dated items without occurances within this period, (3) the first
occurance after and the last occurance before this period. Thus at least once
occurance of everything is available, but repetitions are limited to the given
period.

A backup is made of any file before any action by etm would change it. E.g.,
before a task in '02_tasks.text' would be marked finished, the file would
first be copied to '.02_tasks.bk1'. If '.02_tasks.bk1' already exists, it
would first be moved to '.02_tasks.bk2'. Similarly, if '.02_tasks.bk2' already
exists, then it would be first be moved to '.02_tasks.bk3' and so forth. In
this way, up to 'numbaks' (3 by default) rotating backups of are kept with
'.bk1' the most recent.

This program is free software; you can redistribute it and/or modify it under
the terms of the GNU General Public License as published by the Free Software
Foundation; either version 3 of the License, or (at your option) any later
version.

This program is distributed in the hope that it will be useful, but WITHOUT
ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.