event and task manager

Overview 

GTD with etm 

an illustrative project 

contexts and keywords 

Viewing tasks, events and actions 

Display options 

Display dates for tasks 

Regular expression (regex) matching 

Searching 

Export to iCal/vCal 

Export to CSV 

Project details 

Events 

Reminders 

Alerts (for events and reminders) 

Tasks 

Actions 

Notes 

Anniversary substitutions 

Goto links 

Fuzzy parsing of dates and times 

Due dates for repeating tasks 

etm 

event and task manager 

Contents 

1

Using the date calculator 

Installation/Updating 

OS X users 

Temporary / local installation 

Files created and used by etm 

Configuration files 

Rotating data files 

Pickle files 

Command line usage 

Example Files 

License 

Overview 

etm is an acronym for Event and Task Manager. It provides a simple, intuitive format for 

using plain text files to store data, a command line interface for viewing stored information 

in a variety of convenient ways and a cross-platform, wx(python)-based GUI for creating and 

modifying items as well as viewing them. Displayed items can be grouped by date, context, 

keyword or project and can be filtered in various ways. A display of busy and free times is 

also supported as is a ledger view of time spent that is suitable for client billing. Alarms 

are supported for events and repetition for both events and tasks in a powerful and flexible 

manner. 

GTD with etm 

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: 

1. 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. 

2

2. 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’. 

3. 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. 

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’ which displays not just your tasks, 

but also your events, actions, notes and reminders. Your commitments can be viewed grouped 

by date, context, keyword or project. 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 gives you access to just the information you 

need, when you need it. 

an illustrative project 

Suppose there is a department meeting at noon on Friday, March 13, 2009, that you want to 

remember. With etm, the following text file would accomplish this: 

---- file begins ----------------report 

* staff meeting @c work @d 2009-03-13 @s 12:00p 

---- file ends ------------------- 

The asterisk before ’staff meeting’ means that this line describes an event. The staff meeting 

would now appear on your agenda for March 13 associated with the project report and the 

context work. If you would like to be alerted 15 and 10 minutes before the meeting and be 

reminded to bring a report with you to the meeting, then change the event line to: 

* staff meeting @c work @d 2009-03-13 @s 12:00p @a 15, 10 @n bring report 

3

To make things more interesting, suppose that you are responsible for preparing the report 

and presenting it at the meeting. The following: 


@c work @d 2009-03-13 

* staff meeting @s 12:00p @a 15, 10 @n bring report 

. prepare report @b 1 

---- file ends ------------------- 

would remind you of this task one day before the meeting. 

Still more interesting, suppose you need sales data from Joe and inventory data from Mary to 

prepare the report. Just add two more tasks: 


@c work @d 2009-03-13 


. get sales from Joe @b 2 

. get inventory from Mary @b 2 

. prepare report @b 1 

---- file ends ------------------- 

Tasks can begin with one or more periods or underscores. The tasks can be regarded as 

an outline with the number or periods or underscores determining the level and thus the 

prerequisites of the task. Tasks at the same level in a branch of the outline can be completed 

in any order but none can be started until all higher level tasks in the same branch have been 

completed. The single periods before Joe, Mary and report mean that these tasks are at the 

same (first) level and thus can be completed in any order. 

If we need to complete Mary before beginning report then the following should be used: 


@c work @d 2009-03-13 


. get sales from Joe @b 2 

. get inventory from Mary @b 2 

.. prepare report @b 1 

---- file ends ------------------- 

The two periods before report mean that it is nested under Mary and thus that Mary must be 

finished before report can begin. 

If we really need to complete both Joe and Mary before beginning report then we can use 

underscores instead of periods before Joe and Mary to add both to the prerequisites for report: 

4


@c work @d 2009-03-13 


_ get sales from Joe @b 2 

_ get inventory from Mary @b 2 


---- file ends ------------------- 

Finally, the following slight modification would cover such meetings when they repeat on the 

second Friday of every month: 


@c work @d 2009-03-13 @r m @w FR(2) 


_ get sales from Joe @b 2 

