etm
manage events and tasks using simple text files

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.

Feedback

Please share your ideas in the discussion group at GoogleGroups.

Sample entries

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

[ICO]NameLast modifiedSizeDescription

[DIR]Parent Directory  -  
[   ]CHANGES17-Jan-2013 08:59 728  
[TXT]ETMUsersManual.html21-Mar-2012 08:41 87K 
[TXT]INSTALL16-Jan-2013 20:06 3.9K 
[TXT]LearningtoUseRegularExpressions.html06-Feb-2010 13:59 46K 
[TXT]batchchange.txt15-Feb-2012 08:51 2.6K 
[   ]etm-2.0.67.dmg17-Jan-2013 09:00 22M 
[   ]etm-2.0.67.tar.gz17-Jan-2013 09:00 7.6M 
[   ]etm-891.dmg17-Apr-2012 13:09 20M 
[   ]etm-891.tar.gz17-Apr-2012 13:08 187K 
[   ]etm-891.zip17-Apr-2012 13:08 190K 
[VID]etm-video1.mov10-Jun-2010 13:04 15M 
[TXT]etm.sh.txt15-Sep-2011 08:54 26  
[TXT]etm_osx.sh.txt15-Sep-2011 08:54 138  
[DIR]help/17-Jan-2013 12:57 -  
[DIR]html-images/26-Jul-2012 16:34 -  
[DIR]icons/19-Jan-2013 10:46 -  
[TXT]old2new.txt17-Apr-2012 13:11 5.1K 
[TXT]one2two.py.txt13-Jan-2013 10:16 15K 
[   ]sample_completions.cfg14-Jan-2013 09:23 1.2K 
[TXT]sample_datafile.txt13-Jan-2013 11:37 1.4K 
[TXT]sneakpeek.html26-Jul-2012 16:34 31K 
[TXT]usholidays.txt01-Dec-2009 13:23 738  
[TXT]version.txt17-Jan-2013 08:59 7  

Contents

Features

  • Cross platform. Both the gui and command line versions work under MS Windows, Linux and OS X.

  • Simple and efficient with almost no overhead.

  • Quickly enter items using a simple, intuitive format.

  • Easily specify tasks and events that repeat in complex ways:

    Once every other week:            @r w @i 2
    
    Monthly on the 2nd-15th:          @r m @m range(2,16)
    
    Monthly on the third Monday:      @r m @w MO(+3)
    
    The 3rd, 10th and 25th of April:  @r m @m (3, 10, 25) @M 4
    
    Weekly on Tu and Th through May:  @r w @w (TU,TH) @u 5/31
    
    Monthly on the 2nd and 15th:      @r m @m (2,15)
    
    The first and last days of June:  @r m @m (1,-1) @M 6
    
    Every 13th which is a Friday:     @r m @m 13 @w FR
    
  • Enter dates and times using fuzzy parsing. Suppose that it is currently Tuesday, February 17, 2009. Then in fields calling for a date:

    entering         gives 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
    +0                  2009-02-17 (today)
    +1                  2009-02-18 (tomorrow)
    +45                 2009-04-03
    -1                  2009-02-16 (yesterday)
    -90                 2008-11-19
    
  • Enter times using fuzzy parsing. In fields calling for a time:

    entering         use_ampm:   True    False
    --------        ----------------------------
    10                         10:00am   10:00
    10a                        10:00am   10:00
    10:00                      10:00am   10:00
    22                         10:00pm   22:00
    10p                        10:00pm   22:00
    
  • Additionally, when entering the ending time for an event that starts at 11:30:

    entering         use_ampm:   True    False
    --------        ----------------------------
    +1:30                       1:00pm   13:00
    +1h 30m                     1:00pm   13:00
    +90m                        1:00pm   13:00
    +90                         1:00pm   13:00
    
  • 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 items whose projects, contexts and/or keywords match (regex) search string(s).

  • Show items whose descriptions or notes contain a case-insensitive (regex) search string.

  • 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:

    $ e.py c nov 30 - sep 1
    2009-11-30 - 2009-09-01 = 90 days
    
    $ e.py c sep 1 + 90 days
    2009-09-01 + 90 days = 2009-11-30
    
  • View sun and moon data (from the US Naval Observatory) for a location specified in your ~/.etm/rc for a (fuzzy parsed) date.

  • View local weather conditions and forecast (from yahoo weather) for a location specified in your ~/.etm/rc.

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

