Data

etm data entries (events, tasks, and so forth) are kept in text files with the extension .txt in the directory datadir specified in your etm.cfg file. Items begin with a type character such as * (event) and continue on one or more lines either until the end of the file is reached or another line is found that begins with a type character. The beginning type character for each item is followed by the item summary and then, perhaps, by one or more @key value pairs.

The discussion of possible entry types below is followed by a discussion of the possible @key value pairs.

Entry types

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

    ~ work on sales presentation @s mon 3p @e 1h15m

Entries such as @s mon 3p and @e 1h15m are discussed below under Item details.

Event

Something that will happen on particular day(s) and time(s). Event lines begin with an asterick, *.

    * dinner with Karen and Al @s sat 7p @e 3h

Events have a starting datetime, @s and an extent, @e. The ending datetime is given implicitly as the sum of the starting datetime and the extent. Events that span more than one day are possible, e.g.,

    * Sales meeting @s 9a wed @e 2d8h

begins at 9am on Wednesday and ends at 5pm on Friday.

Occasion

Holidays, anniversaries, birthdays and the like. Like an event with a date but no starting time and no extent. Occasions begin with a caret sign, ^.

    ^ The !1776! Independence Day @s 2010-07-04 @r y &M 7 &m 4

On July 4, 2013, this would appear as The 237th Independence Day.

Note

A record of some useful information. Note lines begin with an exclamation point, !.

! xyz software @d user: dnlg, pw: abd123gef

Task

Something that needs to be done. It may or may not have a due date. Task lines begin with a minus sign, -.

- pay bills @s Oct 25

A task with an @s entry becomes due on that date and past due when that date has passed.

Delegated task

A task that is assigned to someone else, usually the person(s) designated in an @u entry. Delegated tasks begin with a percent sign, %.

    % make reservations for trip @u joe @s fri

Task group

A collection of related tasks, some of which may be prerequities for others. Task groups begin with a plus sign, +.

    + dog house
      @j pickup lumber      &q 1
      @j cut pieces         &q 2
      @j assemble           &q 3
      @j pickup paint       &q 1
      @j paint              &q 4

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

Individual jobs are given by the @j entries. The queue entries, &q, set the order --- tasks with smaller &q values are prerequisites for subsequent tasks with larger &q values. In the example above, neither "pickup lumber" nor "pickup paint" have any prerequisites. "Pickup lumber", however, is a prerequisite for "cut pieces" which, in turn, is a prerequisite for "assemble". Both "assemble" and "pickup paint" are prerequisites for "paint".

The way a task group is displayed is illustrated below. Note that jobs are numbered and that jobs with unfinished prerequisites are labeled with a different icon.
When a job is completed, its icon is changed and it is displayed on the date the job was completed. Note that completing "pickup lumber" makes "cut pieces" available for completion.

In basket

A quick, don't worry about the details item to be edited later when you have the time. In basket entries begin with a dollar sign, $.

    $ joe 919 123-4567

If you create an item using etm and forget to provide a type character, an $ will automatically be inserted.

Someday maybe

Something are you don't want to forget about altogether but don't want to appear on your next or scheduled lists. Someday maybe items begin with a question mark, ?.

    ? lose weight and exercise more

Hidden

Hidden items begin with a hash mark, #. Such items are ignored by etm save for appearing in the folder view. Stick a hash mark in front of any item that you don't want to delete but don't want to see in your other views.

Defaults

Default entries begin with an equal sign, =. These entries consist of @key value pairs which then become the defaults for subsequent entries in the same file until another = entry is reached.

Suppose, for example, that a particular file contains items relating to "project_a" for "client_1". Then entering

= @k client_1:project_a

on the first line of the file and

=

on the twentieth line of the file would set the default keyword for entries between the first and twentieth line in the file.

@key-value pairs

Note in the following that when the required value in an @key value pair is a either a datetime or an time period, special formats are used.

etm supports fuzzy parsing of datetimes. Suppose, for example, that it is currently Wednesday, November 14, 2012. Then, in @keys calling for a datetime, values would expand as illustrated below.

In @keys calling for a time period, values would expand as follows:

@a alert

The specification of the alert(s) to use with the item. One or more alerts can be specified in an item. E.g.,

@a 10m, 5m
@a 1h: s

would trigger the alert(s) specified by default_alert in your etm.cfg at 10 and 5 minutes before the starting time and a (s)ound alert one hour before the starting time.

Similary, the alert

@a 2d: e; who@what.com, where2@when.org; filepath1, filepath2

would send emails to the two listed recipients exactly 2 days (48 hours) before the starting time of the item with the item summary as the subject, with file1 and file2 as attachments and with the body of the message composed using email_template from your etm.cfg.

Finally,

@a 0: p; program_path

would execute program_path at the starting time of the item.

The format for each of these:

@a <trigger times> [: action [; arguments]]

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

Note: either e or p can be combined with other actions in a single alert but not with one another.

@b beginby

An integer number of days before the starting date time at which to begin displaying begin by notices.

@c context

Intended primarily for tasks to indicate the context in which the task can be completed. Common contexts include home, office, phone, computer and errands. The "next view" supports this usage by showing undated tasks, grouped by context. If you're about to run errands, for example, you can open the "next view", look under "errands" and be sure that you will have no "wish I had remembered" regrets.

@d description

An elaboration of the details of the item to complement the summary.

@e extent

A time period string such as 1d2h (1 day 2 hours). For an action, this would be the elapsed time. For a task, this could be an estimate of the time required for completion. For an event, this would be the duration. The ending time of the event would be this much later than the starting datetime.

@f done; due