_ get inventory from Mary @b 2 


---- file ends ------------------- 

What could be easier? 

Here’s a slightly more complicated example for a course I’m teaching (lines beginning with # 

are comments): 

---- file begins ----------------- 

ECO 207 

# classes meet on Tu and Th, 2:50-4:05p (75 minutes) from 1/8 until 4/21 

# save for the midterm on 2/24 and spring break on 3/10 and 3/12 

* ECO 2O7 @d 2009-01-08 @c class @r w @w (TU, TH) @s 2:50p @e 75 

@a (10, 2, 0) @u 2009-04-21 @x (2009-02-24, 2009-03-10, 2009-03-12) 

# exams 

* ECO 2O7 Midterm @d 2009-02-24 @s 2:50PM @e 75 @a (10, 2, 0) @c exam 

* ECO 2O7 Final @d 2009-04-27 @s 2:00PM @e 180 @a (10, 2, 0) @c exam 

# preparation 

. prepare syllabus @d 2009-01-08 @b 7 @c mac 

. prepare midterm @d 2009-02-24 @b 7 @c mac 

.. grade midterm @d 2009-02-25 @c desk 

... record midterm grades @d 2009-02-26 @c mac 

. prepare final @d 2009-04-27 @b 7 @c mac 

.. grade final @d 2009-04-28 @c desk 

... record course grades @d 2009-04-29 @c mac 

---- file ends ------------------- 

5

contexts and keywords 

All item types in etm support the use of both context (@c) and keyword (@k) entries. The 

context field is intended to support the standard use of context in GTD, e.g., ’errands’, ’phone’, 

’computer’, ’office’ and so forth. Using 

e.py i -g c 

shows your items grouped by context or, if you’re about to run some errands you could use 

e.py i -c errands 

to show only the items with the context ’errands’. You could, of course, choose a completely 

different use for the context field. 

The keyword field in etm has no natural counterpart in GTD. One possibility that might be 

useful would be to differentiate between personal, ’@k per’ and work related, ’@k wrk’, items. 

Then 

e.py i -k wrk 

would show only your work related items. Another possibility if you have, say, projects ’A’ 

and ’B’ for a client named ’Jones’ would be to use ’@k Jones:A’ and ’@k Jones:B’. Then 

e.py i -k Jones 

would show all your ’Jones’ items and 

e.py i -k Jones:A 

would show only the items relating to Jones’ project A. Similarly, 

e.py l -i 0120 -k Jones 

would prepare a ledger view showing time spent on items with the keyword Jones broken down 

by date and project. 

6

Viewing tasks, events and actions 

Display options 

Main view is the opening view of the etm and its interactive interface. It displays a monthly 

calendar in the top, left-hand corner with dates color coded to reflect combined lengths of 

scheduled events. Seven days are highlighted in the calendar. Left and right arrow keys move 

the selected days backward or forward by one day. Up and down arrow keys move the selected 

days backward or forward by one week. Page up and page down change the month. Clicking 

on a date in the calendar selects that date and the six following days. Press F1 to display a list 

of shortcuts. 

Items for the seven selected days are displayed in the top, right-hand list panel and the busy 

times for these days are graphically displayed in the bottom, left-hand busy panel. When an 

item is selected in the list panel, the details of the item are displayed in the details panel 

immediately below the list panel. Pressing return or double clicking a selected item in the list 

panel opens it for editing. Clicking a bar in the busy panel selects the relevant item in the 

list panel and double clicking in the busy panel opens the item for editing. Conflicting times 

appear as darker colored bars in the busy panel. 

The status bar in the bottom of the main display is divided into four regions. From left to right 

these regions display 1) the help prompt, 2) the next alert, if any, for the current date, 3) the 

current display options and 4) the status, if any, of the action timer. 

Options for the main display can be set by pressing ’m’. A new window will open with detailed 

information about options for the main view and with a entry bar to specify options. Press TAB 

to select options from a drop-down list. Initially, items in the drop-down list are those specified 

in ’main_history’ in your ’~/.etm/rc’ but option strings used during the current session are 

