Name	Last modified	Size

Parent Directory		-
CHANGES	2009-02-27 13:29	16K
etm-647.tar.gz	2010-08-07 12:04	157K
examples/	2013-01-19 10:47	-
images/	2008-08-19 15:17	-
yeagtd-110.tgz	2009-02-27 13:29	59K
yeagtd-src-110.tgz	2009-02-27 13:29	39K

Contents

Overview
The Project File
- Fields
- Illustrative Recurrence Rules
How Repetition Works
Log and Project Reports
Task Reports
Tips
Installation
License

Overview

YAML, a recursive acronym for "YAML Ain't Markup Language", is a human readable and writable data serialization format. YAML's contribution to yeaGTD is to make the format of the project files extremely simple both to create and to read.

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.

Suppose, for example, that the halogen bulb in the study lamp needs to be replaced. Getting this done requires first removing the old bulb, taking it with you to the hardware store to buy a similar replacement bulb and finally installing the new bulb. Though simple, this example illustrates several aspects of GTD.

1. Projects usually involve a series of steps, some of which must be carried out consecutively, e.g., the old bulb must be removed before it can be taken to the hardware store and the replacement must be purchased before it can be installed.

2. The steps of a project are carried out in a context which may vary from step to step, e.g., removing the old bulb and installing the new one both take place in the context "Home" but buying the required bulb takes place in the context "Errands".

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 away to run errands. 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, "Install new bulb" would not be displayed until "Buy required bulb" had been completed.

GTD thus requires:

planning:	a method for storing and organizing all the bits.
acting:	a method for displaying just the information you need, when you need it.

The Project File

Here are yeaGTD project files for the "Fix light" project and a simple repeating project:

   A non-repeating project                A repeating project
-----------------------------         ----------------------------

  agenda: Fix light                   agenda: Get a haircut

  tasks:                              date: 2007-05-18
  - a: Remove old halogen bulb
    c: Home                           frequency: WEEKLY
                                      interval: 2
  - a: Buy similar bulb               weekday: FR
    c: Errands                        next: RESTART

  - a: Install new bulb               tasks:
    c: Home                           - a: Get a haircut
                                        c: Errands

Simple, aren't they?

A slightly more complicated project is illustrated below as it appears in my editor (textmate) and in the internal yeaGTD project window.

Project files are text files with the extension .yaml that belong to your projects directory and its sub-directories. Each project file can include the following specifications though only agenda, tasks and, for each task, a and c, are required.

Fields

