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.

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.

Search

Entering a regular expession in the search bar of the GUI or passing the expression as an option to outline view using '-s' works differently than the filters described above in two ways:

1) Search applies to all items processed by etm. This means all undated items and at least one occurance of all dated items are included in searches. Filters, on the other hand, apply only to undated items and those between '-b BEGIN' (default today) and '-e END' (default 6 days after BEGIN).

2) Search identifies items in which any field matches the expression. Thus '-s smith' would match items that have 'smith' (case insensitive) in the title, context, keyword, location, note or anywhere else. On the other hand, a filter such as '-k smith' would only match items with 'smith' in the keyword field.

sudo python setup.py install

sudo easy_install -U etm

setuptools-0.6c11-py2.6.egg.sh

mv setuptools-0.6c11-py2.6.egg.sh setuptools-0.6c11-py2.6.egg

sudo sh setuptools-0.6c11-py2.6.egg

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.

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