appended. Here is the help information for the main view: 

-b BEGIN Date. Display items for seven days beginning with this 

(fuzzy parsed) date. 

-g GROUPBY An element from [d,p,c,k] where: 

d: group by date 

p: group by project 

c: group by context 

k: group by keyword 

-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. 

-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 

7

ather than FILE, to include items which do NOT have file 

names matching FILE. 

-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. 

-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. 

-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 with characters from the following: 

a: actions 

b: task begin dates 

e: events 

f: finished tasks 

n: notes 

r: reminders 

t: available tasks 

u: undated tasks 

w: waiting tasks 

Items with types belonging to OMIT will not be displayed. 

The other, non-interactive, views are invoked from the main display. 

item view: Press ’i’ to display the help information and open an entry bar 

to set the options or press TAB to select them from a drop-down list. 

Item view is similar to the main view but can display an arbitrary number 

of days and supports exporting in both iCal/vCal and CSV format. 

Initial entries for the drop-down selection list are set in ’item_history’ 

in your ’~/.etm/rc’. Press ’p’ to print the resulting display. 

busy view: Press ’b’ to display the help information and open an entry 

bar to set the options or press TAB to select them from a drop-down 

list. Busy view lists busy and/or free times for a specified period in 

graphical and/or textual form. Options for the free time display control 

the opening and closing times, the minimum length of a block and 

wrap time required at either end of a free block. Initial entries for the 

drop-down selection list are set in ’busy_history’ in your ’~/.etm/rc’. 

Press ’p’ to print the resulting display. 

8

ledger view: Press ’l’ to display the help information and open an entry 

bar to set the options or press TAB to select them from a drop-down 

list. Ledger view displays an accounting of time spent broken down 

and ordered by date, keyword or context in many ways. Exporting in 

both iCal/vCal and CSV format is supported. Initial entries for the 

drop-down selection list are set in ’ledger_history’ in your ’~/.etm/rc’. 

Press ’p’ to print the resulting display. 

When setting options for main, item, busy and ledger views, entering an empty string invokes 

the default options for the view. New settings from the current session are appended to the 

relevant history list. 

Display dates for tasks 

We may want to be warned of an upcoming due date for a task. We may also want to be 

reminded of a task that is past due. The displayed interval of dates may or may not include 

today. When should tasks be displayed? The approach taken by etm is the following: 

• If the due date for a task falls within the displayed interval, then display the task on its 

due date. 

• Else if the due date for a task falls before the displayed interval and the due date falls on 

or before today (the task is currently due or past due), then display the task on the first 

day of the displayed interval. 

• Else if the task has a begin date (the ’@b’ option was provided) and the begin date falls 

within the displayed interval, then display the task on its begin date. 

• Else if task has a begin date and the begin date falls before the displayed interval and 

the begin date also falls on or before today, then display the task on the first day of the 

displayed interval. 

• Else do not display the task. 

Regular expression (regex) matching 

Etm supports the use of case-insensitive, regular expression matching when searching in main 

view and when filtering contexts, keywords and/or projects in all views. E.g., an option setting 

which included ’-c errands’ would limit the display to items which contain ’errands’ in the context 

field. Alternatively, within etm ’-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., 

9

e.py i -c ’!errands’ 

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

Skip down to ’Matching Patterns in Text: The Basics’ and note that the surrounding 

’/’ delimiters are not needed in etm. 

Searching 

etm supports two types of case-insensitive, regular expression searches. Both types look for 

matches in the item description (title) and note fields. In the first type, the search expression 

is entered in the search box in the top, right-hand corner of the main view in the gui. Any 

matching item, regardless of date, will be displayed but, in the case of a repeating, non-task 

item, only the first repetition will be displayed. For a repeating task, all finished repetitions 

will be displayed along with the first unfinished repetition. 

The second type involves using the search option, ’-s’, either from the command line or when 

setting options for a view in the gui. This type of search only lists items whose dates fall within 

the displayed interval of dates but, in the case of a repeating item, shows every instance of the 

