Initial import of tdl-1.6-pre1
[tdl.git] / tdl.1
1 .TH "tdl" 1 "May 2003" "1.4"
2 .SH NAME
3 tdl \- To do list manager
4 .SH SYNOPSIS
5 tdl  [\-q]
6 .br
7 tdl  [\-q] add|edit|defer|log
8 .br
9 tdl  [\-q] list|done|undo|report
10 .br
11 tdl  [\-q] remove|above|below|into|clone|copyto
12 .br
13 tdl  [\-q] postpone|ignore|open
14 .br
15 tdl  [\-q] which|version|help
16 .br
17 tdla [\-q]
18 .br
19 tdll [\-q]
20 .br
21 tdls [\-q]
22 .br
23 tdld [\-q]
24 .br
25 tdlg [\-q]
26
27 .SH DESCRIPTION
28 A program for managing a to-do list.
29 .PP
30 tdl has a set of functions that can be accessed in two different ways:
31
32     * Directly from the command line
33     * Interactively
34
35 In the 'direct' method, the function and its arguments are provided on the 
36 command line. This mode is useful if you only want to perform a single 
37 operation. An example
38
39     % tdl add "A task"
40     %
41
42 The 'interactive' method is entered when the tdl command is run with no 
43 arguments. In this mode, many tdl operations may be performed within a 
44 single run of the program. This avoids loading and saving the database 
45 for each operation, which may have a small performance benefit. 
46 However, if the program is compiled with the readline library, the 
47 <tab> key will provide various completion functions. An example
48
49     % tdl
50     tdl> add "A task"
51     tdl> exit
52     %
53
54 When in interactive mode, these methods can be used to exit and return 
55 to the shell:
56
57 * The 
58 .B exit 
59 command (see exit command)
60 .br
61 * Hitting <Ctrl-D> (i.e. end of file on stdin)
62 .br
63 * Hitting <Ctrl-C>, <Ctrl-\> etc. The associated signals are caught by 
64 tdl and it will attempt to save the database. However, this method is 
65 more risky than the first two.
66 .br
67 * The 
68 .B quit 
69 command (see quit command). Caution: this does not save the 
70 modified database back to the disk. Only use it if you want to discard 
71 all changes made in this tdl run. 
72
73 .pp
74 All forms may take
75 .I \-q
76 as the first command line argument.  Currently, this suppresses the warning
77 message if no existing database can be found.  The intended use is for using
78 .B tdll
79 when changing into a directory, to list outstanding work in that directory.
80 .PP
81 Any command that modifies the database will rename the old database to a file
82 called
83 .B .tdldb.bak
84 before writing out the new
85 .B .tdldb
86 (The backup file will be in the same directory as the main one.)  This allows
87 for one level of database recovery, if the database is corrupted or a command
88 is issued in error which causes large losses of data (e.g. misuse of the
89 .B remove
90 command.)
91
92
93 .SH SUBCOMMANDS
94 .B tdl above
95 .I index_to_insert_above
96 .I index_to_move ...
97 .br
98 .B tdl before
99 .I index_to_insert_above
100 .I index_to_move ...
101 .PP
102 This command moves one or more entries to a new location in the tree.  The
103 first index specifies the entry which will end up immediately below the moved
104 entries after the operation.  As a special case, you can specify the final
105 component of the first argument as zero.  In this case, the moved entries
106 appear as the last children of the parent node afterwards.
107 .P
108 .ce 1
109 --ooOOoo--
110 .PP
111 .B tdl add
112 .I [@datespec]
113 .I [parent_index]
114 .I [priority]
115 .I text_for_node
116 .br
117 .B tdla
118 .I [@datespec]
119 .I [parent_index]
120 .I [priority]
121 .I text_for_node
122 .PP
123 The
124 .B add
125 command is used to add a new entry to the database.
126 .PP
127 .B datespec
128 is the time at which the entry will be visible when the database is printed
129 with the
130 .B list
131 command.  It defaults to now.  The format for datespec is described in the
132 .B "DATE SPECIFICATION"
133 section later in this page.
134 .PP
135 .B parent_index
136 is the index of the parent node (e.g. 1 or 2.4).  This defaults to the root
137 node if missing, i.e. a new top-level entry is created.
138 .PP
139 .B priority is one of
140 .IR urgent ,
141 .IR high ,
142 .IR normal ,
143 .IR low " or"
144 .IR verylow .
145 Normal is the default if this argument is not specified.  Priorities may be
146 abbreviated (even to just the first letter.)
147 .PP
148 .B text_for_node
149 is the text describing the task for this entry.  If this is more than a single
150 word, you will need to quote it to make the shell keep it as a single argument
151 to tdl.  The text may span multiple lines (i.e. if you hit return whilst the
152 quotation marks are still open in the shell.)
153 .PP
154 If no database exists, the
155 .B add
156 command will create it automatically (in the current directory, unless the
157 .B TDL_DATABASE
158 environment is set, in which case this specifies the path to use).
159 .P
160 .ce 1
161 --ooOOoo--
162 .PP
163 .B tdl below
164 .I index_to_insert_below
165 .I index_to_move ...
166 .br
167 .B tdl after
168 .I index_to_insert_below
169 .I index_to_move ...
170 .PP
171 This command moves one or more entries to a new location in the tree.  The
172 first index specifies the entry which will end up immediately above the moved
173 entries after the operation.  As a special case, you can specify the final
174 component of the first argument as zero.  In this case, the moved entries
175 appear as the first children of the parent node afterwards.
176 .P
177 .ce 1
178 --ooOOoo--
179 .PP
180 .B tdl clone
181 .I index_to_clone ...
182 .PP
183 The clone command can be used to make a deep copy of one or more entries and 
184 add them as new top-level entries in the database. You might use this if you 
185 have a task with a set of subtasks, and find that the same subtasks apply to 
186 some new task. You could copy the first task, and edit the new top-level task 
187 to change its text. 
188 .P
189 .ce 1
190 --ooOOoo--
191 .PP
192 .B tdl copyto
193 .I new_parent_index
194 .I index_to_clone ...
195 .PP
196 The copyto command is very similar to the 
197 .B clone 
198 command. The difference is that copyto inserts the newly created entries as 
199 children of an existing entry, rather than making them new top level entries. 
200 .P
201 .ce 1
202 --ooOOoo--
203 .PP
204 .B tdl create
205 .PP
206 This command is used to create a .tdldb file in the current
207 directory (or at the location specified by the environment variable
208 TDL_DATABASE).  If the database file is already found to exist, a warning will
209 be printed and the command has no effect.
210 .PP
211 The situation where you are likely to use this command is where there is
212 already a .tdldb file in another directory further up the path from this one.
213 Most of the tdl commands will find and use this other database file, assuming
214 that you want to share it across all the directories in the tree.  You might
215 want to use a single database across an entire large project, for example.  The
216 .B create
217 command will ignore any .tdldb file found in an ancestor directory.  It always
218 operates in either the current directory or on the file pointed to by
219 TDL_DATABASE.
220 .P
221 .ce 1
222 --ooOOoo--
223 .PP
224 .B tdl defer
225 .I [@datespec]
226 .I index_to_change...
227 .PP
228 The defer command is used to modify the start-time of one or more existing entries, 
229 where the @ on the datespec is optional because the argument is required, although 
230 the @ can be included for consistency with other commands where a datespec is optional. 
231 .PP
232 An example of use is 
233 .P
234         tdl> defer @+fri 1 2.1... 5
235 .P
236 which defers entries 1, 2.1 and all its children, and 5 until the following Friday. 
237 To list deferred entries, use 
238 .I list \-p
239 , to defer entries indefinitely, see 
240 .I postpone 
241 command. 
242 To re-activate deferred or postponed entries, see 
243 .I open 
244 command. 
245 .P
246 .ce 1
247 --ooOOoo--
248 .PP
249 .B tdl done
250 .I @datespec
251 .I index_of_done_entry ...
252 .br
253 .B tdld
254 .I @datespec
255 .I index_of_done_entry ...
256 .PP
257 The
258 .B done
259 command is used to mark one or more tasks as completed.  The effects are as follows:
260 .IP o
261 The entries no longer appear on the default listing (tdl list / tdll)
262 .IP o
263 The entries are eligible to appear on the report list (tdl report)
264 .IP o
265 The entries are eligible for removal by the purge command (tdl purge.)
266 .PP
267 If the string "..." is appended to an index, it means that entry and all its
268 descendents.  This provides a quick way to mark a whole sub-tree of tasks as
269 being completed.
270 .PP
271 .B datespec
272 is the time at which the entry/entries should be marked as having been
273 completed.  The default is to mark them completed at the current time.  The
274 competion time of an entry affects whether it is shown by the
275 .B report
276 command for a particular range of reported times.
277 .PP
278 The format for datespec is described in the
279 .B "DATE SPECIFICATION"
280 section later in this page.
281 .P
282 .ce 1
283 --ooOOoo--
284 .PP
285 .B tdl edit
286 .I index_to_change
287 .I [new_text]
288 .PP
289 This command is used to change the text of an entry.  If no [new-text] is
290 provided, you will be prompted with the old text to edit interactively. (This
291 is only useful if the GNU readline library has been linked in.)
292 .PP
293 Note, in earlier versions, edit could be used to change the start-time of one 
294 or more entries. This is now handled by the 
295 .B defer 
296 command.
297 .P
298 .ce 1
299 --ooOOoo--
300 .PP
301 .B exit
302 .PP
303 The exit command is used to exit from tdl when it is used in interactive mode. 
304 The exit command is not available in the command line mode, where it would not 
305 make sense. 
306 .br
307 The exit command writes any pending updates to the database before exiting. 
308 Compare the 
309 .B quit 
310 command, which loses all updates made during the current tdl run. 
311 .P
312 .ce 1
313 --ooOOoo--
314 .PP
315 .B tdl export
316 .I filename
317 .I index_to_export ...
318 .PP
319 This command is used to create a new TDL database (whose name is given by the
320 .I filename
321 argument).  The initial contents of the new database are the entries specified
322 by the list of indices following the filename, in that order.  Each index
323 becomes a top-level entry of the new database.  The operation is read-only on
324 the original database.
325 .P
326 .ce 1
327 --ooOOoo--
328 .PP
329 .B tdl help
330 .PP
331 This command displays a summary of use of each of the commands.
332 .P
333 .ce 1
334 --ooOOoo--
335 .PP
336 .B tdl ignore
337 .I index_to_ignore ...
338 .PP
339 The ignore command puts one or more entries into an ignored state. It is 
340 actually implemented in the same way as marking them as done, but as though 
341 they were done a very long time ago. Thus, ignored entries will be deleted 
342 by any subsequent purge operation.
343 .br
344 I added this feature because, when applying remove to several entries, I kept 
345 getting tripped up by the indices changing below the entry that was removed 
346 (I kept removing the wrong entries later by not using the revised indices). 
347 Instead, I can ignore them and rely on a periodic purge to clean up the database.
348 .br
349 Another use for the ignore command would be to move moribund entries into a 
350 wastebasket to stop them cluttering up the normal listing, but without removing 
351 them entirely in case you need to reprieve them later. 
352 .br
353 If you need to un-ignore an entry, just 
354 .B undo 
355 it
356 .P
357 .ce 1
358 --ooOOoo--
359 .PP
360 .B tdl import
361 .I filename
362 .PP
363 This command is used to merge entries from the TDL database
364 .I filename
365 into the default TDL database (i.e. the one that most of the other commands
366 would be accessing).
367 .PP
368 You might use this command if you had a number of separate TDL databases, and
369 wanted to merge their entries to form one combo database.
370 .P
371 .ce 1
372 --ooOOoo--
373 .PP
374 .B tdl into
375 .I new_parent_index
376 .I indices_to_move ...
377 .PP
378 This command moves one or more entries under a new parent entry.  It is
379 equivalent to the
380 .B above
381 command when the
382 .B new_parent_index
383 argument has ".0" appended to it.
384 .P
385 .ce 1
386 --ooOOoo--
387 .PP
388 .B tdl list
389 .I [\-v]
390 .I [\-a]
391 .I [\-p]
392 .I [\-m]
393 .I [\-1...9]
394 .I [<min-priority>]
395 .I [<parent_index>|<search_conditions>...]
396 .br
397 .B tdll
398 .I [\-v]
399 .I [\-a]
400 .I [\-p]
401 .I [\-m]
402 .I [\-1...9]
403 .I [<min-priority>]
404 .I [<parent_index>|<search_conditions...]
405 .br
406 .B tdls
407 .I [\-v]
408 .I [\-a]
409 .I [\-p]
410 .I [\-m]
411 .I [\-1...9]
412 .I [<min-priority>]
413 .I [<parent_index>|<search_conditions...]
414 .PP
415 The
416 .B list
417 or it's synonymous
418 .B ls
419 command is used to display the entries in the database.  By default, only
420 entries that have not been marked
421 .B done
422 and which don't have start times deferred into the future are shown.  If you
423 want to display all entries, include the
424 .B \-a
425 option (which means 'all').  If you want to display the dates and times when
426 the entries were added and/or done, include the 
427 .B \-v
428 option (which means 'verbose').
429 The
430 .B \-p
431 option stands for postponed. It means that tasks which are 'deferred' or 'postponed' 
432 are shown as well as open tasks. 
433 .PP
434 By default, only entries having normal, high or urgent priority are shown.  To
435 change the minimum priority shown, specify the
436 .B min-priority
437 argument.  For example, 'tdll h' will only show entries with priority high or
438 urgent.
439 .PP
440 By default, the whole database is scanned.  If you only want to show part(s) of
441 the database, additional arguments can be given.  These are the indices of the
442 top node of each part of the database you want to show.  So if your database
443 contains entries with indices 1, 2, 2.1, 2.2, 2.2.1, 3 and 4, the command
444 .PP
445 tdl list \-a 2
446 .PP
447 will show all entries 2, 2.1, 2.2 and 2.2.1, whether or not they are completed.
448 .PP
449 Also by default, all entries in the database, at any depth, will be shown.  If
450 you only wish to show 'top-level' entries, for example, you can use
451 .PP
452 tdl list \-1
453 .PP
454 This lists level-1 entries.  Any level-1 entry with hidden child entries
455 underneath it will show a summary of how many such children there are.  For
456 example, the output
457 .PP
458 3 [2/7] A top level entry
459 .PP
460 means that the entry with index 3 has a total of 7 entries underneath it, of
461 which 2 are still open and 5 are completed (i.e. they've had 'tdl done' applied
462 to them.)
463 .PP
464 Because the single digit arguments are used this way for the 'list' subcommand,
465 the normal 'negative index' method can't be used to specify an entry a certain
466 distance from the end of the list.  If you want to do this, use a syntax like
467 .PP
468 tdl list \-\- \-1
469 .PP
470 to show the last index in the array, or
471 .PP
472 tdl list \-2 \-\- \-3 \-2 \-1
473 .PP
474 to show level-1 and level-2 entries within the last 3 level-1 entries in the
475 list.
476 .PP
477 Each 
478 .B search condition 
479 specifies a case-insensitive substring match that is applied to all parent 
480 indices further on in the arguments. (If no parent indices are given, all the 
481 search conditions are and'ed together and applied to filter all the nodes that 
482 would be shown according to the depth, priority etc arguments).
483 .PP
484 Each search condition takes one of the following forms
485 .PP
486     /substring
487     /substring/1
488 .PP
489 In each case, an entry will match if substring is actually a substring of the 
490 text of that entry. In the second form (where the number may be 0, 1, 2 or 3), 
491 a match occurs if there are up to that many errors in the substring. An error 
492 is a single character inserted, removed or changed.
493 .PP
494 This option is most useful if you have a large database and can remember you 
495 have an entry somewhere containing particular word(s), but can't remember where 
496 it is.
497 .PP
498 If you need regular expression matching, the best approach would be to run 
499 tdll from the shell and pipe the output to grep. The internal matching does 
500 approximate matches with keys up to 31 characters. 
501 .PP
502 By default, the listing is produced with colour highlighting.  The
503 .B \-m
504 option can be used to produce a monochrome listing instead.  Alternatively, the
505 .B TDL_LIST_MONOCHROME
506 enviroment variable can be set (to any value) to achieve the same effect.
507 .PP
508 The colours are assigned as follows:
509 .PP
510 .TS
511 tab(&);
512 l | l.
513 _
514 Colour & Meaning
515 _
516 Red & Urgent task
517 Yellow & High priority task
518 White & Normal priority task
519 Cyan & Low priority task, done task
520 Blue & Very low priority task
521 Green & Captions
522 _
523 .TE
524 .P
525 .ce 1
526 --ooOOoo--
527 .PP
528 .B tdl log
529 .br
530 .B tdlg
531 .PP
532 This command is used to add a new entry and mark it done immediately.  It is
533 most useful in conjunction with the
534 .B report
535 command, to record unexpected extra tasks you had to do.
536 .PP
537 The arguments for the
538 .B log
539 command are the same as those for the
540 .B add
541 command.
542 .P
543 .ce 1
544 --ooOOoo--
545 .PP
546 .B narrow
547 .I new_root_index
548 .br
549 .PP
550 The 
551 .B narrow 
552 command can be used to limit the effects of later commands to operate within 
553 a particular sub-tree of your database. Because the indices you specify for 
554 the later operations have the common prefix omitted, this can save typing if 
555 you have many changes to make within the same subtree.
556 .P
557 If your listings are in colour, the common prefix is coloured in blue whilst 
558 the paths below the root of the sub-tree are shown in the usual green. 
559 (In monochrome mode, there is no distinction.)
560 .P
561 Whilst your view is narrowed, the index of the sub-tree root is shown in square 
562 brackets between tdl and > (i.e. [2]).
563 .P
564 If you want to operate on the sub-tree root entry itself whilst you are 
565 narrowed, you can use . to specify its index (think: current directory in Unix.)
566 .P
567 To reverse the effects of the narrow command, use the 
568 .B widen 
569 command (see widen command).
570 .P
571 This command is only available when tdl is being run interactively, i.e. when 
572 you have a tdl prompt. It is not available directly from the shell (where it 
573 wouldn't make much sense). 
574 .P
575 .ce 1
576 --ooOOoo--
577 .PP
578 .B tdl open 
579 .I index_to_reopen[...] ...
580 .PP
581 The open command is used to reverse the effect of the 
582 .B postpone 
583 command. Its effect is actually to set the arrival time of the entries to the 
584 current time. 
585 .P
586 .ce 1
587 --ooOOoo--
588 .PP
589 .B tdl postpone
590 .I index_to_postpone[...] ...
591 .PP
592 The postpone command is used to make 1 more more entries postponed. Its effect 
593 is actually to set the arrival time of the entries a long way in the future 
594 (i.e. it's an extreme form of the 'deferred' feature available through the add and 
595 defer commands.) Postponed entries can be re-activated with the 
596 .B open 
597 command. 
598 .P
599 .ce 1
600 --ooOOoo--
601 .PP
602 .B tdl pri
603 .I new_priority
604 .I index_to_change ...
605 .PP
606 This command changes the priority of one or more entries.  The indices are in
607 the same format as those in the output of the
608 .B list
609 command.  The
610 .B new_priority
611 argument takes the same possible values as for the
612 .B add
613 command.
614 .P
615 .ce 1
616 --ooOOoo--
617 .PP
618 .B tdl purge
619 .I since_epoch
620 .I [entry_index...]
621 .PP
622 This command is used to remove old done entries from the database.  It is much more convenient than repeated
623 .B remove
624 commands.
625 .PP
626 The
627 .B since_epoch
628 argument specifies a time.  The format for this argument is described in the
629 .B "DATE SPECIFICATION"
630 section later. Entries that were marked done (using the
631 .B done
632 command) before that epoch will be purged.
633 .PP
634 Zero or more
635 .B entry_indices
636 may be given.  These restrict the purging to just those entries and their
637 descendents.  The default is to purge the entire database.
638 .P
639 .ce 1
640 --ooOOoo--
641 .PP
642 .B quit
643 .PP
644 The quit command is used to exit from tdl when it is used in interactive mode. 
645 The quit command is not available in the command line mode, where it would not 
646 make sense. 
647 .P
648 The quit command DOES NOT write any pending updates to the database before 
649 exiting. Compare the 
650 .B exit 
651 command, which does write all updates made during the current tdl run.
652 .P
653 The main use for the quit command would be to avoid damaging the database if a serious error had been made. 
654 .P
655 .ce 1
656 --ooOOoo--
657 .PP
658 .B tdl remove
659 .I index_to_remove ...
660 .br
661 .B tdl delete
662 .I index_to_remove ...
663 .PP
664 Completely remove one or more entries from the database.  The indices are the
665 same format as those shown in the output of the
666 .B done
667 command.
668 .PP
669 If the string "..." is appended to an index, it means that entry and all its
670 descendents.  This provides a quick way to remove a whole sub-tree of tasks.
671 .P
672 .ce 1
673 --ooOOoo--
674 .PP
675 .B tdl report
676 .I start_time
677 .I [end_time]
678 .PP
679 The
680 .B report
681 command produces a report (in bulleted list format) of tasks completed in a
682 certain time period.  This is useful if (for example) you have to write a
683 weekly summary of the work you've done.
684 .PP
685 The default for the end of the time period is the current time, if the
686 .B end_time
687 argument is not present.  The start of the period to report on must always be
688 specified.  The format for the time arguments is described in the
689 .B "DATE SPECIFICATION"
690 section later.
691 Examples :
692 .PP
693 tdl report 1w
694 .PP
695 will list all tasks completed in the previous week, whereas
696 .PP
697 tdl report 2w 1w
698 .PP
699 will list all tasks completed between 2 and 1 weeks ago.
700 .PP
701 Where a child entry has been completed in the reporting period, but its parent
702 has not been completed, the parent text in the report will be surrounded by
703 '[[' and ']]'.  To give one example, this will happen if the parent has other
704 child entries that haven't been completed yet.
705 .P
706 .ce 1
707 --ooOOoo--
708 .PP
709 .B revert
710 .PP
711 The revert command discards any changes made in the session and reloads the 
712 in-memory database from disc. If you have used the 
713 .B save 
714 command in the session, the database will revert to its state at the most 
715 recent save. Otherwise it will revert to its state when tdl was initially run.
716 .P
717 The revert command does not take any arguments. 
718 .P
719 .ce 1
720 --ooOOoo--
721 .PP
722 .B save
723 .PP
724 The 
725 .B save
726 command can be used to write the current in-memory database out to the disc 
727 database file. The behaviour is currently equivalent to the command exit 
728 followed by re-running tdl from the shell.
729
730 This command is useful if you tend to do long interactive tdl sessions. 
731 It guards against the risks of
732 .P
733 1. accidentally typing quit when you meant exit
734 .br
735 2. machine crashes
736 .br
737 3. running tdl in another window and seeing a stale copy of the database file. 
738 .P
739 The save command does not take any arguments.
740 .P
741 .ce 1
742 --ooOOoo--
743 .PP
744 .B tdl undo
745 .I index_of_entry_to_undo ...
746 .PP
747 This command cancels the effect of the
748 .B done
749 command for one or more entries, e.g. after they have been mistakenly marked as
750 done.
751 .PP
752 If the string "..." is appended to an index, it means that entry and all its
753 descendents.  This provides a quick way to re-open a whole sub-tree of tasks.
754 .P
755 .ce 1
756 --ooOOoo--
757 .PP
758 .B tdl usage
759 .PP
760 Same as
761 .B tdl help
762 (q.v.)
763 .P
764 .ce 1
765 --ooOOoo--
766 .PP
767 .B tdl version
768 .PP
769 Show the version number of the software.
770 .P
771 .ce 1
772 --ooOOoo--
773 .PP
774 .B tdl which
775 .PP
776 Show the filename of the database that tdl accesses in the current context.
777 .P
778 .ce 1
779 --ooOOoo--
780 .PP
781 .B widen
782 .I n_level
783 .PP
784 The optional n_levels parameter tells tdl how many levels to widen the view. 
785 If the parameter is not specified, it defaults to 1. If you try to widen more 
786 levels than the depth of the current sub-tree root node, the widening will be 
787 silently limited to its depth.
788 .P
789 This command is only available when tdl is being run interactively, i.e. when 
790 you have a tdl prompt. It is not available directly from the shell 
791 (where it wouldn't make much sense). 
792
793 .SH Completion facilities
794 .PP
795
796 When tdl has been compiled to use the readline library, the interactive mode 
797 supports a number of completion functions, activated with the <tab> key.
798 .P
799 In particular, the following are supported:
800
801 .B Command completion. 
802 If <tab> is pressed when the command line is empty, a list of possible commands 
803 will be shown. If <tab> is pressed when a partial command has been typed, the 
804 command will be completed immediately if possible, otherwise a list of commands 
805 matching the already-typed prefix will be shown.
806 .P
807 .B Help completion. 
808 If help or usage is already in the buffer, a list of commands will be shown 
809 (as above). The <tab> completion works in the same way to complete the name of 
810 the command you want a help summary for.
811 .P
812 .B Priority completion. 
813 If list or priority is at the start of the input buffer and the current word 
814 starts with a letter, tdl will try to complete the name of a priority level if 
815 <tab> is pressed.
816 .P
817 .B Open task completion. 
818 If done is at the start of the input buffer, hitting <tab> will show a list of 
819 task indices that are still open. If part of an index has already been typed, 
820 the open task indices for which the typed characters are a prefix will be shown.
821 .P
822 .B Postpone completion. 
823 If postpone is at the start of the input buffer, hitting <tab> will show a list 
824 of tasks that may be postponed. Tasks marked done are excluded. If open is at 
825 the start of the input buffer, hitting <tab> will show a list of tasks that may 
826 be opened.
827 .P
828 .B Parameter hints. 
829 If some other command is at the start of the input buffer and <tab> is pressed, 
830 tdl will show a one-line summary of that command's parameters. 
831
832 .SH DATE SPECIFICATIONS
833 .PP
834 The commands
835 .BR add ,
836 .BR done ,
837 .BR purge ,
838 .BR report ,
839 take arguments defining dates (with add and done it is optional).  Dates may be
840 specified in several formats, shown by the following examples:
841 .PP
842 .TS
843 tab(&);
844 l l.
845 \-1h & exactly 1 hour ago
846 \-2d & exactly 2 days ago
847 +1w & exactly 1 week in the future
848 +1m & exactly 1 month (30 days) in the future
849 +2y & exactly 2 years in the future
850 \-1d\-0815 & 08:15am yesterday
851 +1d\-08 & 8am tomorrow
852 +1w\-08 & 8am on the same day as today next week
853 +6h\-08 & 8am on the day containing the time 6 hours ahead of now
854 \.\-08 & 8am today
855 \.\-20 & 8pm today
856 20011020 & absolute : 12 noon on 20th October 2001
857 011020 & absolute : 12 noon on 20th October 2001 (current century)
858 1020 & absolute : 12 noon on 20th October 2001 (current century and year)
859 20 & absolute : 12 noon on 20th October 2001 (current century, year and month)
860 20011020\-081500 & absolute : 08:15am on 20th October 2001
861 20011020\-0815 & absolute : 08:15am on 20th October 2001 (seconds=0)
862 20011020\-08 & absolute : 08:00am on 20th October 2001 (minutes=seconds=0)
863 011020\-08 & absolute : 08:00am on 20th October 2001 (minutes=seconds=0, current century)
864 etc & (see below)
865 \-sun & 12 noon on the previous Sunday
866 +sat & 12 noon on the following Saturday
867 +sat\-08 & 8am on the following Saturday
868 \-tue\-0815 & 08:15am on the previous Tuesday
869 etc & (see below)
870 .TE
871 .PP
872 In the 'all-numeric' format, the rule is that dates can have fields omitted
873 from the start (assumed to be the current value), and times can have fields
874 omitted from the end (assumed to be zero, except if the hours figure is missing
875 it is assumed to be 12, since most work is done in the day.)
876 .PP
877 In the 'weekday and time' format, the time rule is the same: missing minutes
878 and seconds are taken as zero and missing hours as 12.  If the weekday is the
879 same as today, the offset is always 7 days in the required direction.  If the
880 weekday is not the same as today, the offset will always be less than 7 days in
881 the required direction.
882 .PP
883 In the 'relative' format, when a time is included as well, the procedure is as
884 follows.  First the time is determined which is the given number of hours, days
885 etc away from the current time.  Then the specified time on that day is used.
886 The main use for this is to specify times like '8am yesterday'.  Obviously some
887 of the more uses of this mode are rather far-fetched.
888 .PP
889 For the weekday and relative formats, the sign is actually optional.  The
890 default sign (implying past (-) or future (+)) will then be assumed depending on
891 the command as shown below:
892
893 .PP
894 .TS
895 tab(&);
896 l l l.
897 Command & Default & Reason
898 _
899 add & + & Add entries with deferred start times
900 done & - & Entries have been completed at some time in the past
901 report & - & Reporting on earlier completed tasks not future ones
902 purge & - & Tasks won't be completed in the future, so no need to purge future ones
903 .TE
904
905 .SH HOMEPAGE
906 .PP
907 The homepage for
908 .B tdl
909 on the internet is http://www.rc0.org.uk/tdl/
910 .SH AUTHOR
911 .PP
912 The author is Richard P. Curnow <rc@rc0.org.uk>.
913 .SH ACKNOWLEDGEMENTS
914 .PP
915 I got the idea from a program called devtodo.  I liked what that program did
916 and the command line approach to using it, but I ran into lots of compilation
917 problems with it on older C++ installations.  The path of least resistance
918 turned out to be to hack up a C program to do a similar job.
919
920 .SH ENVIRONMENT
921 .TP
922 TDL_DATABASE
923 If this variable is set, it defines the name of the file to use for holding the
924 database of tasks.  If the variable is not set, the search approach described
925 in the FILES section is used.
926 .TP
927 TDL_LIST_MONOCHROME
928 If this variable is set, the output from the
929 .B list
930 command is produced in monochrome instead of colour (the default).
931 .SH FILES
932 .TP
933  ./.tdldb, ../.tdldb, ../../.tdldb, ...
934 If the TDL_DATABASE environment variable is not present, the file .tdldb in the
935 current directory is used, if that is present.  If not, the same file in the
936 parent directory is used, and so on, until the root directory of the filesystem
937 is reached.  If the database is still not found, a new one will be created in
938 the current directory (except for options that don't modify the database, such
939 as list, help and version.)
940 .PP
941 If you want to have a .tdldb file in 
942 .I every
943 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
944 .IP
945 TDL_DATABASE=./.tdldb
946 .br
947 export TDL_DATABASE
948 .PP
949 and in a C-like shell (csh, tcsh etc) you'd write
950 .IP
951 setenv TDL_DATABASE ./.tdldb
952 .PP
953 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:
954 .IP
955 cd project1
956 .br
957 ln \-s ../project2/.tdldb .
958
959 .SH BUGS
960 Please report them to the author.
961
962 .SH SEE ALSO
963 The full documentation for tdl is maintained as a Texinfo manual. If the info and tdl
964 programs are properly installed at your site, the command
965 .IP
966 info tdl
967 .PP
968 should give you access to the complete manual.
969
This page took 0.111502 seconds and 4 git commands to generate.