Datetimes; tasks, delegated tasks and task groups only. When a task is completed an @f done; due entry is added to the task. Similarly, when a job from a task group is completed in etm, an &f done; due entry is appended to the job and it is removed from the list of prerequisites for the other jobs. In both cases done is the completion datetime and due is the datetime that the task or job was due. The completed task or job is shown as finished on the completion date. When the last job in a task group is finished an @f done; due entry is added to the task group itself reflecting the datetime that the last job was done and, if the task group is repeating, the &f entries are removed from the individual jobs.

Another step is taken for repeating task groups. When the first job in a task group is completed, the @s entry is updated using the setting for @o (above) to show the next datetime the task group is due and the @f entry is removed from the task group. This means when some, but not all of the jobs for the current repetition have been completed, only these job completions will be displayed. Otherwise, when none of the jobs for the current repetition have been completed, then only that last completion of the task group itself will be displayed.

Consider, for example, the following repeating task group which repeats monthly on the last weekday on or before the 25th.

+ pay bills @s 11/23 @f 10/24;10/25
  @r m &w MO,TU,WE,TH,FR &m 23,24,25 &s -1
  @j organize bills &q 1
  @j pay on-line bills &q 3
  @j get stamps, envelopes, checkbook &q 1
  @j write checks &q 2
  @j mail checks &q 3

Here "organize bills" and "get stamps, envelopes, checkbook" have no prerequisites. "Organize bills", however, is a prerequisite for "pay on-line bills" and both "organize bills" and "get stamps, envelops, checkbook" are prerequisites for "write checks" which, in turn, is a prerequisite for "mail checks".

The repetition that was due on 10/25 was completed on 10/24. The next repetition was due on 11/23 and, since none of the jobs for this repetition have been completed, the completion of the group on 10/24 and the list of jobs due on 11/23 will be displayed initially. The following sequence of screen shots show the effect of completing the jobs for the 11/23 repetition one by one on 11/27.

@g goto

The path to a file or a URL to be opened using the system default application when the user presses Control-G in the GUI.

@j job

Component tasks or jobs within a task group are given by @j job entries. @key value entries prior to the first @j become the defaults for the jobs that follow. &key value entries given in jobs use & rather than @ and apply only to the specific job.

Many key-value pairs can be given either in the group task using @ or in the component jobs using &:

The key-value pair &q (queue position) can only be given in component jobs where it is required. 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.

@k keyword

A heirarchical classifier for the item. Intended for actions to support time billing where a common format would be client:job:category. etm treats such a keyword as a heirarchy so that an action report grouped by month and then keyword might appear as follows

    27.5h) Client 1 (3)
        4.9h) Project A (1)
        15h) Project B (1)
        7.6h) Project C (1)
    24.2h) Client 2 (3)
        3.1h) Project D (1)
        21.1h) Project E (2)
            5.1h) Category a (1)
            16h) Category b (1)
    4.2h) Client 3 (1)
    8.7h) Client 4 (2)
        2.1h) Project F (1)
        6.6h) Project G (1)

An arbitrary number of heirarchical levels in keywords is supported.

@l location

The location at which, for example, an event will take place.

@m memo

Further information about the item not included in the summary or the description. Since the summary is used as the subject of an email alert and the descripton is commonly included in the body of an email alert, this field could be used for information not to be included in the email.

@o overdue

Repeating tasks only. One of the following choices: k) keep, r) restart, or s) skip. Details below.

@p priority

Either 0 (no priority) or an intger between 1 (highest priority) and 9 (lowest priority). Primarily used with undated tasks.

@r repetition rule

The specification of how an item is to repeat. Repeating items must have an @s entry as well as one or more @r entries. Generated datetimes are those satisfying any of the @r entries and falling on or after the datetime given in @s.

A repetition rule begins with

@r frequency

where frequency is one of the following characters:

The @r frequency entry can, optionally, be followed by one or more &key value pairs:

Repetition examples:

Optionally, @+ and @- entries can be given.

A repeating task may optionally also include an @o <k|s|r> entry (default = k):

@s starting datetime

When an action is started, an event begins or a task is due.

@t tags

A tag or list of tags for the item.

@u user

Intended to specify the person to whom a delegated task is assigned. Could also be used in actions to indicate the person performing the action.

@v value

A key from values in your etm.cfg. Used in actions to apply a billing rate to time spent in an action. E.g., with

    values:
        br1: 45.0
        br2: 60.0

then entries of @v br1 and @e 2h30m in an action would entail a value of 45.0 * 2.5 = 112.50.

@z time zone

The time zone of the item, e.g., US/Eastern. The starting and other datetimes in the item will be interpreted as belonging to this time zone.

@+ include

A datetime or list of datetimes to be added to the repetitions generated by the @r rrule entry.

@- exclude

A datetime or list of datetimes to be removed from the repetitions generated by the @r rrule entry.

File paths

etm offers two heirarchical ways of organizing your data: by file path and by keyword. There are no hard and fast rules about how to use these heirarchies but the goal is a system that makes complementary uses of file path and keyword and fits your needs. As with any filing system, planning and consistency are paramount.

For example, one pattern of use for a business would be to use file path for people and keyword for client-project-category.

Similarly, a family could use file path to separate personal and shared items for family members, for example:

root etm data directory
    dag
    erp
    shared
        holidays
        birthdays
        events

Here

~dag/.etm/etm.cfg
~erp/.etm/etm.cfg

would both contain datadir entries specifying the common root data directory. Additionally, if these configuration files contained, respectively, the entries

calendars
- [dag, true, dag]
- [erp, false, erp]
- [shared, true, shared]

and

calendars
- [erp, true, erp]
- [dag, false, dag]
- [shared, true, shared]

then, by default, both dag and erp would see the entries from their personal files as well as the shared entries and each could optionally view the entries from the other's personal files as well. See the Preferences tab for details on the calendars entry.