2 @c {{{ Main header stuff
6 @settitle User guide for the tdl program
7 @c @setchapternewpage off
10 @dircategory Utilities
12 * tdl: (tdl). To-do-list management utility
18 @title The tdl program
19 @subtitle This manual describes how to use
20 @subtitle the tdl program for managing to-do-lists.
21 @author Richard P. Curnow
23 @vskip 0pt plus 1filll
24 Copyright @copyright{} 2001,2002,2003,2004,2005 Richard P. Curnow
34 * Introduction:: What the tdl program does
35 * Installation:: Compiling and installing the software
36 * Usage:: Quickstart guide and examples of use
37 * Reference:: Reference section
45 tdl is a lightweight program for managing a 'to-do' list of pending jobs that
48 It supports the following features :
50 @item 1 database per directory, or per tree of directories (tdl searches up
51 through parent directories to find the database, so you can have one per
52 project, for example.)
54 @item add new entries, mark them done, edit the text of entries
56 @item add a new entry and immediately mark it done (e.g. to log tasks you did
57 which you tackled immediately you got them.)
59 @item organise the entries in a tree structure (sub-tasks of other tasks etc)
61 @item move the tasks around and re-organise the hierarchy.
63 @item list the tasks in the database (default listing excludes 'done' tasks,
64 but these can be shown too if desired). The listing is in colour by default,
65 with monochrome output as an option.
67 @item allows entries to be prioritised (priorities shown in different colours
68 on listing). The listing can selectively show only entries at or above a given
71 @item the start time for tasks can be set, to allow for 'deferred' tasks with
72 start times in the future. Such tasks are excluded from the default listing.
74 @item tasks can be marked 'postponed' to avoid them cluttering up the normal
77 @item track date added and date completed for each task
79 @item generate report of tasks completed in a given earlier time period (useful
80 if you have to produce a weekly summary of your work done, for example)
82 @item import and export entries, to allow splitting and merging of databases.
86 @item runs on a Linux console or in a terminal window. It currently generates
87 a coloured listing (monochrome is an option), so a colour xterm or rxvt is
90 @item tdl can run a single sub-command direct from the command line, or it can
91 run in an interactive mode where several sub-commands can be used within a
92 single run. If the GNU readline library is available at compile time, the
93 interactive mode features command line editing and various completion and usage
100 This section discusses installation
103 * Build from source:: Installing tdl from source code
104 * Packaging:: Notes for package builders
107 @c {{{ Build from source
108 @node Build from source
109 @section Installing tdl from source code
110 The procedure for installing tdl from source code is as follows:
113 @item @strong{Unpack the sources}
115 gunzip < tdl-1.0.tar.gz | tar xvf -
119 @item @strong{Configure the makefile}
121 tdl does not use a @code{./configure} mechanism (yet!) to configure options.
122 You have to manually edit @file{Makefile}. The variables you may want to edit are
126 The choice of C compiler
128 The choice of flags to pass to the C compiler
130 The parent directory where the binaries and documentation will be installed.
131 You'd normally set this to @file{/usr/local} or @file{/usr}, unless you use a
132 stow or stow-like approach, or are building a distribution package.
134 If you want readline support in the interactive mode (highly recommended),
135 uncomment the appropriate line in the Makefile, and if necessary edit the path
136 for the include directory where @file{readline.h} and @file{history.h} can be
137 found. Note that a @file{readline} subdirectory is assumed to be suffixed onto
138 whatever path you define.
140 Likewise, edit the path for the directory where @file{libreadline} and
141 @file{libhistory} can be found.
144 @item @strong{Compile the sources}
149 @item @strong{Install the software}
154 @item (Optional) @strong{Build the documentation}
156 This assumes you have the @file{makeinfo} and @file{tex} tools on your path.
161 @item (Optional) @strong{Install the documentation}
163 Currently, there are no Makefile targets for this. Pick the documentation
164 formats you want to keep and install them manually to the appropriate places.
169 @section Notes for package builders
170 For building a Slackware package, you could follow the steps above except for
178 make install DESTDIR=./pkg
179 (copy appropriate docs into subdirectories of pkg)
184 Packagers for other distributions may be able to adapt this. (The point the
185 example is making is that @file{Makefile} contains support for using a variable
186 @var{DESTDIR} in this way.)
188 An example spec file for RedHat packaging is in the file
189 @file{tdl.spec.sample}.
198 This section contains examples of using tdl.
201 * Getting started:: Getting started with tdl
204 @c {{{ Getting started
205 @node Getting started
206 @section Getting started
207 This section shows how you can get started with tdl.
209 Let's assume you have a working directory for a project, and you want to
210 maintain a to-do list for things you need to do on that project. Let's assume
211 the working directory for the project is @file{/home/foobar/myproject}. Then
212 you'd start by entering the following commands into your shell:
215 % cd /home/foobar/myproject
219 Now, lets say you have some tasks to keep track of:
223 tdl> add "Write user guide"
224 tdl> add "Write release notes"
225 tdl> add "Fix bug where empty data file causes core dump"
230 The above sequence will add 3 tasks to your newly created database. A few days
231 later, you might come back to the project and think "Hmmm. What did I need to
232 do next?" You can enter
237 2 Write release notes
238 3 Fix bug where empty data file causes core dump
242 This shows another feature of tdl. If you pass a sub-command (and its
243 arguments, if any) on the tdl command line, tdl will execute just that command,
244 and return you to your shell prompt. However, if you run tdl with no
245 arguments, it will go into its interactive mode. For a single command like
246 @command{list} in this situation, you'd probably find the direct method
249 Suppose you fix the bug. Then you could enter
255 after which the list command would only show the first two tasks as still being
261 2 Write release notes
265 The @command{add}, @command{list} and @command{done} commands may be all that
266 you need in some cases. However, another useful command is @command{report},
267 which will summarise all the tasks you completed in a given period. For
268 example, you could list everything you completed in the last 7 days like this
272 - Fix bug where empty data file causes core dump
276 The other commands in tdl are mostly to do with changing the order of tasks in
277 the database, assigning them priorities, and so on.
285 * Start and Exit:: Starting and exiting tdl
286 * Command line flags:: Flags that can be used from the shell command line
287 * Node specification:: How to reference existing nodes
288 * Command list:: Alphabetical list of all commands
289 * Shortcuts:: Quick access to tdl commands from the shell
290 * Interrupting:: How to make tdl stop whilst it is running
291 * Location:: How tdl finds the database file to use
292 * Completion:: Completion facilities
293 * Datespec:: How dates are specified
294 * Backup file:: How tdl saves a backup copy of the database
295 * Index specification:: How indices can be specified
298 @c {{{ Start and Exit
300 @section Starting and exiting tdl
301 tdl has a set of functions that can be accessed in two different ways:
304 @item Directly from the command line
308 In the 'direct' method, the function and its arguments are provided on the
309 command line. This mode is useful if you only want to perform a single
310 operation. An example
317 The 'interactive' method is entered when the tdl command is run with no
318 arguments. In this mode, many tdl operations may be performed within a single
319 run of the program. This avoids loading and saving the database for each
320 operation, which may have a small performance benefit. However, if the program
321 is compiled with the readline library, the @key{tab} key will provide various
322 completion functions. An example
331 When in interactive mode, these methods can be used to exit and return to the shell:
334 @item The @command{exit} command (@pxref{exit command})
335 @item Hitting @key{Ctrl-D} (i.e. end of file on stdin)
336 @item Hitting @key{Ctrl-C}, @key{Ctrl-\} etc. The associated signals are
337 caught by tdl and it will attempt to save the database. However, this method
338 is more risky than the first two.
339 @item The @command{quit} command (@pxref{quit command}). @strong{Caution:} this
340 does not save the modified database back to the disk. Only use it if you want
341 to discard all changes made in this tdl run.
346 @c {{{ Command line flags
347 @node Command line flags
348 @section Command line flags
351 * -R:: Open the database read-only
357 @subsection Quiet mode
358 If the @command{-q} flag is specified, various warning and informational
359 messages will be suppressed.
365 @c {{{ Read-only mode
367 @subsection Read-only mode
368 If the @command{-R} flag is specified, the database will be opened in read-only
369 mode. In this case, the database will not be locked, and all commands that
370 modify the database will be barred.
372 This flag can be used together with the @command{-q} flag if required.
381 @subsection Forced unlock
382 If the @command{-u} flag is specified, the database's lockfile will be removed
383 if it is found. This is mainly intended for use when an earlier run has left
384 the database locked after a crash.
386 Care shoule be taken that the database is not currently being accessed by a
387 live process, otherwise updates could be lost by one or other of the processes.
393 @c {{{ Node specification
394 @node Node specification
395 @section Node specification
396 Many commands in tdl require you to refer to an existing entry, for example
398 @item to add a child entry to an existing entry
399 @item to mark an entry as being done
403 There are two ways you can refer to existing nodes
405 @item by the numeric path (as shown by @command{tdl list}).
406 @item by negative numeric path (which is used to refer to a node counted from
407 the end of its parent)
408 @item by the start of the node's text, as long as enough is specified to
409 identify the node unambiguously amongst its peers. In this case, the node must
410 be preceded by a single '.' for many commands.
413 For example, if the database contains
427 then @samp{tdl list 1} will show
436 and @samp{tdl list .fe} will show
443 @samp{tdl list .f} will fail since it is ambiguous which node (1 or 2) is being referenced.
445 @samp{tdl list -- -1} will show
452 (note that @samp{tdl list -1} has a different meaning (show 1 level and summarise subordinate levels), and shows
462 @section Alphabetical list of all commands
463 This section describes each of the tdl subcommands.
465 * above command:: Move entries above (before) another entry
466 * add command:: Add a new entry to the database
467 * after command:: Move entries after (below) another entry
468 * before command:: Move entries before (above) another entry
469 * below command:: Move entries below (after) another entry
470 * clone command:: Make a deep copy of one or more entries
471 * copyto command:: Insert a deep copy of one or more entries into an existing entry
472 * create command:: Create a new database in the current directory
473 * defer command:: Modify starting time of one or more entries
474 * delete command:: Remove 1 or more entries from the database
475 * done command:: Mark 1 or more entries as done
476 * edit command:: Change the text and/or start time of an entry
477 * exit command:: Exit program, saving database
478 * export command:: Export entries to another database
479 * help command:: Display help information
480 * ignore command:: Postpone/partially-remove 1 or more entries
481 * import command:: Import entries from another database
482 * into command:: Move entries to end of new parent
483 * list command:: List entries in database (default from top node)
484 * ls command:: List entries in database (default from top node)
485 * log command:: Add a new entry to the database, mark it done as well
486 * moveto command:: Move entries to end of new parent
487 * narrow command:: Restrict actions to part of the database
488 * open command:: Move 1 or more entries out of postponed state
489 * postpone command::Make 1 or more entries postponed
490 * priority command::Change the priority of 1 or more entries
491 * purge command:: Remove old done entries in subtrees
492 * quit command:: Exit program, NOT saving database
493 * remove command:: Remove 1 or more entries from the database
494 * report command:: Report completed tasks in interval
495 * revert command:: Discard changes and reload previous database from disc
496 * save command:: Save the database to disc and continue working
497 * undo command:: Mark 1 or more entries as not done (cancel effect of 'done')
498 * usage command:: Display help information
499 * version command:: Display program version
500 * which command:: Display filename of database being used
501 * widen command:: Widen the part of the database to which actions apply
504 @c {{{ <--COMMANDS-->
507 @subsection above command
508 The @command{above} command is one of the commands used for re-ordering the
509 entries in the database. The @command{above} and @command{before} commands are
512 The arguments of the @command{above} comamnd are:
515 tdl> above <index_to_insert_above> <index_to_move> ...
518 The first argument is the index of the entry above which the other entries are
519 to be moved. The entries corresponding the 2nd index onwards will be placed in
520 argument order above the first entry.
538 You can move entries between levels in the hierarchy, with the restriction that
539 you cannot move a node so that its new parent would be a descendent of itself.
541 If you want to move entries to the end of the list (i.e. above the bottom of
542 the list), you can use a zero as the index of the reference entry, for example
564 @subsection add command
565 The @command{add} command is run as follows
568 tdl> add [@@datespec] [parent-index] [priority] "Text for node"
571 In the simplest case of adding a new top-level entry to the database, with
572 normal priority, starting now, this could be
575 tdl> add "Wash the dog"
578 In a more complex case, to add a high priority entry underneath entry index 1,
579 with the new entry coming live at 11a.m. next Friday, this would be
582 tdl> add @@+fri-11 1 hi "Wash the dog"
585 If you have several entries to add at once, you can go into an @emph{add} mode.
586 Enter a blank line to get back to the @t{tdl>} prompt.
596 To add an entry direct from your shell, there is an additional shortcut
597 (assuming the appropriate symbolic link was created during the installation
601 % tdla "Wash the dog"
608 @subsection after command
609 The @command{after} and @command{below} commands are synonymous. See the
610 description of @command{below} (@pxref{below command}).
612 @c {{{ before command
614 @subsection before command
615 The @command{above} and @command{before} commands are synonymous. See the
616 description of @command{above} (@pxref{above command}).
620 @subsection below command
621 The @command{below} command is one of the commands used for re-ordering the
622 entries in the database. The @command{below} and @command{after} commands are
625 The arguments of the @command{below} command are:
628 tdl> below <index_to_insert_below> <index_to_move> ...
631 The first argument is the index of the entry below which the other entries are
632 to be moved. The entries corresponding the 2nd index onwards will be placed in
633 argument order above the first entry.
651 You can move entries between levels in the hierarchy, with the restriction that
652 you cannot move a node so that its new parent would be a descendent of itself.
653 This is similar to the description for the @command{above} command
654 (@pxref{above command}).
659 @subsection clone command
660 The @command{clone} command can be used to make a deep copy of one or more
661 entries and add them as new top-level entries in the database. You might use
662 this if you have a task with a set of subtasks, and find that the same subtasks
663 apply to some new task. You could copy the first task, and edit the new
664 top-level task to change its text.
666 The arguments of the @command{clone} command are:
669 tdl> clone <index_to_clone> ...
679 tdl> edit 2 "Polish things"
689 If you want the cloned entries to be children of an existing entry, use the
690 @command{copyto} command (@pxref{copyto command}).
692 @c {{{ copyto command
694 @subsection copyto command
695 The @command{copyto} command is very similar to the @command{clone} command
696 (@pxref{clone command}). The difference is that @command{copyto} inserts the
697 newly created entries as children of an existing entry, rather than making them
698 new top level entries.
700 The arguments of the @command{copyto} command are:
703 tdl> copyto <new_parent_index> <index_to_clone> ...
714 tdl> edit 1.2 "Polish things"
717 @c {{{ create command
719 @subsection create command
720 The @command{create} command can only be used direct from the shell command
721 line. It is @strong{not} supported when tdl is used in its interactive
722 mode.@footnote{This is to avoid confusion over which database file is being
723 accessed if @command{create} were used after other commands had already
724 been used in the same session.}
726 Usually, the @command{create} command will create a new @file{.tdldb} file in
727 the current directory. However, if the @var{TDL_DATABASE} environment
728 variable is set when tdl is run, the path specified by that variable
729 will be used instead and the database will be created there. In both
730 cases, the @command{create} command will refuse to over-write an
731 existing database; an error message will be generated if that is
740 @subsection defer command
741 The @command{defer} command is used to modify the start-time of one or more existing entries. Its argument structure is
744 tdl> defer @@<datespec> <entry_index>[...] ...
747 where the @samp{@@} on the datespec is optional because the argument is
748 required, although the @samp{@@} can be included for consistency with other
749 commands where a datespec is optional.
754 tdl> defer @@+fri 1 2.1... 5
757 which defers entries 1, 2.1 and all its children, and 5 until the following
760 To list deferred entries, use @command{list -p}.
762 To defer entries indefinitely, see @ref{postpone command}.
764 To re-activate deferred or postponed entries, see @ref{open command}.
767 @c {{{ delete command
769 @subsection delete command
770 This command is synonymous with the @command{remove} command (@pxref{remove command}).
772 The argument structure is
774 delete <entry_index>[...] ...
780 @subsection done command
781 The @command{done} command is run as follows
784 done [@@<datespec>] <entry_index>[...] ...
787 The @command{done} command is used to mark one or more tasks as completed. Any
788 number of task indices may be specified.
790 The effects are as follows:
794 The entries no longer appear on the default listing (produced by the
795 @command{list} command without the @samp{-a} option).
797 The entries are eligible to appear on the report list (@pxref{report command})
799 The entries are eligible for removal by the purge command (@pxref{purge
803 If the string "..." is appended to an index, it means that entry and all its
804 descendents. This provides a quick way to mark a whole sub-tree of tasks as
807 No entry may be marked 'done' if it has any children that are still 'open'
808 (i.e. not marked 'done'). (The @samp{...} form of the command marks the
809 deepest entries first to bypass this.)
814 @subsection edit command
815 The @command{edit} command is used to modify the text of an existing entry.
816 Its argument structure is
819 tdl> edit <entry_index> [<new_text>]
822 A single <entry-index> must be given. If <new-text> is provided, this replaces
823 the text describing the specified entry. If no <new-text> is provided, you
824 will be prompted with the old text to edit interactively. (This is only useful
825 if the GNU readline library has been linked in.)
829 To change the text for the entry with index 1,
831 tdl> edit 1 "New description"
838 edit (1)> Wash the dog (edit 'dog' to 'cat')
844 (Note, in earlier versions, @command{edit} could be used to change the
845 start-time of one or more entries. This is now handled by the @command{defer}
846 command (@pxref{defer command}).)
851 @subsection exit command
852 The @command{exit} command is used to exit from tdl when it is used in
853 interactive mode. The @command{exit} command is not available in the command
854 line mode, where it would not make sense. An example:
861 The @command{exit} command writes any pending updates to the database before
862 exiting. (Compare the @command{quit} command (@pxref{quit command}), which
863 @strong{loses} all updates made during the current tdl run.)
865 @c {{{ export command
867 @subsection export command
868 The @command{export} command is run as follows
871 export <filename> <entry_index> ...
874 It is used to export one or more tasks (and their subtasks) to another tdl
875 database file. Perhaps you were keeping all your projects' to-do lists in one
876 combined file, and decide you want to separate the list for a particular
883 1 Tasks for project X
884 2 Tasks for project Y
886 2.2 Write release notes
887 tdl> export /home/foobar/project_y/.tdldb 2.1 2.2
895 @subsection help command
896 The @command{help} command displays help information. When run without
897 arguments, a list of valid commands is produced. Note, this list is slightly
898 different depending on whether the @command{help} command is used through the
899 interactive readline interface or straight from the shell.
903 tdl, Copyright (C) 2001-2004 Richard P. Curnow
904 tdl comes with ABSOLUTELY NO WARRANTY.
905 This is free software, and you are welcome to redistribute it
906 under certain conditions; see the GNU General Public License for details.
908 above : Move entries above (before) another entry
909 add : Add a new entry to the database
910 after : Move entries after (below) another entry
911 below : Move entries below (after) another entry
912 before : Move entries before (above) another entry
913 done : Mark 1 or more entries as done
914 edit : Change the text and/or start time of an entry
915 exit : Exit program, saving database
916 export : Export entries to another database
917 help : Display help information
918 import : Import entries from another database
919 into : Move entries to end of new parent
920 list : List entries in database (default from top node)
921 log : Add a new entry to the database, mark it done as well
922 priority : Change the priority of 1 or more entries
923 purge : Remove old done entries in subtrees
924 quit : Exit program, NOT saving database
925 remove : Remove 1 or more entries from the database
926 report : Report completed tasks in interval
927 undo : Mark 1 or more entries as not done (cancel effect of 'done')
928 usage : Display help information
929 version : Display program version
930 which : Display filename of database being used
932 Enter 'help <command-name>' for more help on a particular command
937 If the @command{help} command is passed the name of a sub-command, it shows help for that command.
942 Add a new entry to the database
945 add [@@<datespec>] [<parent_index>] [<priority>] <entry_text>
947 <index> : 1, 1.1 etc (see output of 'tdl list')
948 <priority> : urgent|high|normal|low|verylow
949 <datespec> : [-|+][0-9]+[shdwmy][-hh[mm[ss]]] OR
950 [-|+](sun|mon|tue|wed|thu|fri|sat)[-hh[mm[ss]]] OR
951 [[[cc]yy]mm]dd[-hh[mm[ss]]]
952 <text> : Any text (you'll need to quote it if >1 word)
957 The @command{help} command is synonymous with the @command{usage} command.
960 @c {{{ ignore command
962 @subsection ignore command
963 The @command{ignore} command puts one or more entries into an @emph{ignored}
964 state. It is actually implemented in the same way as marking them as
965 @emph{done}, but as though they were @emph{done} a very long time ago. Thus,
966 ignored entries will be deleted by any subsequent purge operation.
968 I added this feature because, when applying @command{remove} to several
969 entries, I kept getting tripped up by the indices changing below the entry that
970 was removed (I kept removing the wrong entries later by not using the revised
971 indices). Instead, I can @command{ignore} them and rely on a periodic
972 @command{purge} to clean up the database.
974 Another use for the @emph{ignore} command would be to move moribund entries
975 into a @emph{wastebasket} to stop them cluttering up the normal listing, but
976 without removing them entirely in case you need to reprieve them later.
978 The @command{ignore} command is run as follows
981 ignore <entry_index>[...] ...
986 ignore 20 21.6.3 25... 28.1
989 If you need to @emph{un-ignore} an entry, just @command{undo} it (@pxref{undo
993 @c {{{ import command
995 @subsection import command
996 The @command{import} command is used as follows:
1002 This command is used to merge entries from the TDL database @file{filename}
1003 into the default database (i.e. the one that most of the other commands would
1006 You might use this command if you had a number of separate TDL databases, and
1007 wanted to merge their entries to form one combo database.
1011 @subsection into command
1012 The @command{into} command is used to make one or more entries into sub-entries
1013 of another entry. Its usage is
1016 into <new_parent_index> <index_to_move> ...
1019 The following example shows it use
1035 The @command{into} command is closely related to @command{above},
1036 @command{after}, @command{before} and @command{below}. In fact the following
1037 three commands are equivalent
1040 tdl> into N <indices> ...
1042 tdl> above N.0 <indices> ...
1044 tdl> before N.0 <indices> ...
1050 @subsection list command
1051 The @command{list} command is used to display the tasks in the database. Its argument structure is:
1054 list [-v] [-a] [-m] [-p] [-1..9]
1056 [<parent_index>|<search_condition>...]
1059 When run with no arguments, the list contains all tasks that are
1061 @item not marked 'done', 'ignored', 'deferred' or 'postponed',
1062 @item at any levels of the database (i.e. any number of components in the task's index), and
1063 @item of priority normal or higher.
1066 The arguments have the following functions:
1070 This stands for @emph{verbose}. It means that more information will be shown
1073 This stands for @emph{all}. It means that tasks which are 'done', or which are
1074 'deferred' or 'postponed' (by having arrival times in the future), will be
1075 shown as well as open tasks.
1077 This stands for @emph{postponed}. It means that tasks which are 'deferred' or
1078 'postponed' are shown as well as open tasks.
1080 This stands for @emph{monochrome}. Normally, ANSI escape sequences are
1081 inserted to show the list with colour coding. This flag stops these sequences
1084 If you always want this option, set the @var{TDL_LIST_MONOCHROME} environment
1085 variable to any value. If this variable exists, a monochrome listing will be
1087 @item -1, -2, ..., -9
1088 These options restrict the depth of the tree which is generated. For example,
1089 with the @samp{-1} argument, only the first-level entries in the database are
1090 shown. Sub-entries of these are shown by summary totals. See below for an
1092 @item <min-priority>
1093 Normally (at least, if no indices are specified), only tasks with a priority of
1094 at least @samp{normal} are shown in the list. If you specify this option,
1095 tasks of at least the specified priority are shown. The values you can use are
1096 @samp{urgent}, @samp{high}, @samp{normal}, @samp{low} or @samp{verylow}. Each
1097 can be abbreviated to just its initial letter.
1098 @item <parent_index...>
1099 If you want to list just part of the database, you can specify the indices of
1100 the leading entries for the parts you want to see. Any number of entries can
1101 be included (you could even include an index twice if you wanted to for some
1104 When you specify indices, the behaviour regarding priority changes. If no
1105 @samp{<min-priority>} argument was given, the priority of a sub-entry must be
1106 at least that of the entry with the given index for it to be shown. This is
1107 most useful when the entire sub-tree has a lower than normal priority.
1109 If you use the @samp{-1} ... @samp{-9} options with this option, the depth is
1110 counted relative to the depth of the indexed node that you specify.
1111 @item <search_condition>
1112 Each search condition specifies a case-insensitive substring match that is
1113 applied to all parent indices further on in the arguments. (If no parent
1114 indices are given, all the search conditions are and'ed together and applied to
1115 filter all the nodes that would be shown according to the depth, priority etc
1118 Each search condition takes one of the following forms
1124 In each case, an entry will match if @samp{substring} is actually a substring
1125 of the text of that entry. In the second form (where the number may be 0, 1, 2
1126 or 3), a match occurs if there are up to that many errors in the substring. An
1127 @dfn{error} is a single character inserted, removed or changed.
1129 This option is most useful if you have a large database and can remember you
1130 have an entry somewhere containing particular word(s), but can't remember where
1133 If you need regular expression matching, the best approach would be to run
1134 @command{tdll} from the shell and pipe the output to @command{grep}. The
1135 internal matching does approximate matches with keys up to 31 characters.
1139 The command is best illustrated by examples. Suppose the database contains
1152 where @samp{wibble} and @samp{xxxx} have priority @samp{low}. The following
1153 examples show the list command's behaviour.
1163 (Entry 2 and its child are omitted due to priority. Entry 1.1.1 is omitted
1164 because it is done.)
1176 (Passing these arguments shows the missing entries)
1184 (The list is limited to top level entries. The @samp{[1/1]} indices that entry
1185 1 has 1 open child out of a total of 1 children.)
1192 (This lists the 1.1 subtree, showing that there is 1 open child out of a total
1204 (In the first case the substring @samp{ww} must occur exactly in the entry's
1205 text. In the second case, the string @samp{wu} in @samp{wubble} matches
1206 @samp{ww} with a single error so a match occurs.)
1210 @subsection ls command
1211 This is synonymous with the @command{list} command (@pxref{list command}). It
1212 is provided for people who are too used to typing @command{ls} in their shell.
1216 @subsection log command
1217 The @command{log} command is very similar to the @command{add} command, except
1218 that it immediately marks the new entry as done.It is the equivalent of using
1219 @command{add} followed by @command{done} on the new entry. It is run as follows:
1222 log [@@<datespec>] [<parent_index>] [<priority>] <entry_text>
1225 You might use the @command{log} command if complete a new task immediately but
1226 want to make sure you log it for use in producing your weekly report (using
1227 the @command{report} command, @xref{report command}.)
1229 If you have several entries to add at once, you can go into an @emph{log} mode.
1230 Enter a blank line to get back to the @t{tdl>} prompt.
1240 To add an entry direct from your shell, there is an additional shortcut
1241 (assuming the appropriate symbolic link was created during the installation
1245 % tdlg "Wash the dog"
1249 (the ending @samp{g} on the shortcut was chosen as the final letter of the word
1250 @samp{log}. The shortcut @samp{tdll} was already allocated for the
1251 @command{list} subcommand.)
1254 @c {{{ moveto command
1255 @node moveto command
1256 @subsection moveto command
1257 The @command{moveto} and @command{into} commands are synonymous. See the
1258 description of @command{into} (@pxref{into command}).
1260 @c {{{ narrow command
1261 @node narrow command
1262 @subsection narrow command
1263 The @command{narrow} command can be used to limit the effects of later commands
1264 to operate within a particular sub-tree of your database. Because the indices
1265 you specify for the later operations have the common prefix omitted, this can
1266 save typing if you have many changes to make within the same subtree.
1268 The usage of the @command{narrow} command is
1271 narrow <new_root_index>
1274 The following example illustrates:
1301 If your listings are in colour, the common prefix is coloured in blue whilst
1302 the paths below the root of the sub-tree are shown in the usual green. (In
1303 monochrome mode, there is no distinction.)
1305 Whilst your view is narrowed, the index of the sub-tree root is shown in square
1306 brackets between @samp{tdl} and @samp{>} (i.e. @samp{[2]} in the example
1309 If you want to operate on the sub-tree root entry itself whilst you are
1310 narrowed, you can use @samp{.} to specify its index (think: current directory
1313 To reverse the effects of the @command{narrow} command, use the @command{widen}
1314 command (@pxref{widen command}).
1316 This command is only available when @command{tdl} is being run interactively,
1317 i.e. when you have a @samp{tdl} prompt. It is not available directly from the
1318 shell (where it wouldn't make much sense).
1322 @subsection open command
1323 The @command{open} command is used to reverse the effect of the @command{defer}
1324 command (@pxref{defer command}) and @command{postpone} command (@pxref{postpone
1325 command}). Its effect is actually to set the arrival time of the entries to
1328 The @command{open} command is used as follows
1330 open <index_to_reopen>[...] ...
1339 @c {{{ postpone command
1340 @node postpone command
1341 @subsection postpone command
1342 The @command{postpone} command is used to make 1 more more entries postponed
1343 indefinitely. Its effect is actually to set the arrival time of the entries a
1344 long way in the future (i.e. it's an extreme form of the 'deferred' feature
1345 available in the @command{add} and @command{defer} commands.) Postponed entries
1346 can be re-activated with the @command{open} command (@pxref{open command}).
1348 The @command{postpone} command is used as follows
1350 postpone <index_to_postpone>[...] ...
1355 postpone 20 21... 25.2
1358 To postpone an entry until a specific time in the future, use the
1359 @command{defer} command (@pxref{defer command}).
1362 @c {{{ priority command
1363 @node priority command
1364 @subsection priority command
1365 The @command{priority} command is used to modify the priority of one or more entries. Its argument structure is
1368 priority <new_priority> <entry_index>[...] ...
1371 The @samp{new_priority} argument is the new priority to be assigned. The
1372 values you can use are @samp{urgent}, @samp{high}, @samp{normal}, @samp{low} or
1373 @samp{verylow}. Each can be abbreviated to just its initial letter.
1375 You can specify at least one @samp{entry_index}. If an index is followed by
1376 @samp{...}, the whole sub-tree under the referenced entry will be modified too.
1380 tdl> priority high 2 4.1...
1383 will modify the priority of entry 2, entry 4.1, and all the entries under 4.1,
1386 @c {{{ purge command
1388 @subsection purge command
1389 The @command{purge} command is used to remove outdated done tasks from the
1390 database. For example, you might want to automatically remove everything you
1391 completed more than 2 months ago.
1393 Its argument structure is
1395 purge <since_datespec> [<ancestor_index> ...]
1398 The @samp{since_datespec} argument specifies a date. All entries which were
1399 marked 'done' before this date will be completely removed from the database.
1401 The default is to scan the entire database for done tasks that meet the date
1402 constraint. You may specify one or more indices to limit the behaviour. In
1403 this case, only the sub-trees headed by these indices will be considered for
1408 tdl> purge -2m 3.1 5
1411 will purge all entries underneath entries 3.1 and 5 which were marked 'done'
1412 more than 2 months ago.
1417 @subsection quit command
1418 The @command{quit} command is used to exit from tdl when it is used in
1419 interactive mode. The @command{quit} command is not available in the command
1420 line mode, where it would not make sense. An example
1427 The @command{quit} command @strong{DOES NOT} write any pending updates to the database before
1428 exiting. (Compare the @command{exit} command (@pxref{exit command}), which
1429 does write all updates made during the current tdl run.)
1431 The main use for the @command{quit} command would be to avoid damaging the
1432 database if a serious error had been made.
1434 @c {{{ remove command
1435 @node remove command
1436 @subsection remove command
1437 The @command{remove} command is used to remove entries from the database. It
1438 differs from purge @pxref{purge command} in that there is no date constraint,
1439 and entries do not have to be marked 'done' to be removed. You might use
1440 @command{remove} if an open tasks no longer needs to be performed.
1442 The argument structure is
1444 remove <entry_index>[...] ...
1447 You can specify one or more entry indices to remove. If an index is followed
1448 by @samp{...}, tdl will remove the whole sub-tree based at that index.
1450 You cannot remove an entry that has sub-entries below it. (The @samp{...}
1451 handling for indices removes the deepest entries first to bypass this.)
1455 tdl> remove 1.5.4 19... 20
1458 will remove entries 1.5.4 and 20, as well as everything whose index starts with
1461 The @command{remove} command acts immediately to remove the specified entries
1462 from the database. A less aggressive command with similar effects is
1463 @command{ignore} (@pxref{ignore command}).
1465 The @command{delete} command (@pxref{delete command}) is provided as a synonmym
1466 for the @command{remove} command.
1469 @c {{{ report command
1470 @node report command
1471 @subsection report command
1472 The @command{report} command is used to show entries that were marked 'done'
1473 within a specific time interval. Its argument structure is
1476 report <start_datespec> [<end_datespec>]
1479 One or two date specifications may be given. If only the start_datespec is
1480 provided, the end_datespec defaults to the present time. The format of both
1481 arguments is described separately. @xref{Datespec}.
1483 For example, suppose you have to write a report on what you have done in the
1484 last week. You could use
1490 The report is produced in a tree structure, mirroring the database structure.
1491 Entries which have 'done' children, but which haven't themselves been marked
1492 done, have their text surrounded by @samp{[[} and @samp{]]}. For example
1508 You could cut-and-paste this text into your report, as a starting point that
1509 you can reformat into a report. Alternatively, if you run the command direct
1510 from the shell prompt line, you can redirect the output to a file,
1513 % tdl report 1w > report.txt
1518 @c {{{ revert command
1519 @node revert command
1520 @subsection revert command
1521 The @command{revert} command discards any changes made in the session and
1522 reloads the in-memory database from disc. If you have used the @command{save}
1523 command (@pxref{save command}) in the session, the database will revert to its
1524 state at the most recent @command{save}. Otherwise it will revert to its state
1525 when @command{tdl} was initially run.
1527 The @command{revert} command does not take any arguments.
1531 @subsection save command
1533 The @command{save} command can be used to write the current in-memory database
1534 out to the disc database file. The behaviour is currently equivalent to the
1535 command @command{exit} followed by re-running @samp{tdl} from the shell.
1537 This command is useful if you tend to do long interactive tdl sessions. It guards against the risks of
1539 @item accidentally typing @samp{quit} when you meant @samp{exit}
1540 @item machine crashes
1541 @item running @samp{tdl} in another window and seeing a stale copy of the database file.
1544 The @command{save} command does not take any arguments.
1548 @subsection undo command
1550 The @command{undo} command reverses the action of the @command{done} command
1551 @pxref{done command}. You can use it to re-open entries, e.g. if you marked
1552 them 'done' by mistake.
1554 Its argument structure is
1556 undo <entry_index>[...] ...
1559 You can specify one or more indices to act on. If an index is suffixed by
1560 @samp{...}, tdl will re-open the entire sub-tree based at that index.
1563 @c {{{ usage command
1565 @subsection usage command
1566 The @command{usage} command is synonymous with the @command{help} command.
1567 @xref{help command}.
1569 @c {{{ version command
1570 @node version command
1571 @subsection version command
1572 The @command{version} command shows the program version.
1580 @c {{{ which command
1582 @subsection which command
1583 The @command{which} command displays the name of the current database file that
1584 tdl is using. An example:
1592 @c {{{ widen command
1594 @subsection widen command
1596 This command reverses the effects of the @command{narrow} command
1597 (@pxref{narrow command}).
1602 tdl> widen [<n_levels>]
1605 The optional @samp{n_levels} parameter tells tdl how many levels to widen the
1606 view. If the parameter is not specified, it defaults to 1. If you try to
1607 widen more levels than the depth of the current sub-tree root node, the
1608 widening will be silently limited to its depth.
1610 This command is only available when @command{tdl} is being run interactively,
1611 i.e. when you have a @samp{tdl} prompt. It is not available directly from the
1612 shell (where it wouldn't make much sense).
1618 @section Shortcut forms of certain commands
1619 For convenience, several shortcut commands are provided to access the most
1620 common tdl operations. (These can be used from the shell command line.)
1624 This is a shortcut for @command{tdl add}, e.g.
1631 This is a shortcut for @command{tdl delete}.
1634 This is a shortcut for @command{tdl log}.
1637 This is a shortcut for @command{tdl list}.
1640 This is another shortcut for @command{tdl list}.
1646 @section Interrupting
1647 Most programs will stop where they are if you hit @key{Ctrl-C}. This is also
1648 true (normally) for tdl. However, tdl intercepts signals like this so that it
1649 can try to write out the database when it is safe to do so. This avoids the
1650 loss of updates made to the database during the current session.
1652 Because of this approach, it is possible that tdl can get stuck in an endless
1653 loop if a bug arises. For this reason, tdl will exit forcibly if @key{Ctrl-C}
1654 is pressed 4 times. After the third press, a warning message is printed.
1656 If tdl has to be terminated in this way, the database will not be written back
1657 out. Therefore, any edits made in the current session will be lost. Also, a
1658 stale lock file will be left behind. The @samp{-u} command line flag should be
1659 used on the next run of tdl to force the removal of this stale lock file.
1663 @section How tdl finds the databse file to use
1664 If the @var{TDL_DATABASE} environment variable is set, its value is taken to be
1665 the name of the database to use. This allows for two distinct modes of use:
1667 @item If you set @var{TDL_DATABASE} to a fixed filename (with a full path), you
1668 can use a single database regardless of your current working directory.
1669 @item If you set @var{TDL_DATABASE} to a relative path (e.g. @file{./.tdldb}),
1670 you will always use a database in the current working directory.
1673 If this environment variable is not set, tdl finds the database by searching up
1674 through the directory tree until it finds a file called @file{.tdldb}. The
1675 idea is to allow for one database per project, by placing the database in the
1676 parent directory of the project. Then as long as your current working
1677 directory is anywhere within the project tree, the database will be found
1680 The only exception to this is the @command{create} command, which always
1681 operates in the current directory (unless @var{TDL_DATABASE} is set, in which
1682 case this variable's value defines the path to use.)
1684 If you wish to share databases between directory trees in some other way, the
1685 recommended method is to use symbolic (or hard) links to make a single database
1686 appear to be in more than one directory.
1692 @section Completion facilities
1693 When tdl has been compiled to use the @emph{readline} library, the interactive
1694 mode supports a number of completion functions, activated with the @key{tab}
1697 In particular, the following are supported:
1701 @item @strong{Command completion}. If @key{tab} is pressed when the command
1702 line is empty, a list of possible commands will be shown. If @key{tab} is
1703 pressed when a partial command has been typed, the command will be completed
1704 immediately if possible, otherwise a list of commands matching the
1705 already-typed prefix will be shown.
1707 @item @strong{Help completion}. If @command{help} or @command{usage} is
1708 already in the buffer, a list of commands will be shown(as above). The
1709 @key{tab} completion works in the same way to complete the name of the command
1710 you want a help summary for.
1712 @item @strong{Priority completion}. If @command{list} or @command{priority} is
1713 at the start of the input buffer and the current word starts with a letter, tdl
1714 will try to complete the name of a priority level if @key{tab} is pressed.
1716 @item @strong{Open task completion}. If @command{done} is at the start of the
1717 input buffer, hitting @key{tab} will show a list of task indices that are still
1718 open. If part of an index has already been typed, the open task indices for
1719 which the typed characters are a prefix will be shown.
1721 @item @strong{Postpone completion}. If @command{postpone} is at the start of
1722 the input buffer, hitting @key{tab} will show a list of tasks that may be
1723 postponed. Tasks marked @emph{done} are excluded. If @command{open} is at the
1724 start of the input buffer, hitting @key{tab} will show a list of tasks that may
1727 @item @strong{Parameter hints}. If some other command is at the start of the
1728 input buffer and @key{tab} is pressed, tdl will show a one-line summary of that
1729 command's parameters.
1737 @section How dates are specified
1738 @multitable @columnfractions .33 .66
1739 @item @strong{Date specification} @tab @strong{Meaning}
1740 @item -1h @tab exactly 1 hour ago
1741 @item -2d @tab exactly 2 days ago
1742 @item +1w @tab exactly 1 week in the future
1743 @item +1m @tab exactly 1 month (30 days) in the future
1744 @item +2y @tab exactly 2 years in the future
1745 @item -1d-0815 @tab 08:15am yesterday
1746 @item +1d-08 @tab 8am tomorrow
1747 @item +1w-08 @tab 8am on the same day as today next week
1748 @item +6h-08 @tab 8am on the day containing the time 6 hours ahead of now
1749 @item .-08 @tab 8am today
1750 @item .-20 @tab 8pm today
1751 @item 20011020 @tab absolute : 12 noon on 20th October 2001
1752 @item 011020 @tab absolute : 12 noon on 20th October 2001 (current century)
1753 @item 1020 @tab absolute : 12 noon on 20th October 2001 (current century and year)
1754 @item 20 @tab absolute : 12 noon on 20th October 2001 (current century, year and month)
1755 @item 20011020-081500 @tab absolute : 08:15am on 20th October 2001
1756 @item 20011020-0815 @tab absolute : 08:15am on 20th October 2001 (seconds=0)
1757 @item 20011020-08 @tab absolute : 08:00am on 20th October 2001 (minutes=seconds=0)
1758 @item 011020-08 @tab absolute : 08:00am on 20th October 2001 (minutes=seconds=0, current century)
1759 @item etc @tab (see below)
1760 @item -sun @tab 12 noon on the previous Sunday
1761 @item +sat @tab 12 noon on the following Saturday
1762 @item +sat-08 @tab 8am on the following Saturday
1763 @item -tue-0815 @tab 08:15am on the previous Tuesday
1764 @item etc @tab (see below)
1767 In the 'all-numeric' format, the rule is that dates can have fields omitted
1768 from the start (assumed to be the current value), and times can have fields
1769 omitted from the end (assumed to be zero, except if the hours figure is missing
1770 it is assumed to be 12, since most work is done in the day.)
1772 In the 'weekday and time' format, the time rule is the same: missing minutes
1773 and seconds are taken as zero and missing hours as 12. If the weekday is the
1774 same as today, the offset is always 7 days in the required direction. If the
1775 weekday is not the same as today, the offset will always be less than 7 days in
1776 the required direction.
1778 In the 'relative' format, when a time is included as well, the procedure is as
1779 follows. First the time is determined which is the given number of hours, days
1780 etc away from the current time. Then the specified time on that day is used.
1781 The main use for this is to specify times like '8am yesterday'. Obviously some
1782 of the possible uses of this mode are rather far-fetched.
1784 For the weekday and relative formats, the sign is actually optional. The
1785 default sign (implying past (-) or future (+)) will then be assumed depending on
1786 the command as shown below:
1788 @multitable @columnfractions .2 .2 .6
1789 @item @strong{Command} @tab @strong{Default} @tab @strong{Reason}
1790 @item add @tab + @tab Add entries with deferred start times
1791 @item edit @tab + @tab Add entries with deferred start times
1792 @item defer @tab + @tab Modify start times of entries
1793 @item done @tab - @tab Entries have been completed at some time in the past
1794 @item log @tab - @tab Entries have been completed at some time in the past
1795 @item report @tab - @tab Reporting on earlier completed tasks not future ones
1796 @item purge @tab - @tab Tasks won't be completed in the future, so no need to purge future ones
1801 @section How tdl saves a backup copy of the database
1802 Whenever tdl writes a modified database to disk, it renames the previous
1803 database by adding @file{.bak} on the end of the filename. Thus @file{.tdldb}
1804 is renamed to @file{.tdldb.bak}.
1806 If you need to restore the previous @file{.tdldb} for any reason (e.g. a gross
1807 mistake during editing, or if a bug causes it to be corrupted), you can
1808 manually rename @file{.tdldb.bak} to @file{.tdldb}.
1810 @c {{{ Index specification
1811 @node Index specification
1812 @section Index specification
1813 Indices may usually be specified as negative values. This counts from the end of the list. The commonest use for this is to add children to an entry you've just typed, e.g.
1816 tdl> add "Parent entry"
1817 tdl> add -1 "Child entry"
1818 tdl> add -1 "Child entry"
1819 tdl> add -1.-1 "Grandchild entry"
1822 There is one example where negative indices are not handled in the usual way.
1823 This is with the @command{list} command (@pxref{list command}). Here, a
1824 negative index could be misinterpreted as a depth option. If you really want
1825 negative indices for the @command{list} command, terminate the options with
1826 @samp{--} before providing indices and search patterns.
1830 @c vim:cms=@c\ %s:fdm=marker:fdc=5:syntax=off