tdl(1)

NAME
tdl - To do list manager

SYNOPSIS
tdl [-q] add|edit|log
tdl [-q] list|done|undo|report
tdl [-q] remove|above|below|into
tdl [-q] which|version|help
tdla [-q]
tdll [-q]
tdld [-q]
tdlg [-q]

DESCRIPTION
A small program for managing a to-do list.

All forms may take -q as the first command line argument. Currently, this suppresses the warning message if no existing database can be found. The intended use is for using tdll when changing into a directory, to list outstanding work in that directory.

Any command that modifies the database will rename the old database to a file called .tdldb.bak before writing out the new .tdldb (The backup file will be in the same directory as the main one.) This allows for one level of database recovery, if the database is corrupted or a command is issued in error which causes large losses of data (e.g. misuse of the remove command.)

SUBCOMMANDS
tdl above index_to_insert_above index_to_move ...
tdl before index_to_insert_above index_to_move ...

This command moves one or more entries to a new location in the tree. The first index specifies the entry which will end up immediately below the moved entries after the operation. As a special case, you can specify the final component of the first argument as zero. In this case, the moved entries appear as the last children of the parent node afterwards.

--ooOOoo--

tdl add [@datespec] [parent_index] [priority] text_for_node
tdla [@datespec] [parent_index] [priority] text_for_node

The add command is used to add a new entry to the database.

datespec is the time at which the entry will be visible when the database is printed with the list command. It defaults to now. The format for datespec is described in the DATE SPECIFICATION section later in this page.

parent_index is the index of the parent node (e.g. 1 or 2.4). This defaults to the root node if missing, i.e. a new top-level entry is created.

priority is one of urgent, high, normal, low or verylow. Normal is the default if this argument is not specified. Priorities may be abbreviated (even to just the first letter.)

text_for_node is the text describing the task for this entry. If this is more than a single word, you will need to quote it to make the shell keep it as a single argument to tdl. The text may span multiple lines (i.e. if you hit return whilst the quotation marks are still open in the shell.)

If no database exists, the add command will create it automatically (in the current directory, unless the TDL_DATABASE environment is set, in which case this specifies the path to use).

--ooOOoo--

tdl below index_to_insert_below index_to_move ...
tdl after index_to_insert_below index_to_move ...

This command moves one or more entries to a new location in the tree. The first index specifies the entry which will end up immediately above the moved entries after the operation. As a special case, you can specify the final component of the first argument as zero. In this case, the moved entries appear as the first children of the parent node afterwards.

--ooOOoo--

tdl create

This command is used to create a .tdldb file in the current directory (or at the location specified by the environment variable TDL_DATABASE). If the database file is already found to exist, a warning will be printed and the command has no effect.

The situation where you are likely to use this command is where there is already a .tdldb file in another directory further up the path from this one. Most of the tdl commands will find and use this other database file, assuming that you want to share it across all the directories in the tree. You might want to use a single database across an entire large project, for example. The create command will ignore any .tdldb file found in an ancestor directory. It always operates in either the current directory or on the file pointed to by TDL_DATABASE.

--ooOOoo--

tdl done @datespec index_of_done_entry ...

tdld @datespec index_of_done_entry ...

The done command is used to mark one or more tasks as completed. The effects are as follows:

o   The entries no longer appear on the default listing (tdl list / tdll)

o   The entries are eligible to appear on the report list (tdl report)

o   The entries are eligible for removal by the purge command (tdl purge.)

If the string "..." is appended to an index, it means that entry and all its descendents. This provides a quick way to mark a whole sub-tree of tasks as being completed.

datespec is the time at which the entry/entries should be marked as having been completed. The default is to mark them completed at the current time. The competion time of an entry affects whether it is shown by the report command for a particular range of reported times.

The format for datespec is described in the DATE SPECIFICATION section later in this page.

--ooOOoo--

tdl edit [@datespec] index_to_change... [new_text]

This command is used to change an entry.

The text of an entry may be changed, in which case the '...' form of the index is not allowed; exactly one entry must be specified.

Also, the start time of an entry or tree of entries may be changed. (This affects whether the entries are shown by the list command, i.e. the effect is the same as providing a future date to the add command.)

Both the start time and text of an entry may be modified at the same time. In this case, only a single index may be provided (the '...' form is not allowed in this case.)

