NAME
tdl - To do list manager
SYNOPSIS
tdl [-q]
tdl [-q] add|edit|defer|log
tdl [-q] list|done|undo|report
tdl [-q] remove|above|below|into|clone|copyto
tdl [-q] postpone|ignore|open
tdl [-q] which|version|help
tdla [-q]
tdll [-q]
tdld [-q]
tdlg [-q]
DESCRIPTION
A program for managing a to-do list.
tdl has a set of functions that can be accessed in two different ways:
* Directly from the command line
* Interactively
In the ’direct’ method, the function and its arguments are provided on
the command line. This mode is useful if you only want to perform a
single operation. An example
% tdl add "A task"
%
The ’interactive’ method is entered when the tdl command is run with no
arguments. In this mode, many tdl operations may be performed within a
single run of the program. This avoids loading and saving the database
for each operation, which may have a small performance benefit.
However, if the program is compiled with the readline library, the
<tab> key will provide various completion functions. An example
% tdl
tdl> add "A task"
tdl> exit
%
When in interactive mode, these methods can be used to exit and return
to the shell:
* The exit command (see exit command)
* Hitting <Ctrl-D> (i.e. end of file on stdin)
* Hitting <Ctrl-C>, <Ctrl-> etc. The associated signals are caught by
tdl and it will attempt to save the database. However, this method is
more risky than the first two.
* The quit command (see quit command). Caution: this does not save the
modified database back to the disk. Only use it if you want to discard
all changes made in this tdl run.
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 clone index_to_clone ...
The clone command can be used to make a deep copy of one or more
entries and add them as new top-level entries in the database. You
might use this if you have a task with a set of subtasks, and find that
the same subtasks apply to some new task. You could copy the first
task, and edit the new top-level task to change its text.
--ooOOoo--
tdl copyto new_parent_index index_to_clone ...
The copyto command is very similar to the clone command. The difference
is that copyto inserts the newly created entries as children of an
existing entry, rather than making them new top level entries.
--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 defer [@datespec] index_to_change...
The defer command is used to modify the start-time of one or more
existing entries, where the @ on the datespec is optional because the
argument is required, although the @ can be included for consistency
with other commands where a datespec is optional.
An example of use is
tdl> defer @+fri 1 2.1... 5
which defers entries 1, 2.1 and all its children, and 5 until the
following Friday. To list deferred entries, use list -p , to defer
entries indefinitely, see postpone command. To re-activate deferred or
postponed entries, see open command.
--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 index_to_change [new_text]
This command is used to change the text of an entry. If no [new-text]
is provided, you will be prompted with the old text to edit
interactively. (This is only useful if the GNU readline library has
been linked in.)
Note, in earlier versions, edit could be used to change the start-time
of one or more entries. This is now handled by the defer command.
--ooOOoo--
exit
The exit command is used to exit from tdl when it is used in
interactive mode. The exit command is not available in the command
line mode, where it would not make sense.
The exit command writes any pending updates to the database before
exiting. Compare the quit command, which loses all updates made during
the current tdl run.
--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 ignore index_to_ignore ...
The ignore command puts one or more entries into an ignored state. It
is actually implemented in the same way as marking them as done, but as
though they were done a very long time ago. Thus, ignored entries will
be deleted by any subsequent purge operation.
I added this feature because, when applying remove to several entries,
I kept getting tripped up by the indices changing below the entry that
was removed (I kept removing the wrong entries later by not using the
revised indices). Instead, I can ignore them and rely on a periodic
purge to clean up the database.
Another use for the ignore command would be to move moribund entries
into a wastebasket to stop them cluttering up the normal listing, but
without removing them entirely in case you need to reprieve them later.
If you need to un-ignore an entry, just undo it
--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] [-p] [-m] [-1...9] [<min-priority>]
[<parent_index>|<search_conditions>...]
tdll [-v] [-a] [-p] [-m] [-1...9] [<min-priority>]
[<parent_index>|<search_conditions...]
The list or it’s synonymous ls 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’). The -p option stands for postponed. It means that tasks
which are ’deferred’ or ’postponed’ are shown as well as open tasks.
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.
Also by default, all entries in the database, at any depth, will be
shown. If you only wish to show ’top-level’ entries, for example, you
can use
tdl list -1
This lists level-1 entries. Any level-1 entry with hidden child
entries underneath it will show a summary of how many such children
there are. For example, the output
3 [2/7] A top level entry
means that the entry with index 3 has a total of 7 entries underneath
it, of which 2 are still open and 5 are completed (i.e. they’ve had
’tdl done’ applied to them.)
Because the single digit arguments are used this way for the ’list’
subcommand, the normal ’negative index’ method can’t be used to specify
an entry a certain distance from the end of the list. If you want to
do this, use a syntax like
tdl list -- -1
to show the last index in the array, or
tdl list -2 -- -3 -2 -1
to show level-1 and level-2 entries within the last 3 level-1 entries
in the list.
Each search condition specifies a case-insensitive substring match that
is applied to all parent indices further on in the arguments. (If no
parent indices are given, all the search conditions are and’ed together
and applied to filter all the nodes that would be shown according to
the depth, priority etc arguments).
Each search condition takes one of the following forms
/substring
/substring/1
In each case, an entry will match if substring is actually a substring
of the text of that entry. In the second form (where the number may be
0, 1, 2 or 3), a match occurs if there are up to that many errors in
the substring. An error is a single character inserted, removed or
changed.
This option is most useful if you have a large database and can
remember you have an entry somewhere containing particular word(s), but
can’t remember where it is.
If you need regular expression matching, the best approach would be to
run tdll from the shell and pipe the output to grep. The internal
matching does approximate matches with keys up to 31 characters.
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--
narrow new_root_index
The narrow command can be used to limit the effects of later commands
to operate within a particular sub-tree of your database. Because the
indices you specify for the later operations have the common prefix
omitted, this can save typing if you have many changes to make within
the same subtree.
If your listings are in colour, the common prefix is coloured in blue
whilst the paths below the root of the sub-tree are shown in the usual
green. (In monochrome mode, there is no distinction.)
Whilst your view is narrowed, the index of the sub-tree root is shown
in square brackets between tdl and > (i.e. [2]).
If you want to operate on the sub-tree root entry itself whilst you are
narrowed, you can use . to specify its index (think: current directory
in Unix.)
To reverse the effects of the narrow command, use the widen command
(see widen command).
This command is only available when tdl is being run interactively,
i.e. when you have a tdl prompt. It is not available directly from the
shell (where it wouldn’t make much sense).
--ooOOoo--
tdl open index_to_reopen[...] ...
The open command is used to reverse the effect of the postpone command.
Its effect is actually to set the arrival time of the entries to the
current time.
--ooOOoo--
tdl postpone index_to_postpone[...] ...
The postpone command is used to make 1 more more entries postponed. Its
effect is actually to set the arrival time of the entries a long way in
the future (i.e. it’s an extreme form of the ’deferred’ feature
available through the add and defer commands.) Postponed entries can be
re-activated with the open 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--
quit
The quit command is used to exit from tdl when it is used in
interactive mode. The quit command is not available in the command
line mode, where it would not make sense.
The quit command DOES NOT write any pending updates to the database
before exiting. Compare the exit command, which does write all updates
made during the current tdl run.
The main use for the quit command would be to avoid damaging the
database if a serious error had been made.
--ooOOoo--
tdl remove index_to_remove ...
tdl delete 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.
Where a child entry has been completed in the reporting period, but its
parent has not been completed, the parent text in the report will be
surrounded by ’[[’ and ’]]’. To give one example, this will happen if
the parent has other child entries that haven’t been completed yet.
--ooOOoo--
revert
The revert command discards any changes made in the session and reloads
the in-memory database from disc. If you have used the save command in
the session, the database will revert to its state at the most recent
save. Otherwise it will revert to its state when tdl was initially run.
The revert command does not take any arguments.
--ooOOoo--
save
The save command can be used to write the current in-memory database
out to the disc database file. The behaviour is currently equivalent to
the command exit followed by re-running tdl from the shell.
This command is useful if you tend to do long interactive tdl sessions.
It guards against the risks of
1. accidentally typing quit when you meant exit
2. machine crashes
3. running tdl in another window and seeing a stale copy of the
database file.
The save command does not take any arguments.
--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.
--ooOOoo--
widen n_level
The optional n_levels parameter tells tdl how many levels to widen the
view. If the parameter is not specified, it defaults to 1. If you try
to widen more levels than the depth of the current sub-tree root node,
the widening will be silently limited to its depth.
This command is only available when tdl is being run interactively,
i.e. when you have a tdl prompt. It is not available directly from the
shell (where it wouldn’t make much sense).
Completion facilities
When tdl has been compiled to use the readline library, the interactive
mode supports a number of completion functions, activated with the
<tab> key.
In particular, the following are supported:
Command completion. If <tab> is pressed when the command line is
empty, a list of possible commands will be shown. If <tab> is pressed
when a partial command has been typed, the command will be completed
immediately if possible, otherwise a list of commands matching the
already-typed prefix will be shown.
Help completion. If help or usage is already in the buffer, a list of
commands will be shown (as above). The <tab> completion works in the
same way to complete the name of the command you want a help summary
for.
Priority completion. If list or priority is at the start of the input
buffer and the current word starts with a letter, tdl will try to
complete the name of a priority level if <tab> is pressed.
Open task completion. If done is at the start of the input buffer,
hitting <tab> will show a list of task indices that are still open. If
part of an index has already been typed, the open task indices for
which the typed characters are a prefix will be shown.
Postpone completion. If postpone is at the start of the input buffer,
hitting <tab> will show a list of tasks that may be postponed. Tasks
marked done are excluded. If open is at the start of the input buffer,
hitting <tab> will show a list of tasks that may be opened.
Parameter hints. If some other command is at the start of the input
buffer and <tab> is pressed, tdl will show a one-line summary of that
command’s parameters.
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
HOMEPAGE
The homepage for tdl on the internet is http://www.rc0.org.uk/tdl/
AUTHOR
The author is Richard P. Curnow <rc@rc0.org.uk>.
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.