tbabej/taskwiki
1
0
Fork 0
mirror of https://github.com/tbabej/taskwiki.git synced 2025-08-18 21:33:07 +02:00
Code Issues Projects Releases Packages Wiki Activity Actions
taskwiki/doc/taskwiki.txt
Tomas Babej c96b7eb2af docs: Add licence
2015-08-26 21:39:05 +02:00

339 lines
13 KiB
Text
Raw Blame History

*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 "<leader>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 <CR>) info | t tags |
| cp choose project | g grid | l back-link | + start |
| ct 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|
=============================================================================
1. INTRODUCTION *taskwiki*
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 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 header looks like this:
== 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)
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.)
User-defaults will be added to, and can override, filter-defaults.
To see ViewPort details, like defaults used, <CR> with cursor on VP header
- Individual Todos: tasks can be used anywhere in a vimwiki, looking like:
~ * [ ] 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 <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!)
=============================================================================
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/)
- 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
=============================================================================
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
=============================================================================
4. MAPPING *taskwiki-mapping*
n <CR> is mapped to show task info, VP details or follow vimwiki link
After editing a task in insert mode, <CR> starts a new task
Normal mode key mappings (those with "v" also work in visual mode)
<Leader>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|
=============================================================================
5. COMMANDS *taskwiki-commands*
-----------------------------------------------------------------------------
Split reports commands (that open taskwarrior reports in a window split)
*:TaskWikiBurndownDaily* [args]
*:TaskWikiBurndownWeekly* [args]
*:TaskWikiBurndownMonthly* [args]
Opens a split window with the burndown report (close with <CR> or "q")
*:TaskWikiCalendar* [args]
Opens a split window with the calendar report (close with <CR> or "q")
*:TaskWikiGhistoryMonthly* [args]
*:TaskWikiGhistoryAnnual* [args]
Opens a split window with the ghistory report (close with <CR> or "q")
*:TaskWikiHistoryMonthly* [args]
*:TaskWikiHistoryAnnual* [args]
Opens a split window with the history report (close with <CR> or "q")
*:TaskWikiProjects* [args]
Opens a vsplit window with the projects report (close with <CR> or "q")
*:TaskWikiProjectsSummary* [args]
Opens a vsplit window with the summary report (close with <CR> or "q")
*:TaskWikiStats* [args]
Opens a vsplit window with the stats report (close with <CR> or "q")
*:TaskWikiTags* [args]
Opens a vsplit window with the tags report (close with <CR> or "q")
-----------------------------------------------------------------------------
Commands that operate on tasks in the buffer
*:TaskWikiAnnotate*
Opens a prompt to add annotation to selected task(s)
*:TaskWikiDone*
Marks the completed task as done (status:completed)
*:TaskWikiDelete*
Deletes the selected task(s)
*: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)
*:TaskWikiInfo*
(or <CR>) Opens a window with the info report of task under the cursor
("q" or <CR> 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 <CR>) Opens window with details of ViewPort under the cursor
("q" or <CR> again, closes the window)
=============================================================================
6. SETTINGS *taskwiki-settings*
*taskwiki_taskrc_location*
The location of the taskrc file used by taskwiki. Defaults to ~/.taskrc.
*taskwiki_data_location*
The location of the data directory for taskwarrior data used by taskwiki.
Defaults to ~/.task.
*taskwiki_extra_warriors*
A dictionary containing alternative taskwarrior instance definitions.
A key for any alternative taskwarrior definition must be a single,
uppercase letter. Value is dictionary containing respective
data_location and taskrc_location overrides.
Example:
let g:taskwiki_extra_warriors={'H': {'data_location': '/home/tbabej/.habit/', 'taskrc_location': '/home/tbabej/.habitrc'}
Specifying particular extra warrior in the viewport can be done using
#[KEY] at the end of the viewport definition, in this case:
~ === Home habits | project:Home #H ===
*taskwiki_sort_order*
The default sort order used to sort the tasks within viewports. Defaults
to 'due+,pri-,project+'. Expects a comma-separated list of attributes,
optionally followed by + or - to denote the increasing or decreasing
order, respectively.
*taskwiki_sort_orders*
The sort order can also be customized per viewport. This configuration
variable stores a dictionary with the alternative sort order definitions,
each indexed by a uppercase letter.
Example:
let g:taskwiki_sort_orders={"T": "project+,due-"}
Specifying a particular sort order in the viewport can be achieved
using $[KEY] at the end of the viewport definition, in this case:
~ === Work tasks by decreased due, grouped by project | project:Work $T ===
*taskwiki_split_max_width*
Use to limit the width of any vertical split created by taskwiki.
*taskwiki_split_max_height*
Use to limit the height of any vertical split created by taskwiki.
*taskwiki_source_tw_colors*
If set, taskwiki will try to use the same colors for task highlighting
as those defined in taskwarrior.
*taskwiki_disable*
Setting any value for this variable will disable taskwiki.
*taskwiki_measure_coverage*
Development only. Uses python-coverage to track how much of the code
is covered by tests.
=============================================================================
7. TROUBLESHOOTING *taskwiki-trouble*
Are requirements met?
-Vim
-TaskWiki (this plugin)
-Taskwarrior
-Tasklib
-vim-taskwarrior
=============================================================================
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.
=============================================================================
9. CREDITS *taskwiki-credits*
Authored by Tomas Babej
inspired by vimwiki-tasks
=============================================================================
10. LICENSE *taskwiki-license*
Copyright 2014-2015 Tomas Babej
http://github.com/tbabej/taskwiki
This software is released under MIT licence.
Permission is hereby granted, free of charge, to any person obtaining
a copy of this software and associated documentation files (the
"Software"), to deal in the Software without restriction, including
without limitation the rights to use, copy, modify, merge, publish,
distribute, sublicense, and/or sell copies of the Software, and to
permit persons to whom the Software is furnished to do so, subject to
the following conditions:
The above copyright notice and this permission notice shall be
included in all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
vim:tw=78:ts=8:ft=help
Reference in a new issue View git blame Copy permalink