repetition falling within these dates. 

Export to iCal/vCal 

The item view can be exported to applications supporting the iCal (vcalendar) format such as 

Google Calendar, Sunbird, KOrganizer, iCal and, one of my favorites, phpicalendar. Simply set 

the item view options to select the dates and items you wish and then append ’-x NameOfCalendar’. 

E.g., ’-x classes’ would create a calendar named ’classes.ics’. 

Export to CSV 

Item and ledger views also support exporting in CSV (comma separated values) format. Files 

in this format can be imported into most spreadsheet and database programs. Item view 

exports contain all fields for the relevant items and ledger view contains two fields, one for 

the breakdown and one for the corresponding times in minutes. Here, for example, is a ledger 

view with ’-i 2120’ in the option settings: 

9.8h) 2010-06-02 

3.0h) personal 

3.0h) social 

1.3h) computer 

1.3h) work 

1.3h) report 

1.0h) gym 

10


1.0h) health 

0.5h) phone 

0.5h) CR 

0.5h) E 

4.5h) 2010-06-03 


1.0h) social 

3.5h) office 

1.5h) CR 

1.5h) E 

2.0h) work 

2.0h) staff 

and here is the associated CSV export: 

"key","minutes" 

"2010-06-02","588" 

"2010-06-02:None:personal","180" 

"2010-06-02:None:personal:social","180" 

"2010-06-02:computer","78" 

"2010-06-02:computer:work","78" 

"2010-06-02:computer:work:report","78" 

"2010-06-02:gym","60" 

"2010-06-02:gym:personal","60" 

"2010-06-02:gym:personal:health","60" 

"2010-06-02:phone","30" 

"2010-06-02:phone:CR","30" 

"2010-06-02:phone:CR:E","30" 

"2010-06-03","270" 

"2010-06-03:None:personal","60" 

"2010-06-03:None:personal:social","60" 

"2010-06-03:office","210" 

"2010-06-03:office:CR","90" 

"2010-06-03:office:CR:E","90" 

"2010-06-03:office:work","120" 

"2010-06-03:office:work:staff","120" 

Project details 

Project files are text files with the default extension .txt within etmdata (’~/.etmdata’ by default) 

and any sub-directories. 

11

• The first line of each project file gives the project title together with any optional arguments. 

• Subsequent lines describe one of the six types of entries that are possible in etm data 

files. Each occupies a single line. 

Event: Something that will happen on a particular day (or days) and, 

perhaps, at a particular time. An event cannot be begun or finished 

either early or late. Events may or may not require our participation. 

Event lines begin with ’*’ (asterisk). 

Reminder: Similar to an event but without duration. A starting time is 

required and a list of starting times can be provided. If alerts are 

not specified, one will be triggered at each starting time. Reminder 

lines begin with ’&’ (ampersand). 

Task: Something that needs to be done. It may or may not have a due 

date, and if it does, it might be begun and even finished before the 

due date. It might also be finished and even begun after the due 

date. Task lines begin with one or more ’.’ (period) or ’_’ (underscore). 

Action: 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 ’~’ (tilde). 

Note: A record of some useful information. Note lines begin with ’!’ 

(exclamation point). 

Arguments provided on the first line can include most of those used on subsequent lines. 

When provided, they become the default values for subsequent tasks, events and activities. 

Events 

Event lines have the following format: 

* [Options] 

Options: 

date @d YYYY-MM-DD with fuzzy parsing (required) 

context @c string 

goto @g a list of related file paths and urls in the format 

"long[|short]". Lists will display "short" if provided, 

and otherwise "long". If selected in the gui, "long" 

will be opened using the default application. 

keywords @k string or list of strings 

repeat @r d)aily, w)eekly, m)onthly, y)early, l)ist 

12

Default: none. With l)ist only dates specified 

by @l will be included 

interval @i 2, 3, ... Default: 1 

until @u YYYY-MM-DD with fuzzy parsing. Default: forever 

weekday @w MO, TU, ..., MO(-1) or a list of weekdays. 

Integers can be used instead with 0=MO, 1=TU and 

