Content-Type: text/x-zim-wiki
Wiki-Format: zim 0.26
Creation-Date: Unknown
Modification-Date: Di, 07 Apr 2009 22:59:28 +0200

====== TODO List ======

The TODO list plugin adds a dialog that shows a summary of open TODO items in this notebook. It works like a search for the "TODO" and "FIXME" tags, but instead of the normal search results, it shows a more customized list. Alternatively, instead of using the "TODO" tag you can regard any [[checkboxes|checkbox]] as an TODO item.

The idea is that instead of using one page as a dedicated TODO list, you can use multiple pages to keep notes on various ongoing projects. Each of these pages can contain one or more TODO items and the dialog shows the overview of the whole notebook. 

Another use case is when you write something like a paper or an article in zim you just put TODO items in the middle of the page where content is missing. Now the dialog shows a summary of all places in your text that need attention. A third example is the usage of calendar pages to keep the minutes of a project meeting. Now you can use the TODO tag or an open checkbox to flag any personal action items.

===== Syntax =====
You can put TODO items in your pages like this:

	TODO: fix item 1

	FIXME: update this information

or like this:	

	* fix item 1 - TODO

or like this:	

	TODO:
	* fix item 1
	* fix item 2
	* fix item 3

Each line describes one TODO item, sub tasks are not supported. The tag needs to be in all caps in order to be found. For a single item the tag should be at the begin of the line, but the tag is allowed anywhere in the line for list items (i.e. when the line starts with a bullet). To define multiple items at once the tag should be on the first line of the paragraph without any other text on the same line.

Using [[checkboxes]] this might look like:

	TODO:
	[ ] fix item 1
	[*] fix item 2
	[ ] fix item 3

When you want all checkbox items in your notebook to show up without the need to use a "TODO" tag for each list you can enable the **include all open checkboxes **option in the TODOList dialog.

===== Priorities =====
To set a priority for items you add one or more exclamation marks:

	TODO: important item !
	TODO: very important item !!

The number of exclamation marks is the priority given for each item in the list.	

===== Due date =====
You can also add a due date for TODO items. The following formats are supported: 
'''
• dd/mm/yy 
• dd/mm 
• dd.mm.yyyy 
• dd.mm.
• yyyy-mm-dd
• yyyy_mm_dd
• yyyy mm dd (with a space as delimiter)
• yyyy:mm:dd
'''

You can use also the short forms like yy-m-d or d/m.
To distinguish the due date from other dates you may use prefix and postfix identificators. 
The default settings are ''['' as the prefix and '']'' as the postfix. See the Configuration paragraph below for more details.
'''
'''

This date is matched anywhere in the description. For example each of the following sets a high priority item for 24th of December (2009):

	TODO: buy christmas presents [24/12] !!
	TODO: don't forget christmas [  24.12.  ] presents !!
	TODO: [24/12] buy christmas presents !!
	[ ] buy christmas presents [24/12] !!

	TODO:
	!! Buy christmas presents before [24/12]
	!! [2009-12-24] yep, christmas is coming. Buy presents.

	* Buy christmas presents - TODO [24/12] !!

===== Checking items =====
To mark items as done you can either remove them, use strike-trough formatting or put the tag "DONE" on the same line. For example:

	TODO:
	* item 1
	* item 2 - DONE: trivial update
	* item 3

Will only show "item 1" and "item 3" in the TODO list.

Of course when using [[checkboxes]] any item that is checked will be considered DONE. So in this list only item 1 will show up in the TODO list:

	TODO:
	[ ] item 1
	[*] item 2
	[x] item 3

===== Configuration =====
By default the TODOList plugin looks for the tags "TODO" and "FIXME". If you want to disable these (e.g. to only use checkboxes) or want to use different tags you can change them in the [[config|config file]]. The section for this plugin has an option "tags" which takes a comma seperated list of tags to look for.

* tags			default: 	TODO, FIXME

To control the due date match you can use the following options:

* due_date_prefix 	default: 	''[''
-> Used to match the due date. This string must be found before a date. Space between this string and the date is also allowed. Can be set to empty string which means that no prefix is necessary.

* due_date_postfix	default: 	'']''
-> Used to match the due date. This string must be found after a date. Space between the date and this string is also allowed. Can be set to empty string which means that no postfix is necessary.
