]>
Commit | Line | Data |
---|---|---|
7024e37b JW |
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 |