so forth. 

week @W integer week number or list of week numbers. 

monthday @m integer month day or list of monthdays. 

month @M integer month number or list of month numbers. 

include @l a list of (non matching) dates to include. 

exclude @x a list of (matching) dates to exclude. 

starttime @s HH:MM[AP] fuzzy parsing. 

endtime @e HH:MM[AP] fuzzy parsing (requires starttime). 

alerts @a a list of minutes before --starttime for alerts. 

note @n string 

Events without a starttime are regarded as all-day events. 

Note: Lists in events (above) and reminders and tasks (below) must be comma separated and 

enclosed in parentheses. A list of numbers can also be specified using the range operator, e.g., 

range(1,5) = (1,2,3,4) and range(5,20,3) = (5,8,11,14,17). 

Reminders 

Reminder lines have the following format: 

& [Options] 

Options: 

date @d YYYY-MM-DD with fuzzy parsing (required) 












weekday @w MO, TU, ..., MO(-1) or a list of weekdays. 

Integers can be used instead with 0=MO, 1=TU and 

so forth. 

13

week @W integer week number or list of week numbers 

monthday @m integer month day or list of monthdays 

month @M integer month number or list of month numbers 

include @l a list of (non matching) dates to include. 

exclude @x a list of (matching) dates to exclude. 

starttime @s a time or a list of times (fuzzy parsing). 

alerts @a a list of minutes before --starttime for alerts. 

Default: 0. 


Alerts (for events and reminders) 

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. 

Alternatively, on a mac (OS X leopard), you could use 

alertcmd = ’’’say -v "Alex" "%(t)s. %(m)s."’’’ 

to announce the message using the voice ’Alex’ or 

alertcmd = ’’’say -v "Alex" "%(t)s. %(m)s."; growlnotify -t %(T)s -m "%(m)s"’’’ 

to have the message both spoken and displayed using growl. On linux systems with ’notifysend’, 

a warning sound followed by a 5 second popup display of the alert message could be 

produced with 

alertcmd = ’’’aplay /usr/share/sounds/purple/receive.wav 2> /dev/null; notify-send " 

With -t 0 the display would remain until you dismiss it. 

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

14

Tasks 

Tasks lines have a slightly different format: 

[._] [Options] 

one or more periods or underscores: a task in ’outline’ format with the 

level of indention in the outline corresponding to the number of 

periods or underscores. The use of underscores rather than periods 

adds the task to the prerequisites of the next group of lower level 

tasks (sub outline) within the same branch. Examples below. 

Options: 

date @d YYYY-MM-DD with fuzzy parsing (required for repeating 

tasks) 












weekday @w MO, TU, ..., MO(-1) or list of weekdays. 

Integers can be used instead with 0 = MO, 1=TU and so forth. 

week @W integer week number or list of week numbers 

monthday @m integer month day or list of monthdays 

month @M integer month number or list of month numbers 

include @l a list of (non matching) dates to include 

exclude @x a list of (matching) dates to exclude 

overdue @o k)eep, r)estart, s)kip. Default: k 


begin @b integer number of days before date 

finished @f YYYY-MM-DD with fuzzy parsing 

period @p time in minutes required to complete task. Perhaps 

an estimate for an unfinished task or a record of the 

actual time spent for a completed task. 

Outline format details 

The number of periods or underscores gives the level of indention of the task in the outline 

and the level determines task prerequisites within a given branch of the outline. Tasks at the 

15

same level in a branch can be completed in any order but none can be started until all higher 

level tasks in the same branch have been completed. 

The following example illustrates the possibilities. The right-hand column shows the prerequisites 

for the tasks in the left-hand column. E.g., task 9 will not be available until tasks 3, 4, 

5, 6 and 8 have been completed. 

. task 1 prerequisites for task 1: () 

.. task 2 prerequisites for task 2: (1) 

_ task 3 prerequisites for task 3: () 

_ task 4 prerequisites for task 4: () 

.. task 5 prerequisites for task 5: (3, 4) 

