This repository has been archived by the owner on Apr 30, 2024. It is now read-only.
-
Notifications
You must be signed in to change notification settings - Fork 0
/
Copy pathtodo.1
191 lines (191 loc) · 5.87 KB
/
todo.1
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
.\" Copyright (c) 2020 Alexander Möller <[email protected]>
.\"
.\" Permission to use, copy, modify, and distribute this software for any
.\" purpose with or without fee is hereby granted, provided that the above
.\" copyright notice and this permission notice appear in all copies.
.\"
.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
.\"
.Dd $Mdocdate: February 19 2024 $
.Dt TODO 1
.Os
.Sh NAME
.Nm todo
.Nd simple todo list manager
.Sh SYNOPSIS
.Nm
.Op Fl b
.Op Fl q
.Op Fl d Ar file
.Op Fl r Ar file
.Op Fl t Ar file
.Op Fl p Ar priority
.Op command
.Sh DESCRIPTION
.Nm
is a simple todo list manager utilising only basic POSIX shell tools such as
.Xr awk 1 ,
.Xr ed 1
and
.Xr grep 1 .
.Pp
The options are as follows:
.Bl -tag -width Ds
.It Fl b
Batch mode. Mark all tasks as done that match the keyword.
.It Fl q
Quiet mode. Perform the action, but don't display anything on standard output.
Applies to append, create, done, priority, report.
.It Fl p Ar priority
Specify the priority for a newly created entry. Otherwise A will be used.
.It Fl d Ar file
Path to the done.txt file.
.It Fl r Ar file
Path to the report.txt file.
.It Fl t Ar file
Path to the todo.txt file.
.El
.Pp
The following commands are available:
.Bl -tag -width Ds
.It Cm append Ar tasknumber Ar addition
Append an addition to the specified task.
.It Cm create Ar text
Add a new task.
.It Cm done Ar tasknumber No / Ar keyword
Mark the task specified by its tasknumber as done.
When used with -b then all tasks are marked as completed that match the following keyword.
.It Cm edit
Edit todo.txt in $EDITOR.
.It Cm finished
Open done.txt in $PAGER.
.It Cm lc
Show the list of existing contexts including the amount of associated tasks.
.It Cm ld Ar keyword
Show the list of existing entries sorted by due date. The corresponding syntax is due:%Y-%m-%d according to
.Xr strftime 3 .
This can be matched with a keyword.
.It Cm lp
Show the list of existing projects including the amount of associated tasks.
.It Cm ls Ar keyword
Show the list of existing entries. A keyword can be provided to only list matching entries.
Note that the matching is case insensitive.
.It Cm priority Ar tasknumber Ar priority
Change the priority of the specified task.
.It Cm report
Generate a report.
.It Cm today Ar keyword
Show the list of tasks due today as well as those past their due date. If provided, match this with a keyword.
.El
.Sh NOTES
Most of the commands only depend on the first letter. So instead of using
.Bd -literal -offset indent
$ todo create example task
.Ed
.Pp
it is also possible to use
.Bd -literal -offset indent
$ todo c example task
.Ed
.Pp
The only exceptions to this are lc, ld, lp and ls.
.El
.Sh ALLOWED CHARACTERS
The body of tasks can include almost all UTF-8 symbols, including /[]{}.
Characters that might be used but are not supported are \\().
.Pp
Contexts and projects are restricted to alphanumerical characters, underscore and hyphen: [:alnum:]_-].
.Sh ENVIRONMENT VARIABLES
.Bl -tag -width 20n -compact
.It Pa EDITOR
Editor to use for the edit command. Defaults to
.Xr vi 1 .
.It Pa PAGER
Pager to use for the finished command. Defaults to
.Xr less 1 .
.It Pa TODODIR
Directory
.Nm
uses. Defaults to $HOME/.todo/.
.Pp
.It Pa TODO_COLOUR_A
Colour for priority A. Defaults to \\033[31m (red).
.It Pa TODO_COLOUR_B
Colour for priority B. Defaults to \\033[33m (yellow).
.It Pa TODO_COLOUR_C
Colour for priority C. Defaults to \\033[32m (green).
.It Pa TODO_COLOUR_D
Colour for priority D. Defaults to \\033[1;34m (light blue).
.El
.Sh COLOURS
The output of all commands except for done and report is coloured based on priorities. See above for the priorities A-D. All others (E-Z) default to white. Changing this should be very straightforward.
.Sh FILES
.Bl -tag -width 20n -compact
.It Pa $TODODIR/done.txt
File listing finished tasks.
.It Pa $TODODIR/report.txt
File containing the generated reports.
.It Pa $TODODIR/todo.txt
File listing active tasks.
.El
.Sh EXAMPLES
Change the priority of task 1 to B:
.Bd -literal -offset indent
$ todo priority B 1
.Ed
.Pp
Create task "example task" with priority C, but don't display it to standard output:
.Bd -literal -offset indent
$ todo -p C -q create example task
.Ed
.Pp
Get an overview of the tasks due in the first days of August 2021:
.Bd -literal -offset indent
$ todo ld due:2021-08-0
.Ed
.Pp
Mark every task related to taxes as done:
.Bd -literal -offset indent
$ todo -b d taxes
.Ed
.Pp
Check files in a non-standard location:
.Bd -literal -offset indent
$ TODODIR=/path/to/other/directory todo today
.Pp
$ todo -t /some/todo.txt -d /some/other/done.txt -r /another/report.txt ld
.Ed
.Pp
These options are especially useful when put into an
.Xr alias 1 .
.Sh HISTORY
.Nm
is a rewrite from scratch of most features of the popular todo.txt-cli utility. The intention was to provide a simpler version that is only dependent on standard POSIX features but can still be used as a drop-in replacement.
.Pp
The syntax of todo.txt, specifically the + identifier for projects conflicts with regular expressions in
.Xr awk 1 .
Therefore an alternative _ identifier was used by default from version 0.7 to 0.8.3p1.
Since then the relevant
.Xr awk 1
command used in
.Nm
is identifier agnostic and the switch back was made, returning
.Nm
to be a drop-in replacement fully supporting the original syntax of todo.txt.
.Ed
.Sh SEE ALSO
.Xr awk 1 ,
.Xr ed 1 ,
.Xr grep 1 ,
.Xr less 1 ,
.Xr strftime 3
.Sh AUTHOR
.Nm
was written by
.An Alexander Möller Aq Mt [email protected] .