The format for the date is described in the DATE SPECIFICATION section below.

--ooOOoo--

tdl export filename index_to_export ...

This command is used to create a new TDL database (whose name is given by the filename argument). The initial contents of the new database are the entries specified by the list of indices following the filename, in that order. Each index becomes a top-level entry of the new database. The operation is read-only on the original database.

--ooOOoo--

tdl help

This command displays a summary of use of each of the commands.

--ooOOoo--

tdl import filename

This command is used to merge entries from the TDL database filename into the default TDL database (i.e. the one that most of the other commands would be accessing).

You might use this command if you had a number of separate TDL databases, and wanted to merge their entries to form one combo database.

--ooOOoo--

tdl into new_parent_index indices_to_move ...

This command moves one or more entries under a new parent entry. It is equivalent to the above command when the new_parent_index argument has ".0" appended to it.

--ooOOoo--

tdl list [-v] [-a] [-m] [<min-priority>] [<parent_index> ...]
tdll [-v] [-a] [-m] [<min-priority>] [<parent_index> ...]

The list command is used to display the entries in the database. By default, only entries that have not been marked done and which don't have start times deferred into the future are shown. If you want to display all entries, include the -a option (which means 'all'). If you want to display the dates and times when the entries were added and/or done, include the -v option (which means 'verbose').

By default, only entries having normal, high or urgent priority are shown. To change the minimum priority shown, specify the min-priority argument. For example, 'tdll h' will only show entries with priority high or urgent.

By default, the whole database is scanned. If you only want to show part(s) of the database, additional arguments can be given. These are the indices of the top node of each part of the database you want to show. So if your database contains entries with indices 1, 2, 2.1, 2.2, 2.2.1, 3 and 4, the command

tdl list -a 2

will show all entries 2, 2.1, 2.2 and 2.2.1, whether or not they are completed.

By default, the listing is produced with colour highlighting. The -m option can be used to produce a monochrome listing instead. Alternatively, the TDL_LIST_MONOCHROME enviroment variable can be set (to any value) to achieve the same effect.

The colours are assigned as follows:

Colour | Meaning
Red | Urgent task
Yellow | High priority task
White | Normal priority task
Cyan | Low priority task, done task
Blue | Very low priority task
Green | Captions

--ooOOoo--

tdl log
tdlg

This command is used to add a new entry and mark it done immediately. It is most useful in conjunction with the report command, to record unexpected extra tasks you had to do.

The arguments for the log command are the same as those for the add command.

--ooOOoo--

tdl pri new_priority index_to_change ...

This command changes the priority of one or more entries. The indices are in the same format as those in the output of the list command. The new_priority argument takes the same possible values as for the add command.

--ooOOoo--

tdl purge since_epoch [entry_index...]

This command is used to remove old done entries from the database. It is much more convenient than repeated remove commands.

The since_epoch argument specifies a time. The format for this argument is described in the DATE SPECIFICATION section later. Entries that were marked done (using the done command) before that epoch will be purged.

Zero or more entry_indices may be given. These restrict the purging to just those entries and their descendents. The default is to purge the entire database.

--ooOOoo--

tdl remove index_to_remove ...

Completely remove one or more entries from the database. The indices are the same format as those shown in the output of the done command.

If the string "..." is appended to an index, it means that entry and all its descendents. This provides a quick way to remove a whole sub-tree of tasks.

--ooOOoo--

tdl report start_time [end_time]

The report command produces a report (in bulleted list format) of tasks completed in a certain time period. This is useful if (for example) you have to write a weekly summary of the work you've done.

The default for the end of the time period is the current time, if the end_time argument is not present. The start of the period to report on must always be specified. The format for the time arguments is described in the DATE SPECIFICATION section later. Examples :

tdl report 1w

will list all tasks completed in the previous week, whereas

tdl report 2w 1w

will list all tasks completed between 2 and 1 weeks ago.

--ooOOoo--

tdl undo index_of_entry_to_undo ...

This command cancels the effect of the done command for one or more entries, e.g. after they have been mistakenly marked as done.

If the string "..." is appended to an index, it means that entry and all its descendents. This provides a quick way to re-open a whole sub-tree of tasks.

--ooOOoo--

tdl usage

Same as tdl help (q.v.)

--ooOOoo--

tdl version

Show the version number of the software.

--ooOOoo--

tdl which