___ task 6 prerequisites for task 6: (3, 4, 5) 

... task 7 prerequisites for task 7: (3, 4, 5) 

___ task 8 prerequisites for task 8: (3, 4, 5) 

.... task 9 prerequisites for task 9: (3, 4, 5, 6, 8) 


.. task 11 prerequisites for task 11: (3, 4) 


Due dates for tasks with prerequisites 

A task with one or more prerequisites but without a due date will implicitly be assigned the 

due date of the last prerequisite with an explicit due date. 

When assigning explicit due dates for dependent tasks, be sure not to assign a date that is 

earlier than that assigned to any of its prerequisites --- doing so would lead to unpredictable 

results. 

Actions 

Actions are simpler still: 

~ [Options] 

Options: 

date @d a date. Required. 

period @p elapsed time in minutes. Required. 

context @c string. 





keywords @k string or list of strings. Keywords containing a 

colon(s), e.g., "x:y", "x:z", will be split to form 

groups and subgroups when aggregating times. 


16

Notes 

Notes are the simplest of all: 

~ [Options] 

Options: 

date @d a date. Required. The current date will be used if 

one is not provided. 

context @c string. 





keywords @k string or list of strings. Keywords containing a 

colon(s), e.g., "x:y", "x:z", will be split to form 

groups and subgroups when aggregating times. 


Anniversary substitutions 

When items are processed whose titles contain a string of the form !YYYY!, the string will be 

replaced with N[st | nd | th] where N is the number of years from YYYY until the current year. 

E.g., On August 23, 2010, the event: 

* Will’s !1985! birthday @r y @M 8 @m 23 

would be displayed as: 

Will’s 25th birthday 

Goto links 

All etm item types support the use of goto lists using the format: 

e.g., 

@g (longname1[|shortname1], longname2[|shortname2], ...) 

@g (http://freshmeat.net/projects/etm|etm, ~/Documents/ETMUsersManual.pdf) 

When a item containing such a goto list is selected in the gui, pressing ’g’ would open a selection 

dialog for choosing an item from the list to open using the system default application. 

The selection list displays short names, if provided, and otherwise long names. 

17

Fuzzy parsing of dates and times 

Fuzzy parsing is supported by etm running in interactive mode (running ’e.py w’) thanks to 

dateutil. A few examples should provide an idea of what’s possible. Suppose that it is currently 

Tuesday, February 17, 2009. Then in fields calling for a date: 

entering would give after fuzzy parsing 

-------- ------------------------------tue 

2009-02-17 

thu 2009-02-19 

mon 2009-02-23 

23 2009-02-23 

’mar 2’ 2009-03-02 

3/2 2009-03-02 

+45 2009-04-03 

-90 2008-11-19 

Similarly, in fields calling for a time, entering ’6p’ would give after parsing ’06:00PM’. Entering 

’6’, on the other hand, would give ’2009-02-06’. Notice that dates which include spaces such 

as ’mar 2’ must be enclosed in quotes. 

Note: Though it is possible to create projects and new tasks and events using a text editor, 

it is stongly recommended that you use the gui version of etm (by running ’e.py w’). The gui 

version provides fuzzy parsing, reports of any parsing errors with an opportunity to correct 

them plus a scrollable help screen. 

Note: in the fuzzy parsing example above, ’tue’ expands to ’2009-02-17’ and so would ’tuE’ 

but ’tu’ would raise an error. Three letter (but case-insensitive) weekday abbreviations must 

be used with fuzzy parsing. In recurrence rules that specify weekdays, on the other hand, 

both ’tue’ and ’tu’ would raise an error but ’TU’ would not. In specifying weekdays in repeated 

tasks/events, two character weekday abbreviations must be used and both characters must be 

upper case. This inconsistency is due to the fact that fuzzy parsing and recurrence rules are 

separate components of dateutil. Needed corrections are provided automatically by etm when 

creating items using the gui version but not when creating items with a text editor. 

Note: events, actions and repeating tasks must have a date specified by the date, @d, field. 

For repeating tasks and events this date should be the first date satisfying the recurrence rule 

on which the task is due or the event occurs. The only exceptions are that with repeating, list 

tasks or events, @r l, the first date from the include dates field, @l, will be used as the starting 

date if the date field is not provided. 

Due dates for repeating tasks 

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: 

18

@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. 

Repeating tasks with prerequisites 

As with non-repeating tasks, the only thing to remember is not to assign earlier due dates to 

dependent tasks. 

Using the date calculator 

Need to perform arithmetic on dates? etm makes it easy to compute the difference in days 

between two dates or the date that results from adding (or subtracting) a number of days to a 

date: 

Or, from the command line: 

$ e.py c feb 15 + 30 days 

2010-02-15 + 30 days = 2010-03-17 

$ e.py c mar 17 - feb 15 

2010-03-17 - 2010-02-15 = 30 days 

$ e.py c feb 15 - 90 days 

2010-02-15 - 90 days = 2009-11-17 

19

Note that adding/subtracting days is also built into etm’s fuzzy parsing. E.g. if it is currently 

2010-02-15, then in a field calling for a date, ’+45’ would give ’2010-04-01’ and ’-90’ would give 

’2009-11-17’. 

Installation/Updating 

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, icalendar), 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. 