Changes from versions prior to 800

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.

etm Files

The *.pkl python pickle files are no longer needed or used.

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.

Item format

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

python old2new.txt -h

for usage information.

Overview

GUI Display

Date Bar
 
Monthly
Calendar
 
 
 
Busy
Panel
 
 
 
 
 
Outline Panel
 
 
 
 
Details Panel
 
Status Line

Date bar

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.

Quick Start

In etm there are four types of items:

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

Tasks in etm can have prerequisites. E.g.,

- check sizes of existing air filters
-- buy replacement filters
--- install new air filters

The outline structure gives the dependencies.

Tasks with unfinished prerequisites are classified as waiting by etm.

It is also possible for tasks to have multiple, independent prerequisites. E.g.,

- borrow power drill from Ed
+ pick up hardware
-- repair door

Here the '+' adds 'borrow' to 'pick up' as a prerequisite for 'repair'.

Thanks to etm's use of dateutil, events and tasks can be repeated in powerful ways. E.g.,

* payday @d 6/1 @r m @w (MO,TU,WE,TH,FR) @m (-3,-2,-1) @S -1

would repeat on the last weekday in each month.

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

Item Classifiers

A variety of options are available in etm to classify items:

@c CONTEXT

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.

Dates, Times and Alerts

Fuzzy Date Parsing

Suppose that it is currently Tuesday, February 17, 2009. Then in fields calling for a date:

entered           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
+0                  2009-02-17 (today)
+1                  2009-02-18 (tomorrow)
+45                 2009-04-03 (45 days from now)
-1                  2009-02-16 (yesterday)
-90                 2008-11-19 (90 days ago)

Fuzzy Time Parsing

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:

@s 9a @e 10:30a

@s 9a @e +90m

@s 9a @e +90

@s 9a @e +1:30

@s 9a @e +1h 30m

However entered, etm would record the extent as '@e +1:30'.

Alerts

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"'''

(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

alertcmd = '''aplay /usr/share/sounds/purple/receive.wav 2>
        /dev/null; notify-send "%(T)s" "%(m)s" -t 5000'''

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

Alternatively, you could receive an email reminder with

alertcmd = '''echo "%(m)s" | mail -s "etm alert at %(T)s"
        your@email.address"'''

if either sendmail or postfix is enabled on your system.

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.

Time Zones

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:

  1. The item
    1. does not have an @z ZONE entry or
    2. 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.

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

* event @d 2010-08-01 @s 17:00 @z US/Eastern

* event @d 2010-12-01 @s 17:00 @z US/Eastern

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

Grouping and Sorting

Grouping and sorting is controlled by the '-g' outline display option. The default

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

groups and sorts items by y)ear, m)onth and d)ay combined 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 k1 (client name), then y)ear, q)uarter and m)onth combined and finally k2 (project name) 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'
...

or

-g (k1, (y,m,d), T) -d 0 -T 1

would group by k1 (client), then y)ear, m)onth and d)ay combined and finally T (item title). With details omitted, '-d 0' and totals first, '-T 1', the output would be similar to:

3.6h) client 1 (4)
    2.0h) Fri Aug 5 2011 (2)
        1.0h) prepare order (1)
        0.5h) review invoice (1)
    ...
...

Note in the examples above that the ledger information '(number of included items) total time' is automatically appended to each node.

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), and k1, k2, k3, (first, second and all remaining keywords). E.g. with '@k A:B:C:D:E', k1 would be 'A', k2 would be 'B' and k3 would be 'C:D:E'.

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
    

Regular Expression Filters

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.

Options for Actions, Events, Notes and Tasks

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.

KeyValue 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).
@t TAGS O O O O a string or a comma separated list of strings in parenthesis, e.g, "@t (tag 1, tag 2)".

Repetition

Events and task can be repeated using further keys and values

