etm 2: sneak preview

etm 2: sneak preview

Last revised: Thu Jul 26, 2012 16:34:08-0400

Plans for a new version of etm are in the early stages. This document will be updated periodically to reflect improvements suggested by users. Please share your ideas in the etm forum on google groups.


Combined date and time

The use of separate fields, @d and @s, for date and starting time has been combined into a single, starting datetime, @s, which supports fuzzy parsing. E.g. @s 3p tue would set the starting datetime to be 3:00pm on the next Tuesday on or after today.

Note that this is datetime even when only a date is given. E.g., @s 5/5 would give 12:00am on May 5 unless you have set an alternative default starting time in your etmrc.

Consistent use of datetimes is required for time zone support.

Multiday events

Events can now span multiple days. E.g., the following would create an event lasting 3 days and 8 hours starting at 9am on May 5:

* multi-day event @s 9a 5/5 @e +3d8h

This too is needed for time zone support since an event that falls within one day in one time zone may spill over into another day in another time zone.

Begin warnings and alerts for both tasks and events

Events can now have begin warnings as well as tasks.

Tasks can now have alerts as well as events.

Repeatable recurrence rules with new hourly and minutely frequencies

Recurrence rules have a slightly different format and can be repeated. E.g.,

@r m &w 2mo &h 10, 14, 16
@r m &w 3tu &h 11, 15, 17

would repeat m)onthly on w)eekdays corresponding to the 2nd Monday at 10am, 2pm and 4pm and the 3rd Tuesday at 11am, 3pm and 5pm.

Both hourly frequencies and minutely frequencies are now supported, the latter using &n since &m is by month day and &M is by month. Note the use of & rather than @ to specify field values within a recurrence rule.

Lists are no longer wrapped in parentheses. E.g., note the use 10, 14, 16 instead of (10, 14, 16) in the example above.

Custom, repeatable alerts with before and after triggers

Alerts can now be repeated. E.g.,

@a -10, -5
@a +1h: s

would trigger the default alert at 10 and 5 minutes before the starting time and a sound alert one hour after the starting time.

Similary, the alert

@a -2d:,; file1, file2

would send e)mails to the two listed recipients exactly 2 days (48 hours) before the starting time of the event with the event summary as the subject, the event description, by default, as the body and with file1 and file2 as attachments.


@a +0: program_path

would execute program_path zero minutes before the starting time of the event.

The format for each of these:

@a <trigger times> [: action]

In addition to the default action used when the optional : action is not given, there are five possible values for action:

See Templates below for ways to customize alert messages.

The alert type is inferred from the optional : action entry.

New item types

The number of possible item types has been expanded from the original list:

~   action
*   scheduled event
-   task
+   task
!   note

to include the following new types

^   all day event
%   delegated task
&   in basket
?   someday maybe
#   deleted item

Since all scheduled events have @s entries that are datetimes (with timezone information), an all day event is one in which etm effectively ignores the time component of the datetime. Typical uses for this are holidays, birthdays and anniversaries.

Delegated tasks are somewhat similar to tasks with unfinished prerequisites. In the former case, you are waiting for someone else to complete the task and in the latter, you are waiting for yourself to finish the prerequisite. Thus neither is treated as an available task.

Getting Things Done (GTD) fans will recognize in basket and someday maybe. In basket entries are quick, "don't worry about the details" entries to be edited later when you have the time. Someday maybe items are you don't want to forget about altogether but don't want to appear on your next or scheduled lists. Both types of entries appear in the current view under special headings so that neither will be forgotten.

Deleting an item no longer removes it from the data file but instead merely inserts a # character followed by a space at the beginning of the item and records the change in the log file.

Default lines

The requirement that each file have an initial project line has been removed. Instead, default lines beginning with =, are now supported and can be used anywhere in a data file. E.g.

= @c home @k projects

would make home the default context and project the default keyword until another default line is reached.

Group tasks

The old outline format for entering tasks with prerequisites has been replaced by group task. E.g., rather than entering the tasks for making a dog house by entering:

