imag/doc/src/05100-lib-todo.md

## libimagtodo

The library for the todo module which provides functionality to
implement/implements a todomanager in imag.

### Implementation details

One todo entry is stored as one imag entry. The ID of the imag entry is generated by
appending a unique ID (UUID) to "todo/".

The unique ID identifies the todo entry.

#### Stored data

A todo entry stores the following information:

* The (UU)ID of the todo entry
* A status of the todo entry. Valid values are: "deleted", "done", "pending"
* A "scheduled" date/datetime, can also yield an iterator
* An optional "hidden" value, which specifies a date in the future where this
  todo entry should show up. Relative (eg. "-5days"), 
  to the "scheduled" date/datetime
* An optional "due" date/datetime, relative to the "scheduled" time
* A list of dependencies of the entry
* A "importance"-level, config file defined (strings in an array, index used for
  ranking them)
* User defined value (a map of key-value string pairs)

The description of the todo entry is stored as plain text.

#### Data not stored

Some data is explicitely _not_ stored by the library because there are other
libraries fullfilling that purpose. These are:

* Tags, which can be done with libimagentrytag
* Category, which can be done with libimagentrycategory
* Project belonging, which can be done with libimagentrylink (by linking to a
  project file - note that "project" is a domain not yet implemented by imag)
* Annotations, which can be stored with libimagentryannotation

#### Header format

The header partial for libimagtodo is as follows:

```
[todo]
uuid = "string"
status = "string"
scheduled = "<kairos time spec>"
hidden = "<kairos time func (optional)>"
due = "<kairos time func (optional)>"
depends = [ "list of uuids" ]
importance = "string"
uda = {}
```

#### Functionality

The provided functionality of this library includes, but is not limited to:

* Creating new todo entries in the store
* Deleting todo entries from the store
* get/retrieving todo entries from the store
* Turning an entry into a todo entry
* Getting todo details from an entry
  * scheduled, due, waiting date/datetime
  * priority
  * UUID
  * status
  * An iterator over all dependend todo entries (as `StoreIdIterator`)
* Calculating a "urgency" of a todo entry from a formula weighted by configurable factors


#### Dependencies between tasks

Dependencies between todo entries are created by putting the UUID of a dependent todo entry into
the `todo.depends` header.
This way, a unidirectional link is created. A link (as in `libimagentrylink`) is
_also_ created, but this can be turned off explicitely.

As `libimagentrylink` links are bidirectional, they do not suffice for todo
entry dependency creation.

As todo entries are stored with the Store IDs "todo/<uuid>", creating a
`StoreId` from a UUID is trivial.