
VITtk Tutorial v1.1
-------------------

First, create a "sandbox" to play in...

 $ mkdir /tmp/.task-test
 $ task rc.data.location=/tmp/.task-test add Mop the kitchen floor
 $ task rc.data.location=/tmp/.task-test add Clean the kitchen cabinets
 $ task rc.data.location=/tmp/.task-test add Mow the Lawn
 $ task rc.data.location=/tmp/.task-test add Water the garden

Now start with vittk in that sandbox, and capture a debug log...

 $ vittk -ds /tmp/.task-test -d > /tmp/vittk-debug.log

In another terminal window, you can watch the actions VITtk takes by viewing
the "audit" log...

 $ tail -f /tmp/vittk-$USER.log

Now for the actual tutorial.  Let's "add" a task... 

 a Take out the garbage\n

...you don't need to type the <space> after 'a'--it's just typeset that way so
it's easy to read... and '\n' means hit the <enter> aka <return> key, because
a lot of the time you don't need to hit <enter> when doing commands in VITtk.

It's a sunny day outside.  Suppose you stepped away from your computer
and mowed the lawn.  Let's mark that task as "done"... use the 'j' and 'k'
(and/or <DownArrow> and <UpArrow>) keys to scroll to that task and do...

 d

Notice how the "report" ("task ls" output) no longer displays the task you
just marked done--it only displays to-do items ("pending tasks".)

Now suppose the information about watering the garden is incomplete: you also
want to remember to water the flower boxes.  Let's "annotate" the task with
that information...

 scroll to "Water the garden"
 A Don't forget the flower boxes!

Notice how you don't need to escape the single quote character or the 
exclamation mark with backslash characters: VITtk takes care of that for you.

You can set priorities with 'l' for "low", 'm' for "medium", 'h' for "high"
and 'n' for "none".  The garden plants are dying because it's sunny out and
they haven't been watered in a long time.  Let's assign the "water the garden"
task the priority high...

 scroll to "Water the garden"
 h

Notice how this high priority task "bubbles up" to the top of our to-do list.

Our tasks really have two types: some are "Yardwork" and some are "Housework".
So let's organize them by setting their "project" attribute...

 scroll to "Water the garden"
 p Yardwork\n
 scroll to "Take out the garbage"
 p Housework\n
 scroll to "Mop the kitchen floor"
 p Housework\n

There's another way to set a task's project.  In fact, it's a generic way to
execute almost *any* task command.  Not surprisingly, it's called the VITtk
"command line" and you get there by typing ':' (the colon key).  It's like
using the "task" command, but without the "task" part...

 :2 project:Housework\n

Now we're better organized, but the garbage is beginning to stink.  Take
out the garbage and mark it's task "done"...

 scroll to "Take out the garbage"
 d

Eventually you might end up with hundreds of tasks, so you'll want to filter
out all the tasks except the ones you want to look at.  Let's try that--let's
view only tasks which contain the description "kitchen" with the "filter" 
command...

 f kitchen\n

Notice how the top line reads "task ls kitchen".  That's the indicator of 
your "current view".

The other tasks can viewed via their project setting, so let's exit
the filtered view (go back to the default view, to be exact) and view the
"Yardwork" project...

 x
 :ls proj:Yardwork\n

There's one big concept left to discuss: the influence of the VI Editor aka
"vi".  VITtk emulates vi because vi is a very powerful way to edit text,
and thus VITtk is a very powerful way to use Taskwarrior.  

The vi editor has two modes: 1) command mode and 2) text entry (insert) mode.
Once you start inserting text with vi, you exit insert mode (to command mode)
by hitting <enter> or <esc> keys.  The <enter> key accepts the insertion
and <esc> ignores it--it throws it away.  This is also true in VITtk.
This demonstrates how you can abort the addition of a task...

 a Clean the--oh, nevermind<esc>

Also, many of the vi commands that navigate around the screen (in command
mode) also work within VITtk...

 G              go to last task
 H              go to window top (high)
 k or Up        task up
 j or Down      task down
 L              go to window bottom (low)
 M              go to window middle
 ^b or PgUp     page up
 ^f or PgDn     page down
 ^l             refresh report output

...note that the use of some of these commands may be a little confusing
when you don't have many tasks listed or you haven't used vi much.

Eventually you might do other neat things with Taskwarrior, and you'll
probably want to use VITtk to view everything about a given task.  You can
view all the attributes of a task (except the revision history) in no less
than three ways...

 \n      ...display "task info" for the currently selected task
 i       ...ditto
 :N\n    ...display "task info" for task "N"

Note that you need to use the <esc> key to get from the "info command" mode
(i.e. viewing a task's info) back to the "report command" mode (i.e. viewing
a task report.)

We're almost done, but let's review the situation--let's look at the projects,
our progress, and the over-all statistics of our tasks:

 :projects 
 :summary 
 :stat

At this point it's probably a good idea to re-read the vittk help information!
(Sorry, the "in-line" help screen hasn't been implemented yet.)  

 $ vittk -h

Please backup your real task data before you use vittk on it...

 $ mkdir ~/.task.BAK
 $ cp ~/.task/* ~/.task.BAK

Don't hesitate to send along any questions, comments or whatever. 

steve rader
<rader@hep.wisc.edu>
--