+ pickup lumber     @c errands
- pickup paint      @c errands
-- cut peices       @c shop
---  assemble       @c shop
---- sand           @c shop
----- paint         @c shop

You could now enter:

+ dog house @k projects @p 3 @c shop @s 2012-05-01
  @j pickup lumber     &q 1 &b 5 &c errands
  @j pickup paint      &q 1 &b 5 &c errands
  @j cut pieces        &q 2 &b 4
  @j assemble          &q 3 &b 3
  @j sand              &q 4 &b 2
  @j paint             &q 5 &b 1

The actual tasks or jobs within the group are given by the @j entries and are displayed using a combination of the group summary and the job summary:

dog house 1/6: pickup lumber
dog house 2/6: pickup paint
dog house 3/6: cut pieces
dog house 4/6: assemble
dog house 5/6: sand
dog house 6/6: paint

Note that a task group is a single item and is treated as such. E.g., if any group task is selected for editing then the entire group is displayed.

The queue entries, &q, set the order --- tasks with higher queue positions (smaller values) are prerequisites for tasks with lower queue positions (larger values).

@key entries prior to the first @j become the defaults for the jobs which follow. In the example above, for instance, @c shop sets the default context as shop for all component jobs but the lumber and paint jobs override this default with &c errands. Note that keys given in jobs use & rather than @.

Many key-value pairs can be given either in the group task using @ or in the component jobs using &:
@a or &a: alert
@b or &b: begin
@c or &c: context
@d or &d: description
@e or &e: extent
@f or &f: finish
@g or &g: goto
@k or &k: keyword
@l or &l: location
@m or &m: memo
@t or &t: tag
@u or &u: user

The key-value pair &q (queue position) can only be given in component jobs. Key-values other than &q and those listed above, can only be given in the initial group task entry and their values are inherited by the component jobs. In the example above, the May 1 due date for the task is given by the @s entry. Begin warnings for the first two jobs would then begin 5 days earlier on April 26 because of their &b 5 entries. Similarly, alerts could be specified for individual jobs that would trigger at times relative to due datetime for the group task.

When a component job is finished, an &f entry is appended to the job and it is removed from the list of prerequisites for the other jobs. When all jobs in a group task have been finished, an @f entry is appended to the group task and the &f entries for the component jobs are removed. The group task would then be displayed as finished on the date specified by @f and the individual job finish dates would no longer be displayed. A record of the job finish dates would, however, be preserved in the relevant log file.

In the example above, only the first two would initially be displayed as available for completion and the other jobs would be displayed as having unfinished prerequisites:

Unique Id, log entries and item histories

A new unique Id field marked by @i will automatically be created by etm for each item. For example, when you create:

* Sales meeting @s 11a Mon @l Conference Room

it will automatically be changed by etm to:

* Sales meeting @s 11a Mon @l Conference Room
@i 396a55df-5f00-45a7-91f6-3ecbebf1339b

Whenever the etm data file path/filename.txt is modified, a corresponding entry will added to path/filename.log containing the UTC time stamp of the modification and, in a format similar to unified_diff, the changed lines with the unique Ids of the relevant items appended to the @@ range lines. For example:

2012-05-24 12:15
    @@ -0,0 +8,1 @@ 396a55df-5f00-45a7-91f6-3ecbebf1339b
    [+] * Sales meeting @s 11a Mon @l Conference Room
2012-05-29 14:37
    @@ -8,1 +8,1 @@ 396a55df-5f00-45a7-91f6-3ecbebf1339b
    [-] * Sales meeting @s 11a Mon @l Conference Room
    [+] * Sales meeting @s 11a Fri @l Conference Room
    @@ -21,1 +21,1 @@ 18b24fb5-c700-48d0-88a7-fa87733e17d6
    [-] ^ Open House @s Thu @l Office
    [+] ^ Open House @s Thu @l Office

In contrast to the current log format, line number and unique Id information are added and only the lines which have been changed are displayed. The new format also supports file changes involving more than one item.

