From de8e065eec377899993aba03b0b030aa4c69ec46 Mon Sep 17 00:00:00 2001 From: Matthias Beyer Date: Sun, 16 Dec 2018 08:59:00 -0700 Subject: [PATCH] doc: Rewrite docs for todo module parts Signed-off-by: Matthias Beyer --- doc/src/04020-module-todo.md | 7 +-- doc/src/05100-lib-todo.md | 85 ++++++++++++++++++++++++++++++++++-- 2 files changed, 83 insertions(+), 9 deletions(-) diff --git a/doc/src/04020-module-todo.md b/doc/src/04020-module-todo.md index 3849b242..48903c91 100644 --- a/doc/src/04020-module-todo.md +++ b/doc/src/04020-module-todo.md @@ -1,9 +1,4 @@ ## Todo {#sec:modules:todo} -The Todo module implements `taskwarrior` functionality by integrating -taskwarrior itself into imag. - -Each taskwarrior task s referenced from imag and represented as imag entry, thus -making it linkable by other imag entries. - +The "todo" module implements a task manager. diff --git a/doc/src/05100-lib-todo.md b/doc/src/05100-lib-todo.md index 1109ee8d..50eedb41 100644 --- a/doc/src/05100-lib-todo.md +++ b/doc/src/05100-lib-todo.md @@ -1,8 +1,87 @@ ## libimagtodo -The library for the todo module. +The library for the todo module which provides functionality to +implement/implements a todomanager in imag. -Whether this wraps `taskwarrior` or implements a todo tracking mechanism in imag -itself is to be defined. Probably the latter. +### 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 = "" +hidden = "" +due = "" +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/", creating a +`StoreId` from a UUID is trivial. +