*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|

=============================================================================
INTRODUCTION

TaskWiki is a vim plugin that enhances vimwiki (another vim plugin) replacing
    vimwiki's Todo functionality with Taskwarrior tasks. 

Key Features:
- ViewPorts: a vimwiki heading 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.

    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
	Complex filter elements, or dates, like these, will _not_ be used:
	    - nothing with attribute modifiers (project.not:foo)
	    - due: sched: wait: until: values (?)
	    - 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.

- 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.

- Task Info: hitting <CR> 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!)
=============================================================================
PREREQUISITES

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/)
- tasklib develop branch (https://github.com/tbabej/tasklib/tree/develop)

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

=============================================================================
INSTALLING

- 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 

=============================================================================
MAPPING

none yet!

=============================================================================
COMMANDS

*:TaskWikiAnnotate
    Opens a prompt to add annotation to selected task(s)

*:TaskWikiBurndown(Daily, Monthly, Weekly)
    Opens a window with the burndown report (close with <CR> or "q")

*:TaskWikiCalendar
    Opens a window with the calendar report (close with <CR> or "q")

*:TaskWikiDelete
    Deletes the selected task(s)

*:TaskWikiGhistory(Annual, Monthly)
    Opens a window with the ghistory report (close with <CR> or "q")

*: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 <CR> or "q")

*:TaskWikiInfo
    (or <CR>) Opens a window with the info report of task under the cursor
    ("q" or <CR> again, closes the window)

*:TaskWikiInspect
    (or <CR>) Opens window with details of ViewPort under the cursor
    ("q" or <CR> again, closes the window)

*:TaskWikiLink
    Adds an annotation to selected task(s) with ~/path/to/file.wiki

*:TaskWikiMod
    Opens a prompt for task modification, for selected task(s)

*:TaskWikiProjects
    Opens a window with the projects report (close with <CR> or "q")

*:TaskWikiProjectsSummary
    Opens a window with the summary report (close with <CR> or "q")

*:TaskWikiStart
    "Starts" the selected task(s) 

*:TaskWikiStats
    Opens a window with the stats report (close with <CR> or "q")

*:TaskWikiStop
    "Stops" the selected task(s) 

*:TaskWikiTags
    Opens a window with the tags report (close with <CR> or "q")

=============================================================================
CUSTOMIZATION

none yet!?

=============================================================================
TROUBLESHOOTING

- Are requirements met? 
	-Vim
	-TaskWiki (this plugin)
	-Taskwarrior
	-Tasklib
	-vim-taskwarrior

=============================================================================
CONTRIBUTIONS

Clone, fork, contribute and learn more at https://github.com/tbabej/taskwiki
Good ideas, well formed bug reports and thoughtful pull-requests welcome. 

=============================================================================
LICENSE

MIT?