Show the filename of the database that tdl accesses in the current context.

DATE SPECIFICATIONS

The commands add, done, purge, report, take arguments defining dates (with add and done it is optional). Dates may be specified in several formats, shown by the following examples:

-1h | exactly 1 hour ago
-2d | exactly 2 days ago
+1w | exactly 1 week in the future
+1m | exactly 1 month (30 days) in the future
+2y | exactly 2 years in the future
-1d-0815 | 08:15am yesterday
+1d-08 | 8am tomorrow
+1w-08 | 8am on the same day as today next week
+6h-08 | 8am on the day containing the time 6 hours ahead of now
.-08 | 8am today
.-20 | 8pm today
20011020 | absolute : 12 noon on 20th October 2001
011020 | absolute : 12 noon on 20th October 2001 (current century)
1020 | absolute : 12 noon on 20th October 2001 (current century and year)
20 | absolute : 12 noon on 20th October 2001 (current century, year and month)
20011020-081500 | absolute : 08:15am on 20th October 2001
20011020-0815 | absolute : 08:15am on 20th October 2001 (seconds=0)
20011020-08 | absolute : 08:00am on 20th October 2001 (minutes=seconds=0)
011020-08 | absolute : 08:00am on 20th October 2001 (minutes=seconds=0, current century)
etc | (see below)
-sun | 12 noon on the previous Sunday
+sat | 12 noon on the following Saturday
+sat-08 | 8am on the following Saturday
-tue-0815 | 08:15am on the previous Tuesday
etc | (see below)

In the 'all-numeric' format, the rule is that dates can have fields omitted from the start (assumed to be the current value), and times can have fields omitted from the end (assumed to be zero, except if the hours figure is missing it is assumed to be 12, since most work is done in the day.)

In the 'weekday and time' format, the time rule is the same: missing minutes and seconds are taken as zero and missing hours as 12. If the weekday is the same as today, the offset is always 7 days in the required direction. If the weekday is not the same as today, the offset will always be less than 7 days in the required direction.

In the 'relative' format, when a time is included as well, the procedure is as follows. First the time is determined which is the given number of hours, days etc away from the current time. Then the specified time on that day is used. The main use for this is to specify times like '8am yesterday'. Obviously some of the more uses of this mode are rather far-fetched.

For the weekday and relative formats, the sign is actually optional. The default sign (implying past (-) or future (+)) will then be assumed depending on the command as shown below:

Command | Default | Reason
add | + | Add entries with deferred start times
done | - | Entries have been completed at some time in the past
report | - | Reporting on earlier completed tasks not future ones
purge | - | Tasks won't be completed in the future, so no need to purge future ones

AUTHOR

The author is Richard P. Curnow <richard@rrbcurnow.freeuk.com>. If that fails to get through, try <rpc@myself.com> or <richard.curnow@go.to>.

ACKNOWLEDGEMENTS

I got the idea from a program called devtodo. I liked what that program did and the command line approach to using it, but I ran into lots of compilation problems with it on older C++ installations. The path of least resistance turned out to be to hack up a C program to do a similar job.

ENVIRONMENT

TDL_DATABASE
    If this variable is set, it defines the name of the file to use for holding the database of tasks. If the variable is not set, the search approach described in the FILES section is used.

TDL_LIST_MONOCHROME
    If this variable is set, the output from the list command is produced in monochrome instead of colour (the default).

FILES

./.tdldb, ../.tdldb, ../../.tdldb, ...
    If the TDL_DATABASE environment variable is not present, the file .tdldb in the current directory is used, if that is present. If not, the same file in the parent directory is used, and so on, until the root directory of the filesystem is reached. If the database is still not found, a new one will be created in the current directory (except for options that don't modify the database, such as list, help and version.)

If you want to have a .tdldb file in every directory, the suggested approach is to set the TDL_DATABASE environment variable to "./.tdldb". So in a Bourne-like shell (sh, bash, zsh, ksh etc), you'd write

    TDL_DATABASE=./.tdldb
    export TDL_DATABASE

and in a C-like shell (csh, tcsh etc) you'd write

    setenv TDL_DATABASE ./.tdldb

If you want to share .tdldb files between directory hierarchies in some non-standard way, the suggested approach is to use symbolic links to do this, for example:

    cd project1
    ln -s ../project2/.tdldb .

BUGS
Please report them to the author.