agenda:	The title for the project. Required.
date:	The target date for the project in YYYY-MM-DD format. Defaults to the current date if omitted. Fuzzy parsing of dates is supported in the internal yeaGTD project editor and activated by entering a period. E.g. if it is currently Friday August 15 2008, then entering: `thu.` would give `2008-08-21` `25.` would give `2008-08-25` `9/17.` would give `2008-09-17` `9/1/17.` would give `2009-01-17`
early:	The number of days in advance of date at which project tasks, by default, should become available. When early is omitted, date could be interpreted as the starting date for the project. Alternatively, when early is set, date could be interpreted as the ending date for the project which begins early days before date. In either case, project tasks become available early days before date by default.
finished:	The date on which the last of the project tasks was completed in YYYY-MM-DD format. Normally this date is entered automatically when the last task is completed and should not need to be edited. Fuzzy parsing of dates is supported in the internal yeaGTD project editor - see the discussion under date.
frequency:	The base period for repetitions. Must be one of the following: `ONCE`, `DAILY`, `WEEKLY`, `MONTHLY` or `YEARLY`. Use `frequency: ONCE` to disable repetition. Defaults to `ONCE` if omitted.
interval:	The number of frequency periods between repetitions. E.g. `frequency: WEEKLY` and `interval: 2` would call for repetitions every two weeks. Defaults to `1` if omitted. Ignored with `frequency: ONCE`.
extent:	Enter either an integer number of repetitions or a repeat until date in YYYY-MM-DD format to specify when the repetitions will end. Omit to repeat forever. Ignored with `frequency: ONCE`. Fuzzy parsing of dates is supported in the internal yeaGTD project editor - see the discussion under date.
notes:	Notes for the overall project. These are free-form notes save for the fact that notes that begin with a date in YYYY-MM-DD format are treated as log entries. Notes for specific tasks can be entered under Show tasks. Lines in project notes and task n that begin with a date in YYYY-MM-DD format followed by a semicolon are are regarded as log entries. For those who need to keep track of time spent, log entries that follow the date with a time duration in H:MM format followed, optionally, by a key phrase and then by a semicolon and, optionally, other text are treated as time entries. Such entries are not only included in log reports but also in time reports where time aggregates for the chosen outline structure are provided. When creating notes (or task n's) with a text editor, begin each note on a new line preceded by a minus sign: notes: - This is a note. - 2008-05-01; This is a log entry. - 2008-05-01 1:15 Smith Account; This is a time entry. When using the internal yeaGTD project editor, omit the leading minus sign and simply begin each note on a new line.
mode:	Treat project tasks as consecutive or concurrent. CONSECUTIVE: This is the default mode. For projects where tasks should be completed consecutively by default. A task must be completed before the next task becomes available. Consecutive tasks with the same p value, however, are treated as CONCURRENT and become available simultaneously but only after earlier tasks with different p values have been completed. CONCURRENT: This is a convenience setting for todo lists and similar projects where tasks are independent and the order in which they are completed does not matter. All tasks are treated as concurrent.
next:	Ignored with `frequency: ONCE`. This setting has no effect for the next repetition if the project was completed on or before the target date. Otherwise, the effect is as follows: KEEP: The next target date occurs at the next date satisfying the recurrence rule that falls after the previous target date. This is for projects that can be completed late but cannot be skipped. E.g., You have to file quarterly reports and, while they can be filed late, none can be skipped. The report for the last quarter of 2007 was due on January 1, 2008 but you didn't get around to filing it until April 21: frequency: MONTHLY interval: 3 monthday: 1 next: KEEP The target date for the next quarterly report is still April 1, 2008, so the report for the first quarter is already past due. SKIP: Regard a target date prior to current date as having been automatically completed. The next target date is the first date satisfying the recurrence rule which falls on or after the current date. This is for projects for which late completion is not an option. E.g., The trash gets picked up every Tuesday and you forgot to put out the trash yesterday, Tuesday, April 22, 2008: frequency: WEEKLY interval: 1 weekday: TU next: SKIP The next target date is Tuesday, April 29, 2008. RESTART: Create a new recurrence rule which preserves everything from the original other than the starting date (date), then choose as the new starting date the first date which is consistent with the new rule and which falls on or after finished. Finally set the next target date equal to the second date from the new recurrence rule, i.e., the first date from the rule after the starting date. Note that the next target date will thus be at least frequency times interval later than finished. E.g., You want to get a haircut every two weeks and Friday is the most convenient day. The target date for your last haircut was Friday, April 4, 2008 but you didn't get it until the following Thursday: frequency: WEEKLY interval: 2 weekday: FR next: RESTART The next target date will be Friday, April 25.
weekday:	Repetitions occur only on these week days. Defaults to `(MO, ..., SU)` or, equivalently `(1, ..., 7)`, if omitted. E.g., `MO(-1)` with `frequency: MONTH` and `interval: 1`, would repeat on the last Monday in every month or `MO(+3)` would repeat on the third Monday every month. Ignored with `frequency: ONCE`.
monthday:	Repetitions occur only on these days of the month. Defaults to `(1, ..., 31)` if omitted. Ignored with `frequency: ONCE`.
week:	Repetitions occur only on these week numbers. If left void defaults to `(1, ..., 53)`. Ignored with `frequency: ONCE`.
month:	Repetitions occur only on these month numbers. If left void defaults to `(1, ..., 12)`. Ignored with `frequency: ONCE`. The entries for weekday, monthday, week and month can either be a single choice, e.g., `MO`, or a comma separated list enclosed in parentheses, e.g., `(TU(+2), TU(+4))`.

tasks: The following can be specified for each task.

a:
The action or title of the selected task. Required.

c:
The context for the task. Select from a drop-down list of existing contexts or specify a new context. Required.

d:
The target date for the task either as an absolute date in YYYY-MM-DD format or as an integer number of days in advance of date. For repeating projects, absolute dates are converted to an equivalent number of days before date. The value of d for the next repetition is then set to the that number of days before the next project target date. Tasks for projects in which both date and d are void become available as soon as the project is created and have the current date as the target date. Fuzzy parsing of dates is supported in the internal yeaGTD project editor - see the discussion under date.

The remaining days displayed for a task shows the difference between the current date and the relevant task target date. When the current date is later than the target date, the difference is preceded by a minus sign to indicate that the task is past due. Remaining days is empty for tasks in which the target date is void since they are always due on the current date and thus never past due. An X is displayed for completed tasks.

e:
The number of days in advance of the target date for the task at which the task should become available (provided that all prior non-concurrent tasks have been completed). Defaults to the project setting for early if left void. Ignored if both date and d are void.

p:
The concurrent character. With mode: CONSECUTIVE, consecutive tasks with the same concurrent character are treated as concurrent and become available simultaneously. With mode: CONCURRENT then this field is ignored and all tasks are treated as concurrent.

f:
The date on which the task was finished in YYYY-MM-DD format. A date corresponding to the current date is created when the project is marked completed in yeaGTD but a date could be entered manually. Clearing the value of f changes the status of the task from finished to unfinished. Fuzzy parsing of dates is supported in the internal yeaGTD project editor - see the discussion under date.

n:
Task notes. These are free-form notes save for the fact that lines that begin with a date in YYYY-MM-DD format format are treated as log entries. See the discussion under notes above.

a:	The action or title of the selected task. Required.
c:	The context for the task. Select from a drop-down list of existing contexts or specify a new context. Required.
d:	The target date for the task either as an absolute date in YYYY-MM-DD format or as an integer number of days in advance of date. For repeating projects, absolute dates are converted to an equivalent number of days before date. The value of d for the next repetition is then set to the that number of days before the next project target date. Tasks for projects in which both date and d are void become available as soon as the project is created and have the current date as the target date. Fuzzy parsing of dates is supported in the internal yeaGTD project editor - see the discussion under date. The remaining days displayed for a task shows the difference between the current date and the relevant task target date. When the current date is later than the target date, the difference is preceded by a minus sign to indicate that the task is past due. Remaining days is empty for tasks in which the target date is void since they are always due on the current date and thus never past due. An X is displayed for completed tasks.
e:	The number of days in advance of the target date for the task at which the task should become available (provided that all prior non-concurrent tasks have been completed). Defaults to the project setting for early if left void. Ignored if both date and d are void.
p:	The concurrent character. With `mode: CONSECUTIVE`, consecutive tasks with the same concurrent character are treated as concurrent and become available simultaneously. With `mode: CONCURRENT` then this field is ignored and all tasks are treated as concurrent.
f:	The date on which the task was finished in YYYY-MM-DD format. A date corresponding to the current date is created when the project is marked completed in yeaGTD but a date could be entered manually. Clearing the value of f changes the status of the task from finished to unfinished. Fuzzy parsing of dates is supported in the internal yeaGTD project editor - see the discussion under date.
n:	Task notes. These are free-form notes save for the fact that lines that begin with a date in YYYY-MM-DD format format are treated as log entries. See the discussion under notes above.

Illustrative Recurrence Rules

Once every other week:              Monthly on the 2nd and 15th:
   frequency:  WEEKLY                  frequency: MONTHLY
   interval: 2                         monthday: (2,15)

The first Monday in every month:    Monthly on the first and last days:
   frequency: MONTHLY                  frequency: MONTHLY
   interval: 1                         monthday: (1,-1)
   weekday: MO
                                    30 days from the last completion:
The third Monday in every month:       frequency: DAILY
   frequency: MONTHLY                  interval: 30
   interval: 1                         next: RESTART
   weekday: MO(+3)
                                    Every August 13th which is a Friday:
The last Monday in every month:        frequency: YEARLY
   frequency: MONTHLY                  month: 8
   interval: 1                         monthday: 13
   weekday: MO(-1)                     weekday: FR

Weekly on Tu and Th for 5 weeks:    The first Tuesday after a Monday in
   frequency: WEEKLY                November every 4 years
   interval: 1                      (Presidential election day):
   weekday: (TU,TH)                    frequency: YEARLY
   extent: 10                          interval: 4
                                       month: 11
                                       weekday: TU
                                       monthday: (2,3,4,5,6,7,8)

How Repetition Works

When processing an unfinished repetition of a project, finished is void and the target date for the repetition is date. You choose the value of date for the first repetition and, to avoid unpredictable results, the date you choose should satisfy the recurrence rule, e.g., if repetitions are to occur monthly on the first Saturday, then the date you choose for the first repetition should be the first Saturday in some month. After the first repetition, date will be automatically set.

Projects for which next is SKIP are automatically "completed" when late, i.e., if the current date is later than date then finished is automatically set equal to the current date-time. Otherwise, a project is completed when the last action of the project is completed and finished is automatically set to the completion date-time of the last task. A number of automatic actions follow when a project is completed in either way:

If extent is an integer and greater than one then it is decremented by one. If extent is an integer and less than or equal to one, then no further action is taken. (This was the last repetition.)
Otherwise, next date is computed from the recurrence rule taking account of the values of finished, date, next and extent as follows:
If finished is no later than date then the project was completed on time and next date is tentatively set equal to the next date from the recurrence rule falling after date. If finished is later than date, then next date is tentatively set equal to
- the next date from the recurrence rule falling after date if next is KEEP
- the next date from the recurrence rule falling after the current date if next is SKIP
- the next date from a new recurrence rule if next is RESTART. The new rule is obtained from the original by choosing a new starting date which (i) is consistent with other aspects of the original rule and (ii) is the earliest such date that falls on or after finished. Finally, set the target date equal to the second date from the new recurrence rule.
Finally, if extent is a date and the tentative value of next date is later than extent, then no further action is taken. (This was the last repetition.) Otherwise there is at least one more repetition of the project to complete:
- A complete archive copy of project file with all dates, notes and so forth for the just finished repetition is made. This file is named using the date the repetition was finished using the format "YYYY-MM-DD.yaml" and placed in a folder with the same name as the original project file but with the ".yaml" extension removed, e.g., "path/ToDo.yaml" would be archived as "path/ToDo/2008-08-08.yaml".
- log entries (lines that begin with a date in YYYY-MM-DD format) are deleted in notes and each task n.
- d is converted, if necessary, to a number of days before the current value of date for each task.
- date is set equal to the next date computed above.
- for each task, f is reset to None.
- finished is reset to None

Save for some automatic resetting and clearing, repeating projects are exactly like non-repeating ones. The target date for the current repetition is given by date; target dates for tasks are determined by date and the value of d for the task; tasks become available on a date determined by the target date and the values of early and e; and the value of f for a task is either empty for tasks that have not been finished or it contains the datetime that the task was finished for the current repetition.

Log and Project Reports

On the left below is a log report for the project Economics 370 grouped first by month and then by key phrase. On the right is the project report for the same project.

Task Reports

A report on the tasks for the next numdays (set in ~/.yeagtdrc) can be generated either from the console or gui version as illustrated below.

Tips

Create a convenient one-keystroke alias for yeagtddata by adding the following to your ~./bash_profile (replacing 't' with whatever you like):
```
alias t='yeagtddata'
```
Download examples.tgz and unpack it in your GTD directory. These files will show you what's possible and you can copy and/or modify them for your own uses.
Need to delegate an action to someone else? Use two actions, one for delegating the task and another for following up and assign the latter the d date at which you want to be reminded.
Create a Someday project for ideas you would like to think about later omitting date but setting mode: CONCURRENT and then enter each idea as an action with an appropriate review date for the associated d.

Want a recurrent project that repeats on the last day of each month in which you can begin a subsequent copy before the current copy is completed? Create two similar project files, one for the odd months and one for the even months.:

      Odd Months                     Even Months
-----------------------        -------------------------
frequency: YEARLY              frequency: YEARLY
month: (1,3,5,7,9,11)          month:  (2,4,6,8,10,12)
monthday: (-1)                 monthday: (-1)

Installation

Put yeagtd, yeagtddata and yeagtdhelp somewhere in your path, say ~/bin, and make them executable.
Make sure that you have installed the python modules (py)yaml, dateutil (for repetition) and wxPython (for the graphical interface). They are not included in the standard python installation but are easily added.

(py)yaml: http://pyyaml.org/

dateutil: http://labix.org/python-dateutil

wxPython: http://www.wxpython.org/
Command line usage
- Run "yeagtddata -h" for complete usage information.
GUI usage
- Run yeagtd to open the gui interface and press '?' to see a list of available commands.

(py)yaml:	http://pyyaml.org/
dateutil:	http://labix.org/python-dateutil
wxPython:	http://www.wxpython.org/

The first time you run either yeagtd, yeagtddata or yeagtdhelp, the following files and directories will be created if they don't already exist:

the configuration file, ~/.yeagtdrc
the project files directory, ~/yeaGTD
the ToDo project, ~/yeaGTD/ToDo.yaml

You can move the project files directory where ever you like provided that you update the path in ~/.yeagtdrc.

Current users. If you are already using yeagtd, you will need to use yeaconvert which is included in the distribution to update the format of your existing gtd files to the new format. Running:

yeaconvert

at the command line will process all the files in the gtddir folder specified in your ~/.yeagtdrc and send the results to standard output. When you are satisfied with the results, backup your existing gtddir folder and then run:

yeaconvert w

to update your files.

License

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 2 of the License, or (at your option) any later version. This program is provided 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.