Using the unique Ids in the log files, it will be possible to press a hot-key in etm and see a history of changes for the selected item. E.g., for the 'sales meeting' above, the history might appear as follows:

2012-05-24 12:15; path/filename.log -0,0 +8,1
    [+] * Sales meeting @s 11a Mon @l Conference Room
2012-05-29 14:37; path/filename.log -8,1 +8,1
    [-] * Sales meeting @s 11a Mon @l Conference Room
    [+] * Sales meeting @s 11a Fri @l Conference Room

Note that the path/filename will change if an item is moved from one file to another, in which case the history would record the removal from one file and the addition to another.

Templates and replacements

You can use expressions such as !xyz! in various contexts and etm will magically replace them. An anniversary replacement such as !1944! would, for example, be replaced during the year 2012 with the expression 68th. Several replacements like this are built into etm and are discussed below. Others can be defined in your etmrc. You could, for example, have the entry:

xyz = "XYZ Ltd"

in which case !xyz! in, say, the summary or description of an item would be replaced by XYZ Ltd. Such user defined replacements should, of course, be unique.

A template is just a replacement string that itself contains one or more replacement strings. Any replacement string is expanded recursively until no further expansion is possible.

alert templates

Suppose, for example, that you have the following templates in your etmrc:

voice = """\
say -v "Alex" "The time is !alert_time!. !summary! !minutes!. !l!."

email = """\
!start_time! - !end_time! !start_day!, !start_date!


boss_sig = """\

The Boss
XYZ, Ltd
123 456-7890

sales_team = ","
Here are some of the built-in replacements that are particularly useful in alert templates:
!start_day!: the starting day of the week from the item's @s entry
!start_time!: the starting time from the item's @s entry
!end_date!: the ending date from the item's @s and @e entries
!end_time!: the ending time from the item's @s and @e entries
!alert_time!: the time the alert is triggered
!summary!: the item's summary
!d!: the item's @d (description)
!l!: the item's @l (location)

The replacement for !minutes! depends upon the number of minutes until the event begins or since it began. The default, which also can be changed in your etmrc, is:

minutes = [                               # when:
 'begins !num_minutes! minutes from now', # num_minutes <= -2
 'begins one minute from now',            # num_minutes == -1
 'begins now',                            # num_minutes == 0
 'began one minute ago',                  # num_minutes == 1
 'began !num_minutes! minutes ago',       # num_minutes >= 2

The only requirements for your custom minutes is that it must be a list of five strings, one for each of the possible ranges. Use !num_minutes! in the strings where you want the integer number of minutes to appear.

With the etmrc settings above, the event

* Sales meeting @s 11a 7/6 @e +1h @l Conference Room @a -15: v
@a -1d: !sales_team!
    Item 1
    Item 2

would execute the following command at 10:45am on July 6, 2012:

say -v "Alex" '''The time is 10:45am. Sales meeting begins 15 minutes from now. Conference Room.'''

and would send emails to joe and frank at 11:00am on Thursday with the subject 'Sales meeting' and the message:

11:00am - 12:00pm Friday, July 6, 2012
Conference Room

    Item 1
    Item 2

The Boss
XYZ, Ltd
123 456-7890

detail templates

When you select an item in the etm gui, item details are displayed in the details panel. In prior versions of etm, the entire item would be displayed as it appears in the data file. While this remains the default behavior, it is also possible to define templates that customize the display for item types that you would like to be displayed differently:

If, for example, your etmrc contains:

note_template = """\
!summary!                                           !t!

then when this note

! Thinking @s 2012-07-04 @d We can't solve problems by using the same kind of thinking we used when we created them. - Albert Einstein @t quotes @k Einstein:Albert @z US/Eastern
@i a21e576f-8daf-4264-bc87-964df15cd726

is selected, the details panel would display

Thinking                                    quotes
We can't solve problems by using the same kind of thinking we used when we created them. - Albert Einstein

When viewing the details for an item, a hotkey will allow you to toggle back and forth between your custom view and the regular view. Note, however, that the regular view will not display the @i unique id and will only display the @z time zone if it is different than the current local time zone. The regular view of the above note in the Eastern time zone would thus be

