Items in etm begin with a type character such as an asterisk (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 order in which such pairs are entered does not matter.

Sample entries

Characters and Types

~ Action

A record of an action involving the expenditure of time (@e) and/or money (@x). Actions are not reminders, they are instead records of how time and/or money was actually spent. Action lines begin with a tilde, ~.

    ~ picked up lumber and paint @s mon 3p @e 1h15m @x 127.32

Entries such as @s mon 3p, @e 1h15m and @x 127.32 are discussed below under Item details. Action entries form the basis for time and expense billing using action reports - see help/reports.

* 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 conference @s 9a wed @e 2d8h

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

An event without an @e entry or with @e 0 is regarded as a reminder and, since there is no extent, will not be displayed in the week view.

^ 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: abc123def

- 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. If the task also has an @b begin-by entry, then advance warnings of the task will begin appearing the specified number of days before the task is due. An @e entry in a task is interpreted as an estimate of the time required to finish the task.

% Delegated task

A task that is assigned to someone else, usually the person 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 and paint      &q 1
      @j cut pieces                   &q 2
      @j assemble                     &q 3
      @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.

Dates

Fuzzy dates and time periods

When either a datetime or an time period is to be entered, special formats are used in etm. Examples include entering a starting datetime for an item using @s, jumping to a date using Ctrl-J and calculating a date using F5.

Suppose, for example, that it is currently 8:30am on Friday, February 15, 2013. Then, fuzzy dates would expand into the values illustrated below.

Note that 12am is the default time when a time is not explicity entered. E.g., +2/15 in the examples above gives 12:00am on April 15.

To avoid ambiguity, always append either 'a', 'p' or 'h' when entering an hourly time, e.g., use 1p or 13h.

Time periods are entered using the format DdHhMm where D, H and M are integers and d, h and m refer to days, hours and minutes respectively. For example:

As an example, if it is currently 8:50am on Friday February 15, 2013, then entering now + 2d4h30m into the date calculator would give 2013-02-17 1:20pm. If, at the same time, an item were saved on a system in the US/Eastern time zone which contained the entry @s now @z Australia/Sydney then the expanded value would be @s 2013-02-16 12:50am, which is "now" in Sydney.

Dates and times are always stored in etm data files as times in the time zone given by the entry for @z. On the other hand, dates and times are always displayed in etm using the local time zone of the system. In the previous illustration, for example, the data file would contain @s 2013-02-16 12:50am @z Australia/Sydney but this item would be displayed as starting at 2013-02-15 8:50am on a system in the US/Eastern time zone.

Anniversary substitutions

An anniversary substitution is an expression of the form !YYYY! that appears in an item summary. Consider, for example, the occassion

^ !2010! anniversary @s 2011-02-20 @r y

This would appear on Feb 20 of 2011, 2012, 2013 and 2014, respectively, as 1st anniversary, 2nd anniversary, 3rd anniversary and 4th anniversary.The suffixes, st, nd and so forth, depend upon the translation file for the locale.

@key-value pairs

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

The alert

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

would send an email 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.

Similarly, the alert

@a 10m: t; 9191234567@vtext.com, 9197654321@txt.att.net

would send a text message 10 minutes before the starting time of the item to the two mobile phones listed (using 10 digit area code and carrier mms extension) together with the settings for sms in etm.cfg. If no numbers are given, the number and mms extension specified in sms.phone will be used. Here are the mms extensions for the major US carriers:

Alltel          @message.alltel.com
AT&T            @txt.att.net
Nextel          @messaging.nextel.com
Sprint          @messaging.sprintpcs.com
SunCom          @tms.suncom.com
T-mobile        @tmomail.net
VoiceStream     @voicestream.net
Verizon         @vtext.com

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 the following 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. When notices are displayed they will be sorted by the item's starting datetime and then by the item's priority, if any.

@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 entry is added to the task. When the task has a due date, ; due is appended to the entry. Similarly, when a job from a task group is completed in etm, an &f done or &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, if added, 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 or @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. Note that the datetime given in @s will only be included if it matches one of the datetimes generated by the @r entry.

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 action_rates key

Actions only. A key from action_rates in your etm.cft to apply to the value of @e. Used in actions to apply a billing rate to time spent in an action. E.g., with

    minutes: 6
    action_rates:
        br1: 45.0
        br2: 60.0

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

@w action_markups key

A key from action_markups in your etm.cfg to apply to the value of @x. Used in actions to apply a markup rate to expense in an action. E.g., with

    weights:
        mr1: 1.5
        mr2: 10.0

then entries of @w mr1 and @x 27.50 in an action would entail a value of 27.50 * 1.5 = 41.25.

@x expense

Actions only. A currency amount such as 27.50. Used in conjunction with @w above to bill for action expenditures.

@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. If only a date is provided, 12:00am is assumed.

@- exclude

A datetime or list of datetimes to be removed from the repetitions generated by the @r rrule entry. If only a date is provided, 12:00am is assumed.

Note that to exclude a datetime from the recurrence rule, the @- datetime must exactly match both the date and time generated by the recurrence rule.

Folders

etm offers two heirarchical ways of organizing your data: by folder (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 folder 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 folders for people and keywords for client-project-category.

Similarly, a family could use folders 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.