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 b2af1d4388 docs: Enumerate and describe all the options
2015-08-26 21:39:01 +02:00

313 lines
12 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)
*:TaskWikiBurndown(Daily, Monthly, Weekly) [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")
*:TaskWikiGhistory(Annual, Monthly) [args]
Opens a split window with the ghistory report (close with <CR> or "q")
*:TaskWikiHistory(Annual, Monthly) [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*
MIT?
vim:tw=78:ts=8:ft=help
Reference in a new issue View git blame Copy permalink