! Thinking @s 2012-07-04 @d We can't solve problems by using the same kind of thinking we used when we created them. @t quotes @k Einstein:Albert

Note that while information about the item's file and line numbers is not available in the details panel, the press of a hotkey will display the complete, "universal diff" history of the item from its creation to the latest change with timestamps, file name and line numbers.

template labels

One further display customization is possible. You can define labels in your etmrc. Suppose, for example, that you have:

labels = {
    'l' : "Location: ",
    't' : "Tags: "

Then the !t! entry in the note template above would, for the given note, expand to Tags: quotes. Similarly, the !l! entry in the email template would expand to Location: Conference Room. Such labels are only generated when the corresponding field value is not empty.


The screen shots below show several views from a PyQt prototype. The goal has been to reduce the size of the display with a view toward possible deployment on mobile platforms.


The toolbar contains, from left to right:

The drop down views menu displays the available views --- these are enumerated below.

Details panel

Clicking on an item or pressing the open details icon in the tool bar displays the details of the selected item in the details panel. This panel can be closed either by pressing Escape, the close details panel icon in the tool bar or the close button in the details panel.

The icons in the details panel tool bar correspond, from left to right, to

- mark the task finished (disabled for non tasks)
- create a clone and open it for editing
- delete the item
- open the item for editing


When a repeating item is selected, both delete and open for editing offer a chance to choose which instances of the item to change:

When using the editor, an improved version of completion is available. As soon as you enter "@c", for example, a list of possible completions will pop up:

And then, as you type further characters, the list will shrink to show only those that still match.

Up and down arrow keys change the selection and either tab or enter inserts the selection.

The possible selections come from a single words file in your etm directory with entries such as the following:

@c home
@c office
@c phone
@k client_a:project_1
@k client_a:project_2
@t blue
@t red

Action timing

Clicking on the new action timer icon brings up a dialog to enter the summary (title) of the timer and, when this is accepted, the icon changes to display a pause timer icon, an elapsed time in hours and minutes display and a stop timer and record action icon:

When the timer is paused, the display changes to the following:

Whether running or paused, a tooltip for the elapsed time display shows the action title.



Displays items requiring attention now, including in basket items, due and pastdue tasks, due and past due delegated tasks, due and past due tasks with unfinished prerequisites, notices of upcoming (begin) items and someday maybe items.


Displays unscheduled (undated) tasks grouped by context and sorted by priority. These are the GTD next actions that can completed whenever an opportunity arises.


Displays scheduled (dated) items grouped by date and sorted by type and time. Note that all dates are displayed with the view scrolled to the current date on opening or when the spacebar is pressed. Times are displayed for the local time zone.

Arrows in the toolbar go backward and forward to the previous or next date with scheduled items.


Displays busy/free time for scheduled events graphically by week. Clicking in a busy period opens the details panel for the relevant event. This view refects the 'sunday_first' setting from your etmrc file. Arrows in the toolbar go backward and forward one week at a time.


Displays a monthly calendar display with day colors highlighted according to the amount of event time scheduled. Double clicking a date switches to the day view for the selected date. Arrows in the toolbar go backward and forward one month at a time.


Items other than notes grouped by project file path, type, title and datetime. Use this view to review the status of your projects.

                datetime1 for event1
                datetime2 for event1
                datetime1 for event2
                datetime2 for event2
                datetime1 for task1


Only actions will be displayed in this view and only action minutes will be shown in totals. Maybe a list of options for grouping and sorting could be given in your etmrc and then a hotkey would cycle among the resulting views?

The goal would be enable a convenient ledger view for accounting and billing. Suggestions from folks who would use such a view would be greatly appreciated.


Both dated and undated notes grouped by project file path and title. Dated notes also appear in the Day view on the relevant date. Undated notes, on the other hand, only appear in this view. With an appropriate note_template, the goal here is to incorporate the functionality of nts into etm.


Corresponds to the old 'options' view. An entry line for options at the top with a corresponding tree display below.