OS X users 

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. 

20

Temporary / local installation 

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. 

Files created and used by etm 

Configuration files 

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 rc when e.py is run then 

configuration settings, including the setting for etmdata, will be taken from that 

file instead of ~/.etm/rc. 

~/.etm/rc: 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/data/: 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 Rotating data files 

below. 

~/.etm/export/: Views exported in iCal or CSV format are, by default, kept in this 

directory. 

21

Rotating data files 

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. 

Furthermore, if ’rotate_files = True’ in your ’~/.etm/rc’, new files will be created each month 

and these files will be archived for you after one year. 

Suppose ’rotate_files = True’ and that it is currently February 2009. Then etm will automatically 

create ’tasks_02.txt’, ’evnts_02.txt’, ’actns_02.txt’, ’notes_02.txt’ and ’rmdrs_02.txt’ the 

first time it is run. By default, tasks, events, actions, notes and reminders created during 

February will be written, respectively, to these files. Similar files will be automatically be created 

and become the defaults as subsequent months arrive. When February 2010 rolls around 

’tasks_02.txt’ will automatically be moved to ’.2009-02_tasks’, ’evnts_02.txt’ to ’.2009-02_evnts’ 

and so forth and new ’tasks_02.txt’, ’evnts_02.txt’ and so forth will be created. Since etm only 

processes files with the extension ’.txt’, the monthly archives of your past tasks, events and 

actions will be kept until you decide to delete them but only the last year’s worth will be loaded 

and processed by etm. etm will also create files ’done_02.txt’, ’done_03.txt’ and so forth, store 

finished copies of repeating tasks in these files and archive them after a year. 

If, on the other hand, ’rotate_files = False’. Then etm will automatically create ’tasks.txt’, 

’evnts.txt’, ’actns.txt’, ’notes.txt’, ’rmdrs.txt’ and ’done.txt’ the first time it is run. By default, 

tasks, events, actions, notes, reminders and finished copies of repeating tasks will be written, 

respectively, to these files. These files will neither be rotated nor archived but backups will be 

made when any action taken by etm modifies them. 

When a non-repeating task is finished, a date stamp containing the completion date is added 

to the task so that if, e.g., 

. my non-repeating task @d 2009-02-17 

were marked finished on Feburary 18, 2009 then it would become: 

. my non-repeating task @d 2009-02-17 @f 2009-02-18 

On the other hand, when a repeating task is marked finished, the due date for the task is 

updated to the next due date and a copy of the task with the repetition details removed and 

the completion date added is appended to the done file. If, e.g., 

. my repeating task @d 2009-02-17 @r d @i 7 

were finished on Feb 18, 2009, then it would become: 

. my repeating task @d 2009-02-24 @r d @i 7 

22

and 

. my repeating task @d 2009-02-17 @f 2009-02-18 