Key Value Description
@r REPEAT 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.
@C COUNT an integer number of repetitions to allow. E.g., "@d 2011-01-01 @r m @m (15, 30) @C 4" would repeat on Jan 15, Jan 30, Feb 15 and Mar 15 of 2011. Default: none, i.e., repetitions continue forever.
@w WEEKDAY 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.

Options for Outline and Busy Views

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

    OutlineBusyDescription
-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.
-gGROUPBYO   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.
-oOMIT 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.
-sSEARCH 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.
-cCONTEXT 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.
-kKEYWORD 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.
-pPRIORITY 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.
-tTAG 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'.
-lLOCATION 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.
-uUSER 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.
-PPROJECT 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.
-fFILE 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.
-iINCLUDE   O String. One or more characters from B (busy time bars), b (busy times), F (free time bars), f (free times), and c (conflict times). Default: Bfc
-OOPENING   O Time. The opening or earliest time (fuzzy parsed) to be considered when displaying free periods. Default: 8:00a.
-CCLOSING   O Time. The closing or latest time (fuzzy parsed) to be considered when displaying free periods. Default: 10:00p.
-mMINIMUM   O Positive integer. The minimum length in minutes for a free period to be displayed. Default: 60.
-wWRAP   O Positive integer. Provide a buffer of WRAP minutes before and after busy periods when computing free periods. Default: 15.
-vVCAL O   Export displayed items in vCal format to export.ics in the 'export' directory specified in the etm rc file.
-xVALUES O   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).

Command line usage

Run

e.py ?

for complete usage information:

documented etm commands
Enter '? X' (or 'help X') for
details about command X
=============================================================================
b  c  colors  d  e  f  help  j  m  n  numbers  o  q  r  u  v  w

or, for example,

e.py ? o

to get outline usage information:

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.

You can run:

e.py

without any options to open an interactive version of the CLI:

$ e.py
enter 'q' to quit or 'help' for usage information
etm:

Entering 'o' at the prompt produces output such as:

etm: o
Wed Aug 24 2011 (20) 4:00
    10:00a meet with Client 1 [1]
    1:00p meet with Client 2 [2]
    5:00p Monday, Wednesday, Friday late afternoon event [3]
    5:00p workout [4]
        back exercises [5]
        Alert test [6]
        phone conference with Client 1 [7]
    +1   make eye appointment [8]
    +7   set up luncheon meeting with Client 2 [9]
    +14   Promote etm [10]
        monthly report preparation [11]
        Client 2 research [12]
        work on E draft [13]
    X   E draft [14]
    X   call Client 2 [15]
    X   Water house plants [16]
        etm examples [17]

Thu Aug 25 2011 (12) 6:45
    10:05a Tuesday/Thursday morning and afternoon events [18]
    12:00p staff lunch [19]
    2:50p Tuesday/Thursday morning and afternoon events [20]
    3:00p Meet with Client 3 re A [21]
        back exercises [22]
        Take out trash [23]
        make eye appointment [24]
        revisions for A [25]
        work on E revisions [26]

The numbers in square brackets that follow items can be used interactively to modify items. E.g.

etm: d 9

would prompt for confirmation and then delete item number 9 (set up luncheon). Similarly

etm: e 11

would open item number 11 (monthly report) using the editor specified by 'term_editor' in your etmrc file. Other interactive options include c (display 3 month calendar), f (finish item), m (move item to a different file), n (create new item), r (force data reload), u (unfinish item) and v (check for newer version).

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.

Requirements

You will need to have python >= 2.5.2 (but < 3.0), wxPython >= 2.8.7 and the non-standard but easily-installed python module dateutil >= 1.4.1. Exporting a list view to iCal requires the python module vobject .

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

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

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.

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.

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.

etm Files

Configuration files

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

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

Completion List Files

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.

Abbreviations

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

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

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.

Rotating backup files

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.

Log files

Any etm action which changes a data file is logged. E.g. adding a new event to '07_evnts.text' would append a time stamped entry to '07_evnts.log':

### 2011-07-21 10:37:38 ###
[+] * Book club pot luck dinner @d 2011-08-14 @s (6:30p) @e +3:00

License

Copyright (c) 2009-2012 Daniel Graham <daniel.graham@duke.edu>. 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.