.TH "tdl" 1 "May 2003" "1.4" .SH NAME tdl \- To do list manager .SH SYNOPSIS tdl [\-q] .br tdl [\-q] add|edit|defer|log .br tdl [\-q] list|done|undo|report .br tdl [\-q] remove|above|below|into|clone|copyto .br tdl [\-q] postpone|ignore|open .br tdl [\-q] which|version|help .br tdla [\-q] .br tdll [\-q] .br tdls [\-q] .br tdld [\-q] .br tdlg [\-q] .SH DESCRIPTION A program for managing a to-do list. .PP 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 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 .B exit command (see exit command) .br * Hitting (i.e. end of file on stdin) .br * Hitting , 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. .br * The .B 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. .pp All forms may take .I \-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 .B tdll when changing into a directory, to list outstanding work in that directory. .PP Any command that modifies the database will rename the old database to a file called .B .tdldb.bak before writing out the new .B .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 .B remove command.) .SH SUBCOMMANDS .B tdl above .I index_to_insert_above .I index_to_move ... .br .B tdl before .I index_to_insert_above .I index_to_move ... .PP 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. .P .ce 1 --ooOOoo-- .PP .B tdl add .I [@datespec] .I [parent_index] .I [priority] .I text_for_node .br .B tdla .I [@datespec] .I [parent_index] .I [priority] .I text_for_node .PP The .B add command is used to add a new entry to the database. .PP .B datespec is the time at which the entry will be visible when the database is printed with the .B list command. It defaults to now. The format for datespec is described in the .B "DATE SPECIFICATION" section later in this page. .PP .B 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. .PP .B priority is one of .IR urgent , .IR high , .IR normal , .IR low " or" .IR verylow . Normal is the default if this argument is not specified. Priorities may be abbreviated (even to just the first letter.) .PP .B 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.) .PP If no database exists, the .B add command will create it automatically (in the current directory, unless the .B TDL_DATABASE environment is set, in which case this specifies the path to use). .P .ce 1 --ooOOoo-- .PP .B tdl below .I index_to_insert_below .I index_to_move ... .br .B tdl after .I index_to_insert_below .I index_to_move ... .PP 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. .P .ce 1 --ooOOoo-- .PP .B tdl clone .I index_to_clone ... .PP 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. .P .ce 1 --ooOOoo-- .PP .B tdl copyto .I new_parent_index .I index_to_clone ... .PP The copyto command is very similar to the .B 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. .P .ce 1 --ooOOoo-- .PP .B tdl create .PP 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. .PP 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 .B 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. .P .ce 1 --ooOOoo-- .PP .B tdl defer .I [@datespec] .I index_to_change... .PP 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. .PP An example of use is .P tdl> defer @+fri 1 2.1... 5 .P which defers entries 1, 2.1 and all its children, and 5 until the following Friday. To list deferred entries, use .I list \-p , to defer entries indefinitely, see .I postpone command. To re-activate deferred or postponed entries, see .I open command. .P .ce 1 --ooOOoo-- .PP .B tdl done .I @datespec .I index_of_done_entry ... .br .B tdld .I @datespec .I index_of_done_entry ... .PP The .B done command is used to mark one or more tasks as completed. The effects are as follows: .IP o The entries no longer appear on the default listing (tdl list / tdll) .IP o The entries are eligible to appear on the report list (tdl report) .IP o The entries are eligible for removal by the purge command (tdl purge.) .PP 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. .PP .B 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 .B report command for a particular range of reported times. .PP The format for datespec is described in the .B "DATE SPECIFICATION" section later in this page. .P .ce 1 --ooOOoo-- .PP .B tdl edit .I index_to_change .I [new_text] .PP 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.) .PP Note, in earlier versions, edit could be used to change the start-time of one or more entries. This is now handled by the .B defer command. .P .ce 1 --ooOOoo-- .PP .B exit .PP 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. .br The exit command writes any pending updates to the database before exiting. Compare the .B quit command, which loses all updates made during the current tdl run. .P .ce 1 --ooOOoo-- .PP .B tdl export .I filename .I index_to_export ... .PP This command is used to create a new TDL database (whose name is given by the .I 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. .P .ce 1 --ooOOoo-- .PP .B tdl help .PP This command displays a summary of use of each of the commands. .P .ce 1 --ooOOoo-- .PP .B tdl ignore .I index_to_ignore ... .PP 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. .br 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. .br 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. .br If you need to un-ignore an entry, just .B undo it .P .ce 1 --ooOOoo-- .PP .B tdl import .I filename .PP This command is used to merge entries from the TDL database .I filename into the default TDL database (i.e. the one that most of the other commands would be accessing). .PP 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. .P .ce 1 --ooOOoo-- .PP .B tdl into .I new_parent_index .I indices_to_move ... .PP This command moves one or more entries under a new parent entry. It is equivalent to the .B above command when the .B new_parent_index argument has ".0" appended to it. .P .ce 1 --ooOOoo-- .PP .B tdl list .I [\-v] .I [\-a] .I [\-p] .I [\-m] .I [\-1...9] .I [] .I [|...] .br .B tdll .I [\-v] .I [\-a] .I [\-p] .I [\-m] .I [\-1...9] .I [] .I [|] .I [|