Autocommit of file /home/julien/.dotfiles/vim/.vim/bundle/vimtodo/doc/todo.txt change...
[dotfiles/vim.git] / .vim / bundle / vimtodo / doc / todo.txt
1 *todo.txt*  Vim todo list plugin
2
3 Vim todo list plugin                                            *vimtodo*
4
5 Plugin for managing hierarchical to do lists in vim.
6
7 ==============================================================================
8 ABOUT                                                   *vimtodo-about*
9
10 Vimtodo originally started out as a set of syntax highlights for the todo.txt
11 (http://www.todotxt.com/) format in vim with a few added extras such as
12 subtasks. However, it quickly grew into a fully fledged task management
13 system, taking several ideas from Emacs' org-mode (http://www.orgmode.org/).
14
15 ==============================================================================
16 INSTALLATION                                            *vimtodo-installation*
17
18 Untar the archive to ~/.vim. If you wish, untar to a temporary directory, and
19 copy the contents of the autoload/, doc/, ftplugin/ and syntax/ directories to
20 the respective directories in your ~/.vim directory.
21
22 Alternatively, if you have pathogen installed, untar the entire archive to
23 ~/.vim/bundle/vimtodo/.
24
25 ==============================================================================
26 BASIC TODO ENTRIES                                      *vimtodo-basics*
27
28 To start with, open up a new file, and add the following line to the
29 beginning: >
30     # vim:ft=todo
31
32 This line tells vim that the file is a vimtodo file. See |modeline| for more
33 information. Now write the file, quit and reopen it. Alternatively, you can
34 just type the following to set the filetype without reopening the file: >
35     :set ft=todo
36
37 To do entries are simply lines in the file that follow a specific format. Add
38 the following line into the file: >
39     TODO 2009-09-01 @computer +learnvim Read vim tutorial
40
41 This is a todo entry. You can also add a new entry, with the 'cn' alias. In
42 insert mode, type 'cn' and a new todo entry along with the current date will
43 be added. You can also use <LocalLeader>cn in normal mode to add a new entry.
44
45 The todo entry is made up of several parts:
46
47     TODO - the task status, this is something like TODO, DONE, WAITING
48     2009-09-01 - the task creation date
49     @computer - the context of the task, in this case, something to do at the
50                 computer
51     +learnvim - the project the task is associated with
52
53 Giving multiple tasks a context or project tag allows you to filter out just
54 the tasks you are interested in using the filter function (described later).
55
56 For now, press escape to go back to normal mode, make sure the cursor is on
57 the same line at the todo entry you just added, and press <LocalLeader>cs (\cs
58 by default). The task status will change to 'DONE' and the line will be greyed
59 out. Here, several things have happened:
60
61     - The task status changed from TODO to DONE
62     - The entire task changes color to show that the task is complete
63     - A CLOSED: line has been added underneath showing the date and time that
64       the task was closed.
65     - A logbook entry has been added (but is currently hidden), logging the
66       time and date of the task state change.
67
68 A CLOSED: entry is added whenever a task is closed, and will be removed
69 if a task is re-opened.
70
71 Logbook entries however, log the date and time every time you change the state
72 of a task, and look like this: >
73
74     :LOGBOOK:
75         TODO: 2009-09-30 18:19:51
76         CANCELLED: 2009-09-30 18:19:50
77         DONE: 2009-09-30 18:12:58
78
79 Currently the todo entry is folded, so move the cursor to the fold line (just
80 below the todo entry) and press zO to open all the folds. Then move the cursor
81 back to the todo line and press <LocalLeader>cs to change the task status a
82 few times to see the behavior of the closed/logbook lines.
83
84 If desired, the display of closed/logbook lines can be turned off in your
85 .vimrc. See the configuration section for more details.
86
87 You can add more information to a task using normal text editing commands.
88 Anything that is indented is considered to be information that is part of a
89 todo entry. For example, the closed and logbook lines are indented and
90 considered part of the todo entry.
91
92 A due date for a task can be added. Add the following to the end of the
93 original todo entry you added earlier: {2009-09-30}. This will be highlighted
94 just like the task date. If you wish to add the current date, type in ds. For
95 example {ds} will set a deadline of today.
96
97 If you have tasks with due dates, you can use several commands to view tasks
98 that are due soon:
99
100     <LocalLeader>cd - Show tasks due today
101     <LocalLeader>cf - Show tasks due tomorrow
102     <LocalLeader>cw - Show tasks due within 7 days
103     <LocalLeader>cx - Show overdue tasks (tasks that were due sometime in the past
104                  year)
105
106 Each of these opens up another buffer listing the matching entries. Pressing
107 enter on one of the items in the list will take you to the corresponding
108 entry. Try this - change the deadline for your task to today, and type
109 <LocalLeader>cd.
110
111 You can filter on other criteria too, such as context or project using the
112 :Filter ex command. It takes a regular expression and will show matching
113 tasks. For example: >
114
115     :Filter @home
116
117 which would bring up all tasks with a context of @home.
118
119 ==============================================================================
120 TASK STATES         *vimtodo-state* *vimtodo-taskstate* *vimtodo-taskstates*
121
122 The first word of a task in all caps shows the tasks state. Normally it is is
123 something like TODO or DONE, but the available states can be configured as
124 needed.
125
126 Task states can be changed in one of two ways: The <LocalLeader>cs normal mode
127 command, and the <LocalLeader>cv normal mode command.
128
129 <LocalLeader>cs will cycle through the task states (by default, TODO, DONE,
130 CANCELLED) See |vimtodo-stateprogression| for more information on this.
131
132 <LocalLeader>cv will bring up a prompt asking you to pick which state you want to
133 switch to. Press the letter associated with the state to immediately change
134 the task to that state.
135
136 Some task states are considered "done" states. In these states, the entire
137 task is highlighted in the same color (as if it was a comment) and a CLOSED
138 tag is added to the task to show the date and time the task was closed.
139
140 In addition to the closed task, whenever a tasks state is changed, the state
141 change is appended to the task in a LOGBOOK section (or "drawer"). This is an
142 indented part of the task with one line for each state change.
143
144 The closed/logbook behavior can be configured in your .vimrc using the
145 'g:todo_log_done' and 'g:todo_log_drawer' settings. Alternatively, you can set
146 this behavior on a per file basis using the LOGDONE and LOGDRAWER properties.
147 See |vimtodo-config| for more information on these settings.
148
149 STATE PROGRESSION                                   *vimtodo-stateprogression*
150
151 When using <LocalLeader>cs to change between task states, the state will cycle
152 between succesive states in the progression, and back to the beginning if the
153 final state is reached. The progression can be configured, but the default
154 states are:
155
156 TODO -> DONE -> CANCELLED
157 WAITING -> CLOSED
158
159 If you wish to change to a state that is on a different progression (e.g. from
160 TODO to WAITING), then you can use the <LocalLeader>cv command to jump direct
161 to that state.
162
163 ==============================================================================
164 ARCHIVING                               *vimtodo-archive* *vimtodo-archiving*
165
166 VimTODO can move all completed tasks to another file to reduce clutter. The
167 <LocalLeader>ca command is used for this. Any task that has been closed will
168 be moved to the done file, which by default is 'done.txt' in the same
169 directory as the todo file.
170
171 The name of the done file can be changed using the g:todo_done_file .vimrc
172 setting or on a per-file basis using the DONEFILE property.
173
174 ==============================================================================
175 CHECKBOXES                                              *vimtodo-checkboxes*
176
177 In addition to tasks with a given state, Vimtodo can manage checkboxes. Any
178 line in a file can contain a checkbox. It doesn't have to be a task heading,
179 and in fact it probably isn't a good idea to mix task entries (with a state)
180 and checkboxes.
181
182 To create a checkbox, simply type [ ] in insert mode. Alternatively, you can
183 use <LocalLeader>cb in normal mode to add a checkbox to the beginning of a
184 line.  Note that if you do this on the header line for a task, it will be
185 inserted before the task state (e.g. TODO) and the task will lose any special
186 meaning.
187
188 To toggle a checkbox, use the <LocalLeader>cc command. By default, a checkbox
189 will be checked with an X, and another use of <LocalLeader>cc will uncheck the
190 box.  However, like task states, there are a number of states a checkbox can
191 cycle through: >
192
193     [ ] -> [X]
194     [+] -> [-] -> [.]
195     [Y] -> [N] -> [?]
196
197 To use one of these other progressions, simply start with the relevant state
198 when creating your checkbox. For example, type [Y] in insert mode to create a
199 Y/N/? check box.
200
201 Again, like task states, checkbox state progression can be configured. The
202 g:todo_checkbox_states variable and the CHECKBOXSTATES property controls this
203 behavior.
204
205 ==============================================================================
206 TASK LINKS                              *vimtodo-tasklinks* *vimtodo-links*
207
208 Vimtodo can be configured to reference an external task management system. By
209 adding tidXXXX to your task, you can use <LocalLeader>ct to open up a web page
210 showing the external task.
211
212 For example:
213
214 You have an external task management system where all tickets are available on
215 the web at the following URL: http://tasks.example.com/tickets/tid=12345 (for
216 ticket #12345)
217
218 Set up the g:todo_taskurl variable in your .vimrc to be the same as the above
219 url, substituting '%s' for the ticket number. In addition, you need to set the
220 g:todo_browser variable to be a command to load a web page in your browser. In
221 the example below, gnome-open is used to open the default browser (If you are
222 using Linux/Gnome): >
223
224       let g:todo_taskurl="http://tasks.example.com/tickets/tid=%s"
225       let g:todo_browser="gnome-open"
226
227 You wish to reference this ticket in a TODO entry, so you add tid12345
228 to the ticket. At this point, <LocalLeader>ct will open up your web browser
229 and take you to the referenced ticket.
230
231 Vimtodo can also open any URL in a web browser if the g:todo_browser variable
232 is configured. To do this, use <LocalLeader>cl and any http/https link on the
233 current line will be opened in the web browser.
234
235 ==============================================================================
236 FOLDING                                                     *vimtodo-folding*
237
238 Any extra data added to an entry (be it the logbook/closed tags, or notes on a
239 task) is indented from the first line, and is folded away when the file is
240 first opened using vim's folding features. Folding is based on the indentation
241 of the text.
242
243 All of vim's normal folding commands can be used to manipulate what is
244 hidden/shown. For a good overview on this, see |fold-commands|. However, the
245 basic commands used to open/close folds are |zo| and |zc| (both normal mode
246 commands).
247
248 ==============================================================================
249 TIME SPENT ON TASKS                                     *vimtodo-timespent*
250
251 Vimtodo has limited support for logging the time spent on tasks. For each
252 subtask in a todo entry, you can add the time spent tag that looks something
253 like: [1.5h] (for 1.5 hours spent on the task).
254
255 Vimtodo can then total up the time spent on each subtask and display the total
256 in the top level task. The command to update the totals is <LocalLeader>ce,
257 which will create or update a TIMETOTAL property inside the INFO drawer on the
258 top level task.
259
260 In addition to the normal mode command, the ex command :UpdateTimeTotal is
261 provided, which will allow you to automate the updating as desired. One option
262 is to update the totals just before saving the file with an autocommand. The
263 following example is something you could add in ~/.vim/after/ftplugin/todo.vim
264 which would automatically update the times whenever a todo file is written: >
265
266     au BufWrite <buffer> :UpdateTimeTotal
267
268 ==============================================================================
269 CONFIGURATION                       *vimtodo-config* *vimtodo-configuration*
270
271 Much of vimtodo's behavior can be changed if desired. There are two options
272 for configuration: variables in .vimrc and properties.
273
274 PROPERTIES                                              *vimtodo-properties*
275
276 Properties are simply per-file configuration options that you add to the
277 beginning of a todo file. They are all contained in a :SETTINGS: drawer,
278 usually near the top of the file, and each setting begins with a + sign:
279 For example: >
280
281     :SETTINGS:
282         +DONEFILE: custom_done_file.txt
283         +LOGDONE: 0
284
285 CONFIGURATION OPTIONS                                   *vimtodo-configoptions*
286
287 g:todo_checkbox_states              (property: +CHECKBOXSTATES)
288
289     Sets the list of checkbox state progressions.
290
291     If set in the vimrc file, this is a list of valid checkbox progressions,
292     each progression of which is itself a list. To set multiple checkbox
293     progressions using properties, just use multiple +CHECKBOXSTATES lines.
294
295     Examples (vimrc first, then properties example below): >
296
297     let g:todo_checkbox_states = [
298         \["A", "B", "C"],
299         \["1", "2", "3"]]
300
301     :SETTINGS:
302         +CHECKBOXSTATES: A B C
303         +CHECKBOXSTATES: 1 2 3
304
305 g:todo_done_file                    (property: +DONEFILE)
306
307     Set the name of the file to archive done tasks into. (Default: done.txt)
308
309 g:todo_log_done                     (property: +LOGDONE)
310
311     Enable/disable logging of the time a task is done with the CLOSED: tag.
312     Set to 1 to enable logging, 0 to disable.  (Default: 1)
313
314 g:todo_log_into_drawer              (property: +LOGDRAWER)
315
316     Set the name of the drawer to log state changes into. If blank, then don't
317     log state changes into a drawer. (Default: LOGBOOK)
318
319 g:todo_states                       (property: +STATES)
320
321     Set a custom list of valid task states.
322
323     If set in the vimrc file, this is a list of valid state progressions, each
324     progression of which is itself a list. To set multiple state progressions
325     using properties, just use multiple +STATES lines.
326
327     If '|' is included in a given state progression, it separates normal
328     states from "done" states. If '|' is not present, then all states in that
329     progression are normal states. To have a progression made entirely of done
330     states, put '|' as the first entry in the list.
331
332     Each state should be in all caps (e.g. TODO). An optional shortcut key
333     (for use with <LocalLeader>cv) can be added in parentheses after the state
334     (e.g. "TODO(t)").
335
336     To set the colors for each state, see the g:todo_state_colors option.
337
338     Examples (vimrc first, then properties example below): >
339
340     let g:todo_states=[['TODO(t)', '|', 'DONE(d)', 'CANCELLED(c)'],
341         \['WAITING(w)', 'HOLD(h)', 'INPROGRESS(i)', 'SOMEDAY(s)', 'CLOSED(l)']]
342
343     :SETTINGS:
344         +STATES: TODO(t) | DONE(d) CANCELLED(c)
345         +STATES: WAITING(w) HOLD(g) INPROGRESS(i) SOMEDAY(s) CLOSED(l)
346
347 g:todo_state_colors                 (property: +STATECOLORS)
348
349     Set the highlight colors for each state.
350
351     This is a map from state names to colors. Any color name recognized by vim
352     can be used here. Standard colors such as 'Red', 'Blue', 'Green', 'Grey'
353     are all recognized.
354
355     When using the +STATECOLORS property, use a colon to separate the state
356     name from the color, separate each state/color pair with a comma, and use
357     multiple property lines if required.
358
359     Examples (vimrc first, then properties example below): >
360
361     let g:todo_state_colors= {
362         \'DONE': 'Green',
363         \'CLOSED': 'Grey',
364         \'CANCELLED': 'Red',
365         \'TODO': 'Blue',
366         \'WAITING': 'Yellow',
367         \'HOLD': 'Grey',
368         \'INPROGRESS': 'Cyan',
369         \'SOMEDAY': 'Grey'
370         \}
371
372     :SETTINGS:
373         +STATECOLORS: DONE:Green, CLOSED:Grey, CANCELLED:Red, TODO:Blue
374         +STATECOLORS: WAITING:Yellow, HOLD:Grey, INPROGRESS:Cyan
375         +STATECOLORS: SOMEDAY:Grey
376
377 g:todo_taskurl                      (property: +TASKURL)
378
379     Sets the url for referencing external task manager tickets using tidXXXX
380     format in an entry.
381
382     Any occurence of %s in the URL will be replaced with the id of the ticket
383     when <LocalLeader>ct is used.
384
385     Default: blank (<LocalLeader>ct does nothing)
386
387 g:todo_browser                      (property: +BROWSER)
388
389     Sets the command to use when loading a url or external ticket. The command
390     is executed with a single parameter - the URL to load in the browser.
391
392     If you are running GNOME, then 'gnome-open' is a good choice, as it will
393     load your default browser. Likewise, Mac users can use 'open' for this. If
394     you want a specific browser to open, you can specify that instead.
395
396     Default: blank (any commands that require this will have no effect)
397
398 ==============================================================================
399 TROUBLESHOOTING                                     *vimtodo-troubleshooting*
400
401 When I load a todo file (or set ft=todo), the syntax coloring shows up, but
402 none of the commands seem to work.
403
404     Make sure you have filetype plugins enabled in your vim config. This can
405     be done by adding 'filetype plugin on' to your .vimrc file. See
406     |:filetype-plugin-on| for more details.
407
408 ==============================================================================
409 REPORTING BUGS AND FEATURE REQUESTS                             *vimtodo-bugs*
410
411 Vimtodo uses github for bug tracking. Go to
412 http://github.com/mivok/vimtodo/issues to report any issues.
413
414 The latest version of the script is always available on github:
415
416 http://github.com/mivok/vimtodo
417
418 ==============================================================================
419   vim:ft=help:tw=78