would be appended to the appropriate done file. 

A repeating task that is set to skip overdue due dates presents a new situation since it can 

have repetitions that are never finished and yet never become overdue. Suppose, for example, 

that I need to put the trash on the curb for pickup every Friday: 

. take out trash @d 2009-02-20 @r w @w FR @o s 

where the ’@o s’ means that the task will be skipped if it becomes overdue. Then if I forget to 

take out the trash on the 20th, on February 21 this task would be automatically be replaced 

by: 

. take out trash @d 2009-02-27 @r w @w FR @o s 

Since the February 20 repetition of this task was skipped rather than finished, no record would 

be made of a completion in the done file. The completion record would thus show only the 

dates on which the task was actually marked finished. 

Finally, a backup is made of any file before any action using etm w would change it. E.g., 

before a task in ’02_tasks.txt’ 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. Further, a record showing the task before and after the change would 

be appended to ’.02_tasks.log’. 

Pickle files 

For each data file in your data directory and its subdirectories, etm makes a copy for internal 

use. If there is a data file named ’tasks.txt’, for example, then etm will create a version for 

internal use named ’tasks.pkl’. These ’pkl’ files are in a special, ’pickle’ format that permits 

them to be reloaded by etm more quickly than their ’txt’ counterparts. Whenever a ’txt’ file is 

modified, the corresponding ’pkl’ file is recreated. 

Command line usage 

Run 

e.py h 

23

for complete usage information: 

Information: 

h Show this help message 

c Process a date expression of the form ’date (+-) string’ 

where ’string’ is either a date or an integer followed 

by the word ’days’ and return the result. E.g., ’dec 1 + 

90 days’ or ’nov 30 - sep 1’. Note: ’+’ cannot be used 

when ’string’ is a date. 

n Display the latest available version of etm 

w Start the wx(Python) based gui version of etm. If the 

current working directory contains a file named ’emtrc’ 

then settings from that file will be used instead of those 

from ’~/.etm/rc’. 

Displays: 

i [I] Display a list of events, actions and tasks using command line 

options [first prompting for options and displaying help 

information]. 

b [B] Display busy/free times using command line options [first 

prompting for options and displaying help information]. 

l [L] Display a reckoning of time spent in events and actions 

using command line options [first prompting for options and 

displaying help information]. 

or, for example, 

e.py i -h 

to get usage information for item view. 

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. 

24

Example Files 

The files in ’etm-eg.tgz’ (simple examples), ’etm-prob.tgz’ (erroneous entries) and ’etm-egtest.tgz’ 

(stress tests) both illustrate and test etm’s features. The usage for each is the same. 

Unpack the tarball, then cd to the resulting directory and run: 

python make_egs.py 

Running ’make_egs.py’ creates a series of data and other supporting files using the templates 

in the various *.eg files to produce corresponding *.txt files with suitable dates for illustrating 

and testing etm. Any existing *.txt files will be removed in the process. 

Don’t change the directory name 

As a safety feature, ’make_egs.py’ will only run if the directory name is unchanged. 

A file named ’rc’ will also be created based on the settings in your ’~/.etm/rc’ but with the 

setting for ’etmdata’ changed to point to the current directory. You can then run either e.py 

or e.pyw from this directory and the example entries will be the only ones displayed. 

The created data files should illustrate what’s possible. Complete some of the repeating tasks 

by pressing ’f’ and see what happens. Check ledger reports by pressing ’l’ and using various 

options. Look at the busy/free report by pressing ’b’. Make any changes you like but remember 

that all *.txt files in the current directory will be overwritten whenever make_egs.py is run. 

The created *.txt and other supporting files can always be removed by changing to the ’eg’ 

directory and running 

python make_egs.py -r 

This will restore the ’eg’ directory to its initial state and prevent the examples from appearing 

in your etm displays. 

License 

Copyright (c) 2009-2010 Daniel Graham . All rights reserved. 

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. 

http://www.gnu.org/licenses/gpl.html 

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. 

25

event and task manager

Create successful ePaper yourself

Delete template?

Save as template?