diff --git a/README.md b/README.md
index 4408cb7..391f598 100644
--- a/README.md
+++ b/README.md
@@ -6,9 +6,26 @@ _Use [taskwarrior](http://taskwarrior.org) task-management in [vimwiki](https://
[](https://coveralls.io/r/tbabej/taskwiki?branch=master)
[](https://landscape.io/github/tbabej/taskwiki/master)
-This is a vim plugin, which aims to provide integration between vimwiki and taskwarrior. It extends vimwiki by replacing the rudimentary Todo lists, and provides bidirecitonal synchronization between TaskWarrior and Vimwiki files.
+ \*[taskwiki.txt](/doc/taskwiki.txt)\*
+
+ _____ _ __ ___ _ _ ~
+ a |_ _|_ _ ___| | _\ \ / (_) | _(_) a ~
+ command-line | |/ _` / __| |/ /\ \ /\ / /| | |/ / | personal wiki ~
+ todo list | | (_| \__ \ < \ V V / | | <| | for vim ~
+ manager |_|\__,_|___/_|\_\ \_/\_/ |_|_|\_\_| ~
+ ~
+==============================================================================
+QUICK-REFERENCE -- use < leader > + t and one of:
-This allows you to define your tasks in your vimwiki files and still have processing power of TaskWarrior at your disposal. If you use taskwarrior, and you use vimwiki, you want this plugin.
+| a annotate | C calendar | Ga ghistory annual | p projects |
+| bd burndown daily | d done | hm history month | s summary |
+| bw burndown weekly | D delete | ha history annual | S stats |
+| bm burndown monthly | e edit | i (or CR ) info | t tags |
+| cp choose project | g grid | l back-link | + start |
+| cp choose tag | Gm ghistory month | m modify | - stop |
+
+
+
### Requirements
@@ -24,57 +41,86 @@ This allows you to define your tasks in your vimwiki files and still have proces
### Enhancements
* [vim-plugin-AnsiEsc](https://github.com/powerman/vim-plugin-AnsiEsc) for color support
* [tagbar](https://github.com/majutsushi/tagbar) for taskwiki file navigation
+* [vim-taskwarrior](https://github.com/farseer90718/vim-taskwarrior) for grid view
### Install
-Install this plugin like any other; using pathogen or copying the files and folders to your vim directories.
+- plugins the vim way: http://vimdoc.sourceforge.net/htmldoc/usr_05.html#05.4
+- plugins the easy way: https://github.com/tpope/vim-pathogen. Other "vim plugin managers" will probably work, but have not been tested
### Features
-#### ViewPorts
- * Create a heading that contains a taskwarrior filter, that looks like this;
+- ViewPorts: a vimwiki header with a task query (filter) embedded, generate
+a corresponding list of tasks. These tasks can be modified and changes
+will be synced back to task data. A ViewPort heading looks like this:
+
-== Foo task list | project:foo ==
+ == Project Foo Tasks | +PENDING project:foo | +bar pri:H ==
+ title ^^^ filter ^^^ ^^^ user defaults
-and after saving the file, TaskWiki generates a full list of matching tasks.
+title can be any text, and the filter elements are concealed in normal mode.
+
+- Individual Todos: tasks can be used anywhere in a vimwiki, looking like:
-#### Define defaults, by extending that heading like this;
-== Foo task list | project:foo | project:foo +bar ==
+* [ ] Install TaskWiki plugin
-so that any tasks created under this heading will automatically be assigned "project:foo +bar"
-#### Bidirecitonal updates:
- * TW -> Vimwiki (upon file loading)
- * Vimwiki -> TW (upon saving)
+and when adding a new task, any other metadata can be added after "--" like
-#### Updated information
- * Description
- * Task status (completion)
- * Dependency sets (sets subtasks as dependencies of parent tasks)
- * Due dates
- * Priority
+
+* [ ] test taskwiki todos and viewports -- proj:tw.wiki +foo due:tomorrow
+
+
+and the task will be synced with the task data on saving. After syncing,
+all tasks end with a concealed uuid (eg. #541c5b57) don't edit this!
+
+- Task Info: hitting with the cursor over a task shows all task info.
+
+- Reports: burndown, calendar, history, projects, summary, stats and tags
+reports can all be invoked, opening in a split window.
+
+- Grid view: the TaskWikiGrid command will open a new buffer with a grid
+view of task details, of the nearest ViewPort (using vim-taskwarrior)
+
+- Back-links: The command TaskWikiLink will add an annotation to the selected
+task(s) with the ~/path/to/file.wiki
+
+- Tests: TaskWiki is well tested in development to ensure data integrity.
+ **DISCLAIMER** This is free software, it comes with absolutely NO
+ warranty and no promise of fitness for any purpose! (back up your data!)
### Commands
- * TaskWikiBurndown(Daily, Monthly, Weekly)
- * TaskWikiCalendar
- * TaskWikiDelete
- * TaskWikiGhistory(Annual, Monthly)
- * TaskWikiHistory(Annual, Monthly)
- * TaskWikiInfo
- * TaskWikiLink
- * TaskWikiMod
- * TaskWikiProjects
- * TaskWikiProjectsSummary
- * TaskWikiStart
- * TaskWikiStats
- * TaskWikiStop
- * TaskWikiTags
+* TaskWikiBurndown(Daily, Monthly, Weekly)
+* TaskWikiCalendar
+* TaskWikiChooseProject
+* TaskWikiChooseTag
+* TaskWikiDelete
+* TaskWikiGhistory(Annual, Monthly)
+* TaskWikiHistory(Annual, Monthly)
+* TaskWikiInfo
+* TaskWikiInspect
+* TaskWikiLink
+* TaskWikiMod
+* TaskWikiProjects
+* TaskWikiProjectsSummary
+* TaskWikiStart
+* TaskWikiStats
+* TaskWikiStop
+* TaskWikiTags
-### Planned features
-* Updating
- * Removals from dependency sets
+see more in doc/taskwiki.txt. After installing, run :helptags and then :he taskwiki
### Credits
-Inspired by vimwiki-tasks plugin.
+Authored by Tomas Babej
+
+Inspired by [vimwiki-tasks plugin](https://github.com/teranex/vimwiki-tasks).
+
+### Contributing
+
+Clone, fork, contribute and learn more at https://github.com/tbabej/taskwiki
+
+Good ideas, well formed bug reports and thoughtful pull-requests welcome.
+
+
diff --git a/doc/TaskWiki-demo.gif b/doc/TaskWiki-demo.gif
new file mode 100644
index 0000000..736a56b
Binary files /dev/null and b/doc/TaskWiki-demo.gif differ
diff --git a/doc/taskwiki.txt b/doc/taskwiki.txt
index e779ea0..e377f29 100644
--- a/doc/taskwiki.txt
+++ b/doc/taskwiki.txt
@@ -1,39 +1,52 @@
-*taskwiki.txt* Taskwarrior tasks in Vimwiki v0.7.5 ~
- _____ _ __ ___ _ _ ~
- a |_ _|_ _ ___| | _\ \ / (_) | _(_) a ~
- command-line | |/ _` / __| |/ /\ \ /\ / /| | |/ / | personal wiki ~
- todo list | | (_| \__ \ < \ V V / | | <| | for vim ~
- manager |_|\__,_|___/_|\_\ \_/\_/ |_|_|\_\_| ~
- ~
-=============================================================================
-CONTENTS
- 1. Introduction |taskwiki|
- 2. Prerequisites |taskwiki-prereq|
- 3. Installing |taskwiki-install|
- 4. Mapping |taskwiki-mapping|
- 5. Commands |taskwiki-commands|
- 6. Customization |taskwiki-customize|
- 7. Troubleshooting |taskwiki-trouble|
- 8. Contributing |taskwiki-contribute|
- 9. License |taskwiki-license|
+*taskwiki.txt* Taskwarrior tasks in Vimwiki v0.8.4 ~
+ _____ _ __ ___ _ _ ~
+ a |_ _|_ _ ___| | _\ \ / (_) | _(_) a ~
+ command-line | |/ _` / __| |/ /\ \ /\ / /| | |/ / | personal wiki ~
+ todo list | | (_| \__ \ < \ V V / | | <| | for vim ~
+ manager |_|\__,_|___/_|\_\ \_/\_/ |_|_|\_\_| ~
+ ~
+==============================================================================
+QUICK-REFERENCE -- use "t" and one of: -- *taskwiki-quickref*
+
+| a annotate | C calendar | Ga ghistory annual | p projects |
+| bd burndown daily | d done | hm history month | s summary |
+| bw burndown weekly | D delete | ha history annual | S stats |
+| bm burndown monthly | e edit | i (or ) info | t tags |
+| cp choose project | g grid | l back-link | + start |
+| cp choose tag | Gm ghistory month | m modify | - stop |
+
+==============================================================================
+CONTENTS *taskwiki-contents*
+
+ 1. Introduction |taskwiki|
+ 2. Prerequisites |taskwiki-prereq|
+ 3. Installing |taskwiki-install|
+ 4. Mapping |taskwiki-mapping|
+ 5. Commands |taskwiki-commands|
+ 6. Settings |taskwiki-settings|
+ 7. Troubleshooting |taskwiki-trouble|
+ 8. Contributing |taskwiki-contribute|
+ 9. Credits |taskwiki-credits|
+ 10. License |taskwiki-license|
=============================================================================
-INTRODUCTION
+1. INTRODUCTION *taskwiki*
-TaskWiki is a vim plugin that enhances vimwiki (another vim plugin) replacing
- vimwiki's Todo functionality with Taskwarrior tasks.
+TaskWiki is a vim plugin that enhances vimwiki (another vim plugin) by adding
+ Taskwarrior tasks, reports and commands, to Vimwiki's todo functionality.
Key Features:
-- ViewPorts: a vimwiki heading with a task query (filter) embedded, generates
+- ViewPorts: a vimwiki header with a task query (filter) embedded, generates
a corresponding list of tasks. These tasks can be modified and changes
- will be synced back to task data. A ViewPort heading looks like this:
- == Project Foo Tasks | project:foo | +bar ==
- title ^ filter ^ ^ user defaults
- The filter and defaults are concealed in normal mode.
+ will be synced back to task data. A ViewPort header looks like this:
- Defaults for new tasks added under a ViewPort are derived from the filter
+ == Project Foo Tasks | +PENDING project:foo | +bar pri:H ==
+ title ^^^ filter ^^^ ^^^ user defaults
+
+ title can be any text, and the filter elements are concealed in normal mode.
+
+ Defaults for new tasks added under a ViewPort are derived from the filter
(where possible) and from user-defaults (if any)
- User-defaults will be added to, and will override, filter-defaults.
Only simpler elements will work as defaults defaults to new tasks:
- attribute:value (project:foo)
- +tag
@@ -43,30 +56,41 @@ Key Features:
- nothing in parentheses (project:foo or project:bar)
- no negative tags (-foo)
- no virtual tags (+PENDING +TODAY +OVERDUE etc.)
- filter-defaults, so that any new tasks will be have these values.
+ User-defaults will be added to, and can override, filter-defaults.
+ To see ViewPort details, like defaults used, with cursor on VP header
- Individual Todos: tasks can be used anywhere in a vimwiki, looking like:
- * [ ] Install TaskWiki plugin
- and the task will be synced with the task data on saving.
+
+ * [ ] Install TaskWiki plugin
+ and when adding a new task, any other metadata can be added after "--" like
+ * [ ] test taskwiki todos and viewports -- proj:tw.wiki +foo due:tomorrow
+
+ Task are synced with the task data on file open and on saving. After sync,
+ all tasks end with a concealed uuid (eg. #541c5b57) don't edit this!
+
+ NOTE: vimwiki todos can still be used along side of taskwiki tasks, as long
+ as the leading character is "-" or "#." or "+" but not "*".
+ - [ ] This is a vimwiki todo (ignored by taskwiki)
- Task Info: hitting with the cursor over a task shows all task info.
- Reports: burndown, calendar, history, projects, summary, stats and tags
reports can all be invoked, opening in a split window.
-- Grid view: the TaskWikiGrid command will open a new buffer with a grid
+- Grid view: the :TaskWikiGrid command will open a new buffer with a grid
view of task details, of the nearest ViewPort (using vim-taskwarrior)
-- Back-links: The command TaskWikiLink will add an annotation to the selected
+- Back-links: The command :TaskWikiLink will add an annotation to the selected
task(s) with the ~/path/to/file.wiki
- Tests: TaskWiki is well tested in development to ensure data integrity.
**DISCLAIMER** This is free software, it comes with absolutely NO
warranty and no promise of fitness for any purpose! (back up your data!)
-=============================================================================
-PREREQUISITES
-This plugin requires:
+=============================================================================
+2. PREREQUISITES *taskwiki-prereq*
+
+This plugin requires:
- vim 7.4 or greater, with python bindings (use :version in vim, to check)
- vimwiki dev branch (https://github.com/vimwiki/vimwiki)
- taskwarrior 2.4.0+ (http://taskwarrior.org/download/)
@@ -75,86 +99,144 @@ This plugin requires:
and can be enhanced with:
- vim-plugin-AnsiEsc (https://github.com/powerman/vim-plugin-AnsiEsc) for color
- tagbar (https://github.com/majutsushi/tagbar) for taskwiki file navigation
-- vim-taskwarrior (https://github.com/farseer90718/vim-taskwarrior) for Grid
+- vim-taskwarrior (https://github.com/farseer90718/vim-taskwarrior) for grid
=============================================================================
-INSTALLING
+3. INSTALLING *taskwiki-install*
- plugins the vim way: http://vimdoc.sourceforge.net/htmldoc/usr_05.html#05.4
- plugins the easy way: https://github.com/tpope/vim-pathogen
- Other "vim plugin managers" will probably work, but have not been tested
+ Other "vim plugin managers" will probably work, but have not been tested
=============================================================================
-MAPPING
+4. MAPPING *taskwiki-mapping*
-none yet!
+n is mapped to show task info, VP details or follow vimwiki link
+ After editing a task in insert mode, starts a new task
+
+ Normal mode key mappings (those with "v" also work in visual mode)
+ t +
+vn a :TaskWikiAnnotate
+ n bd :TaskWikiBurndownDaily
+ n bw :TaskWikiBurndownWeekly
+ n bm :TaskWikiBurndownMonthly
+vn cp :TaskWikiChooseProject
+vn ct :TaskWikiChooseTag
+ n C :TaskWikiCalendar
+vn d :TaskWikiDone
+vn D :TaskWikiDelete
+vn e :TaskWikiEdit
+vn g :TaskWikiGrid
+ n Gm :TaskWikiGhistoryMonthly
+ n Ga :TaskWikiGhistoryAnnual
+ n hm :TaskWikiHistoryMonthly
+ n ha :TaskWikiHistoryAnnual
+vn i :TaskWikiInfo
+vn l :TaskWikiLink
+vn m :TaskWikiMod
+ n p :TaskWikiProjects
+ n s :TaskWikiProjectsSummary
+ n S :TaskWikiStats
+ n t :TaskWikiTags
+vn + :TaskWikiStart
+vn - :TaskWikiStop
=============================================================================
-COMMANDS
+5. COMMANDS *taskwiki-commands*
+
+-----------------------------------------------------------------------------
+Split reports commands (that open taskwarrior reports in a window split)
+
+*:TaskWikiBurndown(Daily, Monthly, Weekly) [args]
+ Opens a split window with the burndown report (close with or "q")
+
+*:TaskWikiCalendar [args]
+ Opens a split window with the calendar report (close with or "q")
+
+*:TaskWikiGhistory(Annual, Monthly) [args]
+ Opens a split window with the ghistory report (close with or "q")
+
+*:TaskWikiHistory(Annual, Monthly) [args]
+ Opens a split window with the history report (close with or "q")
+
+*:TaskWikiProjects [args]
+ Opens a vsplit window with the projects report (close with or "q")
+
+*:TaskWikiProjectsSummary [args]
+ Opens a vsplit window with the summary report (close with or "q")
+
+*:TaskWikiStats [args]
+ Opens a vsplit window with the stats report (close with or "q")
+
+*:TaskWikiTags [args]
+ Opens a vsplit window with the tags report (close with or "q")
+
+-----------------------------------------------------------------------------
+Commands that operate on tasks in the buffer
*:TaskWikiAnnotate
Opens a prompt to add annotation to selected task(s)
-*:TaskWikiBurndown(Daily, Monthly, Weekly)
- Opens a window with the burndown report (close with or "q")
-
-*:TaskWikiCalendar
- Opens a window with the calendar report (close with or "q")
+*:TaskWikiDone
+ Marks the completed task as done (status:completed)
*:TaskWikiDelete
Deletes the selected task(s)
-*:TaskWikiGhistory(Annual, Monthly)
- Opens a window with the ghistory report (close with or "q")
+*:TaskWikiEdit
+ Opens the task in vim, with all fields exposed for editing
*:TaskWikiGrid
Opens a new buffer with the selected ViewPort displayed as a grid
- (requires vim-taskwarrior plugin)
-
-*:TaskWikiHistory(Annual, Monthly)
- Opens a window with the history report (close with or "q")
+ (requires vim-taskwarrior plugin)
*:TaskWikiInfo
(or ) Opens a window with the info report of task under the cursor
("q" or again, closes the window)
+*:TaskWikiLink
+ Adds an annotation to selected task(s) with ~/path/to/file.wiki
+
+*:TaskWikiStart
+ "Starts" the selected task(s)
+
+*:TaskWikiStop
+ "Stops" the selected task(s)
+
+*:TaskWikiMod [mods]
+ Opens a prompt for task modification, for selected task(s)
+
+----------------------------------------------------------------------------
+Interactive commands
+
+*:TaskWikiChooseProject
+ Interactively choose project
+
+*:TaskWikiChooseTag
+ Interactively choose tag
+
+----------------------------------------------------------------------------
+Meta commands
+
*:TaskWikiInspect
(or ) Opens window with details of ViewPort under the cursor
("q" or again, closes the window)
-*:TaskWikiLink
- Adds an annotation to selected task(s) with ~/path/to/file.wiki
+=============================================================================
+6. SETTINGS *taskwiki-settings*
-*:TaskWikiMod
- Opens a prompt for task modification, for selected task(s)
-
-*:TaskWikiProjects
- Opens a window with the projects report (close with or "q")
-
-*:TaskWikiProjectsSummary
- Opens a window with the summary report (close with or "q")
-
-*:TaskWikiStart
- "Starts" the selected task(s)
-
-*:TaskWikiStats
- Opens a window with the stats report (close with or "q")
-
-*:TaskWikiStop
- "Stops" the selected task(s)
-
-*:TaskWikiTags
- Opens a window with the tags report (close with or "q")
+g:taskwiki_disable=
+ Disable taskwiki if ANY taskwiki_disable variable set (the "off" switch)
+
+g:taskwiki_measure_coverage (?)
+ Run the measure parts first, if desired
+
+g:taskwiki_tw_colors (?)
+ Enable the use of the current taskwarrior color theme
=============================================================================
-CUSTOMIZATION
-
-none yet!?
-
-=============================================================================
-TROUBLESHOOTING
-
-- Are requirements met?
+7. TROUBLESHOOTING *taskwiki-trouble*
+Are requirements met?
-Vim
-TaskWiki (this plugin)
-Taskwarrior
@@ -162,12 +244,19 @@ TROUBLESHOOTING
-vim-taskwarrior
=============================================================================
-CONTRIBUTIONS
+8. CONTRIBUTIONS *taskwiki-contribute*
Clone, fork, contribute and learn more at https://github.com/tbabej/taskwiki
-Good ideas, well formed bug reports and thoughtful pull-requests welcome.
+Good ideas, well formed bug reports and thoughtful pull-requests welcome.
=============================================================================
-LICENSE
+9. CREDITS *taskwiki-credits*
+
+Authored by Tomas Babej
+inspired by vimwiki-tasks
+
+=============================================================================
+10. LICENSE *taskwiki-license*
MIT?
+